{"id":26766073,"url":"https://github.com/ucl/blender_randomiser","last_synced_at":"2025-04-15T12:35:58.025Z","repository":{"id":201026926,"uuid":"590426015","full_name":"UCL/Blender_Randomiser","owner":"UCL","description":null,"archived":false,"fork":false,"pushed_at":"2025-01-22T11:47:48.000Z","size":1895,"stargazers_count":2,"open_issues_count":13,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-28T20:18:57.339Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UCL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-18T11:45:25.000Z","updated_at":"2025-01-22T11:47:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"d4abeabc-d959-417c-8638-1af05bae1cbf","html_url":"https://github.com/UCL/Blender_Randomiser","commit_stats":null,"previous_names":["ucl/blender_randomiser"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UCL%2FBlender_Randomiser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UCL%2FBlender_Randomiser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UCL%2FBlender_Randomiser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UCL%2FBlender_Randomiser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UCL","download_url":"https://codeload.github.com/UCL/Blender_Randomiser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249072821,"owners_count":21208253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-28T20:19:01.872Z","updated_at":"2025-04-15T12:35:58.002Z","avatar_url":"https://github.com/UCL.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Blender_Randomiser\n\n\nBlender 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:\n - Manually setting the bounds in the UI Randomiser panel located in the Geometry Nodes space\n - Using an input `.json` [file](/input_bounds.json) to [set the bounds from the command line](/docs/input_output.md)\n\n\n   The add-on panel called \"Randomiser\" is located in the Geometry Nodes space within Blender:\n   ![Addon_location](/docs/images/Addon_location.png)\n\n\n## Purpose\n\nThe 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:\n - **Camera transforms** (location and Euler rotation with toggle for randomising in absolute or relative i.e. delta terms) ![camera_transforms](/docs/images/Transforms_panel.png)\n - **Geometry** ([see further details](/docs/Materials_geometry_panel.md))\n - **Materials**([see further details](/docs/Materials_geometry_panel.md))\n\nIn the add-on, these three components appear as separate UI panels.\n\n 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))\n\n  Other functionality includes:\n   - Selection toggle for including/excluding individual properties of the panel in the randomisation\n   - Possibility of setting a randomisation seed for reproducibility\n   - Capability to randomise the desired properties at every frame of an animation\n   - [Save Parameter panel](/docs/input_output.md) with outputs saved to `.json` [file](/output_randomisations_per_frame1697116725.310647.json) with a timestamp\n\n\n ## Installation via command line\n1. First, clone the repository in your desired directory\n```\ngit clone https://github.com/UCL/Blender_Randomiser.git\n```\n2. Launch a terminal at the cloned directory\n    - You should be at the `Blender_Randomiser` directory\n3. Run the following bash script:\n    ```\n    sh install_randomiser.sh\n    ```\n    - 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.\n    - 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)\n\n\u003e [!NOTE]\n\u003e  `source ~/.bash_profile` is used in the bash script to create an alias for blender with the following line in the bash_profile:\n\u003e `alias blender=/Applications/Blender.app/Contents/MacOS/Blender`\n\n**Advanced Usage**\n\n\u003e  In step 3, run the [randomisation_seed.sh](/randomisation_seed.sh) bash script instead which has optional inputs:\n\u003e - `--seed 32` which is an input to Blender\n\u003e - `--input ./input_bounds.json` (input to `install_and_enable_addons.py`)\n\u003e - `--output ./output_randomisations_per_frame1697116725.310647.json` (input to `install_and_enable_addons.py`)\n\nAlternatively, install [manually](/docs/Install_addon_manually.md) via Blender settings\n\n ## License and copyright\n\n [BSD 3-Clause License](/LICENSE)\n\n ## Testing\n\n 1. Launch a terminal at the cloned directory\n    - You should be at the `Blender_Randomiser` directory\n 2. Run `pytest` or `python -m pytest --blender-executable /Applications/Blender.app/Contents/MacOS/Blender`\n    - This will run our [testing script](/tests/test_integration/test_installing_and_enabling.py) which currently tests the camera transforms, materials and geometry panels.\n\n\n\u003e [!NOTE]\nThe 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.\n\n**Installing Pytest in Python**\n\nThe following steps were needed to install these dependencies (tested in MacOS only):\n```\n# create and activate conda environment:\nconda create -n blender-dev python=3.10 -y\nconda activate blender-dev\n\n# install pytest-blender:\npip install pytest-blender\npip install pytest-cov\n\n# Get path to the Python interpreter that ships with Blender - this may take a long time:\nblender_python=\"$(pytest-blender)\"\n\n# from the `Blender_Randomiser` directory, install the randomiser package with dev dependencies by running:\n$blender_python -m pip install \".[dev]\"\n\n#Run pytest:\npython -m pytest tests\n\n## ~/.local/bin may need to be added to path\n```\n\n**Installing Pytest in Blender's Python**\n\nAn easy way to install these dependencies (tested in Linux only) is to run the following code in [Blender's Python scripting window](https://docs.blender.org/api/current/info_quickstart.html#running-scripts):\n```\nimport pip\npip.main([\"install\", \"pytest\", \"--user\"])\npip.main([\"install\", \"pytest-cov\", \"--user\"])\npip.main([\"install\", \"pytest-blender\", \"--user\"])\n```\n\nThen outside of Blender, run the following command:\n```\n\u003cpath_to_blender_python\u003e -m pytest --blender-executable \u003cpath-to-blender-executable\u003e\n```\n\n ## Contributions\n\n Please see [Dev Notes](./docs/Dev_notes.md) if you wish to contribute. Feel free to submit suggestions via issues and/or PRs.\n\n It can be helpful to use different `.blend` files for prototyping as it can preload certain features you're testing.\n\n There are a few outstanding issues for enhancements:\n - Not able to currently export materials colour default value for save params button\n - Materials colour min-max can only be set to the same values in the 4D matrix using the [input file](/input_bounds.json)\n - No functionality for reading in min-max input boundaries for user defined panel\n - Not able to currently handle an empty UIlist in the user defined panel which causes issues for other funtionality in the add-on (which are resolved by adding at least one UD prop to UIlist)\n - Can randomise all panels and save the output parameters, however the functionality to toggle on/off selection of individual parameters is only available for camera transforms and user defined properties currently, but not geometry and materials panels where all these properties will be randomised and exported when this functionality is used.\n - General refactoring for repeated code for example [for the geometry and materials issue mentioned above](/randomiser/utils/list_props_to_randomise.py)\n\n\n ## Authors\n\n[Tom Dowrick](https://github.com/tdowrick)\n\n[Ruaridh Gollifer](https://github.com/ruaridhg)\n\n[Sofía Miñano](https://github.com/sfmig)\n\n[Harvey Mannering](https://github.com/harveymannering)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fucl%2Fblender_randomiser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fucl%2Fblender_randomiser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fucl%2Fblender_randomiser/lists"}