- Author: Qianqian Fang (q.fang at neu.edu) and Yuxuan Zhang (zhang.yuxuan1 at northeastern.edu)
- License: GNU General Public License version 3 (GPLv3)
- Version: v2022 (v0.6)
- Website: http://mcx.space/BlenderPhotonics
- Acknowledgement: This project is funded by NIH awards R01-GM114365 and U24-NS124027
BlenderPhotonics is a Blender addon to enable 3-D tetrahedral mesh generation (via Iso2Mesh)
and mesh-based Monte Carlo (MMC) photon simulations (via MMCLAB) inside
the Blender environment. Both Iso2Mesh and MMCLAB are executed in GNU Octave, which interoperates with Blender
oct2py module and the
bpy Python interface.
BlenderPhotonics supports three processing workflows: 1) converting 3-D Blender objects to region-labeled tetrahedral meshes and triangular surfaces; 2) converting a volumetric image stored in a NIfTI file to a multi-labeled tetrahedral mesh, and 3) defining optical properties of each region and a light source to execute and render MMC simulation results. Each feature can be achieved via a single click on the GUI.
BlenderPhotonics combines the interactive 3-D shape creation/editing and advanced modeling capabilities provided by Blender with state-of-the-art Monte Carlo (MC) light simulation techniques and GPU acceleration. It uses Blender's user-friendly computer-aided-design (CAD) interface as the front-end to allow creations of complex domains, making it easy-to-use for less-experienced users to create sophisticated optical simulations needed for a wide range of biophotonics applications.
If you use BlenderPhotonics in your research, please cite the below paper:
- Yuxuan Zhang and Qianqian Fang, "BlenderPhotonics: an integrated open-source software environment for three-dimensional meshing and photon simulations in complex tissues", J. of Biomedical Optics, 27(8), 083014 (2022) doi: https://doi.org/10.1117/1.JBO.27.8.083014
- Install Blender (2.8 or higher) and Octave (4.2 or above) and add them to the
PATHenvironment variable. on Ubuntu Linux, this can be done by
sudo apt-get install blender octave. How to verify: type blender and octave in a command line window, they should start
- Install Python module
oct2pyfor the bundled (built-in) Python inside Blender (not your system's Python)
- This can be done by first identifying the bundled Python by running blender, go to the Scripting tab, in the left-middle Console panel, you can see the Python version, for example, is 3.x
- Open a terminal, type
python3 --version, if the printed version is the same as Blender bundled Python version, you may go to Step 2.4
- If your system's python3 is different from Blender's built-in version, you need to install the matching
version via your package management system, such as
sudo apt-get install python3.x- here "3.x" must match what you saw in the Blender's scripting window.
sudo python3 -m pip install oct2py jdataor
sudo python3.x -m pip install oct2py jdata, this will download and install
jdataand their dependencies to the system's python folder, and all other users on the same computer can use it. If you just want to install oct2py for your own account, or do not have
sudo, you can install by
python3 -m pip install oct2py jdata --useror
python3.x -m pip install oct2py jdata --user. This wil install all modules under
pip install bjdataif needing binary JMesh files
- If the above steps fail, you may still install
jdataby first typing
sys.pathin the Python console in the Scripting view in Blender. This prints a list of paths that Python searches to look for modules. You may copy the
jdatafolders that you have installed on your system's Python module folder to one of the
- How to verify: type
import jdatain the "Scripting" tab of Blender with no error
- Download and unzip Iso2Mesh from http://github.com/fangq/iso2mesh to a work folder
- Download and unzip MMCLAB from http://mcx.space/nightly/ to a work folder
- (Optional) If one intends to load JMesh/JSON mesh files with array-level compression support, one should download and unzip the ZMat Toolbox from https://github.com/fangq/zmat/releases to a work folder
- Automatically add Iso2Mesh, ZMat and MMCLAB to your Octave's search path by opening
~/.octavercwith a text editor and typeHow to verify: start octave, and type
addpath('/path/to/iso2mesh'); addpath('/path/to/mmclab'); addpath('/path/to/zmat');
which mmc, you should see their paths printed
mmcand enter in Octave command window, if you see the error message "liboctinterp.so.4: cannot open shared object file: No such file or directory", this suggest that you are using an Octave newer than the version that was used to compile
mmc.mex. To solve this issue, you must run
sudo ln -s /usr/lib/x86_64-linux-gnu/liboctinterp.so.7 /usr/lib/x86_64-linux-gnu/liboctinterp.so.4or recompile mmc.mex by downloading the source code. see this mailing list post for details.
- Install BlenderPhotonics in Blender
- Download BlenderPhotonics from Github: https://github.com/COTILab/BlenderPhotonics/
- Start Blender, select menu Edit\Preferences\Add-ons, then click the Install ... button, browse
the downloaded .zip file. Blender will load the addon and show it as User Interface: BlenderPhotonics,
click on the empty checkbox, this will install and enable "BlenderPhotonics". It may take a few seconds, until
the checkmark is shown. You can close the Preferences dialog. You should restart blender to use the addon.
The addon is installed under the folder
- Click on the small
<button next to the x/y/z-axis icon on the right-top of the Layout view to show the "N-Panel", and BlenderPhotonics is shown as a tab at the bottom. Click on it to see the BlenderPhotonics GUI.
- How to verify: in the default Blender window with a cube, click on the first button on Blender2Mesh, it should create a mesh