Adding docs to README

README.md

@@ -1,33 +1,42 @@
 # Blender_Randomiser
 
-## Installation
+
+Blender Randomiser is a Blender add-on that allows different Blender properties to be randomised between minimum and maximum bounds. This can be achieved either by:
+ - Manually setting the bounds in the UI Randomiser panel located in the Geometry Nodes space
+ - Using an input `.json` [file](/input_bounds.json) to [set the bounds from the command line](/doc/input_output.md)
+
+## Purpose
+
+The original and main use case of this add-on is for rendering synthetic (near) photo-realstic data for laparoscopic surgery, with a view to generating large scale labelled data sets for ML applications in surgery. With that context to replicate the different camera positions used in surgery as well as the shape and appearance of the tissues involved with surgery, the three main components (contained with separate UI panels) to be randomised are:
+ - **Camera transforms** (location and Euler rotation with toggle for randomising in absolute or relative i.e. delta terms)
+ - [**Geometry**](/doc/Materials_geometry_panel.md)
+ - [**Materials**](/doc/Materials_geometry_panel.md)
+
+ Additionally, there is a **user defined properties** panel where the user can specify the full path of a property they want to randomised and it will create a subpanel for each of these properties with min-max bounds. Examples include:
+  - bpy.data.objects["Cube"].location (Float 3D)
+  - bpy.context.scene.frame_current (int 1D)
+  - bpy.data.objects["Sphere"].scale (Float 3D)
+  - bpy.data.objects["Cube"].collision.absorption (Float 1D)
+  - bpy.data.cameras["Camera"].dof.aperture_fstop (Float 1D)
+  - bpy.data.objects["Cube"].rotation_euler (Euler)
+
+  It should be noted that bpy.data.objects["Cube"].location[0] or bpy.data.cameras["Camera"].location[0] will throw an error if trying to add to the UD panel. However, bpy.data.objects["Cube"].location will work fine and if you only want to change the x-location then you can leave the y-/z-location bounds as 0 (min) to 0 (max) and the Cube won't be moved in those directions.
+
+  Another example that will not work is if the object has a '.' in the middle of the name i.e. "Cube.001" so please remove this if you want to have multiple cubes in your scene.
+
+  Other functionality includes:
+   - Toggle on/off button for including/excluding each property in the randomisation
+   - Seed panel to set the random seed
+   - Randomise properties per frame
+   - [Save Parameter panel](/doc/input_output.md) with outputs saved to `.json` [file](/output_randomisations_per_frame1697116725.310647.json) with a timestamp
+
+
+ ## Installation
 First, clone the repository in your desired directory
 ```
 git clone https://github.com/UCL/Blender_Randomiser.git
 ```
 
