- 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
via the 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
PATH
environment variable. on Ubuntu Linux, this can be done bysudo apt-get install blender octave
. How to verify: type blender and octave in a command line window, they should start - Install Python module
oct2py
for 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. - Type
sudo python3 -m pip install oct2py jdata
orsudo python3.x -m pip install oct2py jdata
, this will download and installoct2py
andjdata
and 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 havesudo
, you can install bypython3 -m pip install oct2py jdata --user
orpython3.x -m pip install oct2py jdata --user
. This wil install all modules under~/.local/lib/python3.x/site-package
folder. Runpip install bjdata
if needing binary JMesh files - If the above steps fail, you may still install
oct2py
andjdata
by first typingimport sys
andsys.path
in 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 theoct2py
andjdata
folders that you have installed on your system's Python module folder to one of thesys.path
folders - How to verify: type
import oct2py
andimport jdata
in 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
~/.octaverc
with a text editor and typeHow to verify: start octave, and typeaddpath('/path/to/iso2mesh'); addpath('/path/to/mmclab'); addpath('/path/to/zmat');
which s2m
,which zmat
andwhich mmc
, you should see their paths printed - type
mmc
and 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 compilemmc.mex
. To solve this issue, you must runsudo ln -s /usr/lib/x86_64-linux-gnu/liboctinterp.so.7 /usr/lib/x86_64-linux-gnu/liboctinterp.so.4
or 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
~/.config/blender/2.82/scripts/addons/BlenderPhotonics
- 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