UCL · ruaridhg · Oct 18, 2023 · Oct 16, 2023 · Oct 16, 2023 · Oct 16, 2023
diff --git a/README.md b/README.md
@@ -1,39 +1,80 @@
 # Blender_Randomiser
 
-## Installation
-First, clone the repository in your desired directory
+
+Blender Randomiser is a Blender add-on that allows different scene properties to be randomised between some minimum and maximum bounds. The bounds can be defined 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](/docs/input_output.md)
+
+## Purpose
+
+The add-on was originally developed to render a highly diverse and (near) photo-realistic synthetic dataset of laparoscopic surgery camera views. To replicate the different camera positions used in surgery as well as the shape and appearance of the tissues involved with surgery, we focused on three main components to randomise:
+ - **Camera transforms** (location and Euler rotation with toggle for randomising in absolute or relative i.e. delta terms)
+ - **Geometry** ([see further details](/docs/Materials_geometry_panel.md))
+ - **Materials**([see further details](/docs/Materials_geometry_panel.md))
+
+In the add-on, these three components appear as separate UI panels.
+
+ Additionally, there is a **user-defined properties** panel where the user can specify the full Python path of a property to randomise.  When adding a user-defined property, a subpanel will be created to define its min and max bounds. Certain examples will and won't work (see [user-defined examples](/docs/user_defined_panel.md))
+
+  Other functionality includes:
+   - Selection toggle for including/excluding individual properties of the panel in the randomisation
+   - Possibility of setting a randomisation seed for reproducibility
+   - Capability to randomise the desired properties at every frame of an animation
+   - [Save Parameter panel](/docs/input_output.md) with outputs saved to `.json` [file](/output_randomisations_per_frame1697116725.310647.json) with a timestamp
+
+
+ ## Installation via command line
+1. 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
+2. Launch a terminal at the cloned directory
     - You should be at the `Blender_Randomiser` directory
-2. Run the following bash script:
+3. Run the following bash script:
     ```
     sh install_randomiser.sh
     ```
     - 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)
+    - The `install_and_enable_addons.py` script installs and enables any add-ons that are passed as command line arguments (add-ons can be passed as a path to a single Python file, or as a zip file)
+
+> **Advanced Usage**
+>  In step 3, run the [randomisation_seed.sh](/randomisation_seed.sh) bash script instead which has optional inputs:
+> - `--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`)
+
+Alternatively, install [manually](/docs/Install_addon_manually.md) via Blender settings
+
+ ## License and copyright
+
+ [BSD 3-Clause License](/LICENSE)
+
+ ## Testing
+
+ 1. Launch a terminal at the cloned directory
+    - You should be at the `Blender_Randomiser` directory
+ 2. Run `pytest` or `python -m pytest --blender-executable /Applications/Blender.app/Contents/MacOS/Blender`
+    - This will run our [testing script](/tests/test_integration/test_installing_and_enabling.py) which currently tests the camera transforms, materials and geometry panels.
+
+
+> [!NOTE]
+>  Only relevant if you are wanting to run the tests.
+> The tests make use of the [pytest-blender plugin](https://github.com/mondeja/pytest-blender#pytest-blender), which has `pytest` and other packages as dependencies (e.g. `pytest-cov`). These need to be installed in the site-packages directory of Blender's Python. The pytest-blender repo provides some guidance for this [here](https://github.com/mondeja/pytest-blender#usage). It is important to make sure you use Blender's Python interpreter and Blender's pip when installing `pytest` and its dependencies. Below are some tips on how to do this in Linux and MacOS.
+
+> **Linux**
+>  An easy way to install these dependencies correctly in Linux is to run the following code in [Blender's Python scripting window](https://docs.blender.org/api/current/info_quickstart.html):
+> `import pip `
+`pip.main(["install", "pytest", "--user"])`
+`pip.main(["install", "pytest-cov", "--user"])`
+`pip.main(["install", "pytest-blender", "--user"])`
+
+
+> **MacOS**
+>  The following steps were needed to install these dependencies correctly 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
+
+ ## Contributions
+
+ Please see [Dev Notes](./docs/Dev_notes.md) if you wish to contribute. Feel free to submit suggestions via issues and/or PRs.
diff --git a/Dev notes.md → docs/Dev_notes.md b/Dev notes.md → docs/Dev_notes.md
@@ -122,17 +122,13 @@ 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.*
 
 
 Addons are saved into one of (not sure why would it be one or the other)
 ```
     ['/Applications/Blender.app/Contents/Resources/3.4/scripts/addons',
-    '/Users/sofia/Library/Application Support/Blender/3.4/scripts/addons',
+    '/Users/user_account/Library/Application Support/Blender/3.4/scripts/addons',
     '/Applications/Blender.app/Contents/Resources/3.4/scripts/addons_contrib']
 ```
 
@@ -149,28 +145,15 @@ 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
-from Sofia & Ruaridh, see [here](https://hackmd.io/-e8g50WRTPSH8XeEaNIqlw#)
-(we both have access and can give access to others).
-
-Includes description of work done on the first TI, next steps and some gotchas.
 
 ---
 
 ## Other notes on Python scripting in Blender
 
+From experience the easiest way to work with Blender add-ons is by loading scripts containing snippets of code you want to test in [Blender's Python scripting window](https://docs.blender.org/api/current/info_quickstart.html) at the same time as your add-on/panel to allow interaction of your code with your add-on and to allow access to the Blender scene properties. Alternatively, there are other options to debug and inspect variables (see below).
 
 ### To inspect variables / debug:
+
 - #### Option 1:  Use 'code' module
     Works in Python interactive terminal in Blender and in Windows terminal). See further info in [docs](https://docs.blender.org/api/2.81/info_tips_and_tricks.html#drop-into-a-python-interpreter-in-your-script). For me, pdb works if run from terminal but not with Python console in Blender
     ```

diff --git a/docs/Install_addon_manually.md b/docs/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]
+> - 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
diff --git a/docs/Materials_geometry_panel.md b/docs/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.
diff --git a/docs/README.md b/docs/README.md
diff --git a/docs/_config.yml b/docs/_config.yml