-### To install via Blender settings
-1. Zip the following directory:
-    `Blender_Randomiser/randomiser/`
-2. Launch Blender
-3. Navigate to Edit > Preferences
-4. On the left-hand side panel, select 'Add-ons'
-5. On the top-right select 'Install an add-on'
-6. Browse to select the randomiser.zip file.
-    - In the background, Blender will copy the file to the add-ons folder and unzip it
-    - In MacOS, this add-on directory is usually located at:
-        `/Users/user/Library/Application Support/Blender/3.4/scripts/addons`
-    (see [Blender directory layout](https://docs.blender.org/manual/en/latest/advanced/blender_directory_layout.html) for further details)
-
-7. Click on the checkbox next to the installed add-on to enable it.
-    - The add-on can be found by searching for 'randomisation' in the top right search bar.
-    - Before searching, note that the checkbox to show enabled add-ons only ('Enabled Add-ons Only') may be selected!
-
-Note that:
-- if you install an add-on, it will overwrite any pre-existing add-on with the same name.
-- Blender will only have access to the add-ons copied to any of the add-ons directories (see [Blender directory layout](https://docs.blender.org/manual/en/latest/advanced/blender_directory_layout.html)).
-- Remember that if you modify the code, you will need to create a new zip file with the latest version and repeat steps 1-7
-
 ## To install via command line
 1. Launch a terminal at the cloned directory
     - You should be at the `Blender_Randomiser` directory
@@ -37,3 +46,67 @@ Note that:
     ```
     - This will zip the `randomiser` subdirectory, open the `sample.blend` file with Blender, and use Blender's Python interpreter to execute the `install_and_enable_addons.py` script.
     - The `install_and_enable_addons.py` script installs and enables any add-ons that are passed as command line arguments (add-ons can be one Python file or a zip file)
+
+Alternatively, install [manually](/doc/Install_addon_manually.md) via Blender settings
+
+## To install via command line with additional inputs
+
+For step 2 above, run the following bash script instead:
+
+    sh install_randomiser.sh
+
+This will follow the same steps as above, but there are optional inputs as well:
+ - `--seed 32` which is an input to Blender
+ - `--input ./input_bounds.json` (input to `install_and_enable_addons.py`)
+ - `--output ./output_randomisations_per_frame1697116725.310647.json` (input to `install_and_enable_addons.py`)
+
+## Learning and tutorials
+
+[Add-on tutorial from docs](https://docs.blender.org/manual/en/3.4/advanced/scripting/addon_tutorial.html)
+
+[Developer documentation: Python](https://wiki.blender.org/wiki/Python)
+
+
+ ## License and copyright
+
+ [BSD 3-Clause License](/LICENSE)
+
+ ## Testing
+
+ [Testing script](/tests/test_integration/test_installing_and_enabling.py) which used [pytest-blender plugin](https://github.com/mondeja/pytest-blender#pytest-blender)
+
+ To use the plugin, you need to install `pytest` and all other dependencies used in testing (`pytest-cov`) in the site-packages of Blender's Python. The repo provides some guidance for this [here](https://github.com/mondeja/pytest-blender#usage). It is important to make sure you use the correct Python interpreter and pip (Blender's ones) when installing `pytest` and `pytest-cov`.
+
+ #### Linux:
+ Running the following code in a script within Blender:
+
+`import pip `
+
+`pip.main(["install", "pytest", "--user"])`
+
+`pip.main(["install", "pytest-cov", "--user"])`
+
+`pip.main(["install", "pytest-blender", "--user"])`
+
+
+ #### MacOS:
+
+The following steps were need on MacOS:
+ - `get-pip.py` downloaded (this step may not be needed since newer versions of Blender have pip installed already in the Blender python)
+ - Changing Mac permissions to grant full disk access from where you're running pytest i.e. VS code or terminal
+ - `/Applications/Blender.app/Contents/Resources/3.4/python/bin/python3.10 -m pip install pytest -t "/Applications/Blender.app/Contents/Resources/3.4/python/lib/python3.10/site-packages"` the target flag -t makes sure that the installation ends up in the correct place
+
+
+ ### Running Tests
+
+ Run `pytest` on the CLI within the project folder to test the camera transforms, materials and geometry panels as well as testing the `.blend` file loads, the add-on is installed and enabled and the randomising works per frame and with the seed set.
+
+ N.B. Alternative approach would be to use [Blender as a python module](https://wiki.blender.org/wiki/Building_Blender/Other/BlenderAsPyModule), but the only pytest-blender plugin approach is implemented in this repo.
+
+
+ ## Dev notes
+
+ Please see [Dev Notes](./doc/Dev_notes.md)
+
+
+ ## Contributions

Dev notes.md → doc/Dev_notes.md

@@ -122,10 +122,6 @@ with open(filepath, 'rb') as file:
 ## Add-ons
 
 
-[Add-on tutorial from docs](https://docs.blender.org/manual/en/3.4/advanced/scripting/addon_tutorial.html)
-
-[Developer documentation: Python](https://wiki.blender.org/wiki/Python)
-
 *An add-on is simply a Python module with some additional requirements so Blender can display it in a list with useful information.*
 
 
@@ -149,14 +145,7 @@ To enable an already installed add-on from the CLI:
 
 [Accepted space-regions combinations](https://blender.stackexchange.com/a/97268)
 
-## Testing
-[PR 62](https://github.com/UCL/Blender_Randomiser/pull/62) is a first attempt at testing with Blender's Python interpreter.
-
-I used this [pytest-blender plugin](https://github.com/mondeja/pytest-blender#pytest-blender), which seems to have very useful fixtures and also provides some steps towards CI.
-
-To use the plugin, we need to install `pytest` and all other dependencies used in testing (`pytest-cov` mainly) in the site-packages of Blender's Python. The repo provides some guidance for this [here](https://github.com/mondeja/pytest-blender#usage). It is important to make sure you use the correct Python interpreter and pip (Blender's ones) when installing `pytest` and `pytest-cov`.
 
-I think an alternative approach would be to use [Blender as a python module](https://wiki.blender.org/wiki/Building_Blender/Other/BlenderAsPyModule), but the pytest-blender plugin approach seems easier.
 
 
 ## Handover notes 6/6/2023

doc/Install_addon_manually.md

@@ -0,0 +1,21 @@
+### To install via Blender settings
+1. Zip the following directory:
+    `Blender_Randomiser/randomiser/`
+2. Launch Blender
+3. Navigate to Edit > Preferences
+4. On the left-hand side panel, select 'Add-ons'
+5. On the top-right select 'Install an add-on'
+6. Browse to select the randomiser.zip file.
+    - In the background, Blender will copy the file to the add-ons folder and unzip it
+    - In MacOS, this add-on directory is usually located at:
+        `/Users/user/Library/Application Support/Blender/3.4/scripts/addons`
+    (see [Blender directory layout](https://docs.blender.org/manual/en/latest/advanced/blender_directory_layout.html) for further details)
+
+7. Click on the checkbox next to the installed add-on to enable it.
+    - The add-on can be found by searching for 'randomisation' in the top right search bar.
+    - Before searching, note that the checkbox to show enabled add-ons only ('Enabled Add-ons Only') may be selected!
+
+Note that:
+- if you install an add-on, it will overwrite any pre-existing add-on with the same name.
+- Blender will only have access to the add-ons copied to any of the add-ons directories (see [Blender directory layout](https://docs.blender.org/manual/en/latest/advanced/blender_directory_layout.html)).
+- Remember that if you modify the code, you will need to create a new zip file with the latest version and repeat steps 1-7

doc/Materials_geometry_panel.md

@@ -0,0 +1,21 @@
+## Materials
+- A panel to randomise properties relative to the material nodes:
+    - nodes and node groups are aggregated based on the material they belong to.
+    - only materials with use_nodes=True are added to the panel. By default, use_nodes is set to True, but this is a convenient way to add/remove materials from the panel.
+    - If new nodes that are marked for randomisation are added or deleted, these appear automatically in the randomisation panel.
+    - Recursive node groups are accepted.
+    - Convenience functions were added to visualise the node graph per material, constrain the min and max values for the randomisation and unselect nodes that are candidates for randomisation but are unlinked.
+
+### When is a new material slot automatically added?
+Clicking the name of the material in a subpanel header shows its node graph. If a material is clicked and it has no slot assigned, a new slot will be created for it
+
+
+
+## Geometry
+- A panel to randomise properties relative to the geometry nodes:
+    - nodes are aggregated based on the node group they belong to.
+    - Same functionalities as in material nodes panel: new or deleted nodes are automatically added, recursive node groups are accepted,etc.
+
+
+### When is a new modifier automatically added to an object’s geometry?
+If a geometry node group is not inside another node group, and is not linked to a modifier of the currently active object, a new modifier is created and the geometry node group is linked to it.

doc/input_output.md

@@ -0,0 +1,13 @@
+## Min-max bounds via input file
+[Example input .json file](/input_bounds.json) for setting bounds. Currently can be used for setting camera transforms, materials and geometry min-max boundaries. Could be extended in the future to use parameter names from the [output .json file](/output_randomisations_per_frame1697116725.310647.json).
+
+The input file is read in as a dictionary with the key names following the pattern of "Values" + "material or geometry name" + "socket name":
+ - "Values Geometry Nodes.001RandomSize.001"
+ - "Values MaterialRandomMetallic"
+
+
+## Save parameter outputs button
+
+In this panel, you can set how many frames you want to randomise before clicking the Save Parameter Outputs button. This will randomise all the variables that are toggled on for randomisation and then a dictionary of parameter values are saved to an output .json file.
+
+Due to the layout of geometry/materials panels, they are saved as a dictionary within the overall dictionary.