add preprint link and help info

COTILab · Jan 20, 2022 · b8ed86c · b8ed86c
1 parent bf852e8
commit b8ed86c
Show file tree

Hide file tree

Showing 17 changed files with 474 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -3,13 +3,13 @@
 BlenderPhotonics
 ========================
 
--   **Author**: Yuxuan Zhang (zhang.yuxuan1 at northeastern.edu) and Qianqian Fang (q.fang at neu.edu)
+-   **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](https://grantome.com/grant/NIH/R01-GM114365-06) and 
-      [U24-NS124027](https://reporter.nih.gov/search/dXkcyoaEQkaRrkpQoOnEBw/project-details/10308329) (PI: Fang)
+      [U24-NS124027](https://reporter.nih.gov/search/dXkcyoaEQkaRrkpQoOnEBw/project-details/10308329)
 
 Introduction
 -------------
@@ -29,6 +29,11 @@ It uses Blender's user-friendly computer-aided-design (CAD) interface as the fro
 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.
 
+The details of this work can be found in the below preprint:
+
+- Yuxuang Zhang and Qianqian Fang, "[BlenderPhotonics – a versatile environment for 3-D complex bio-tissue
+  modeling and light transport simulations based on Blender](https://doi.org/10.1101/2022.01.12.476124)", 
+  bioRxiv 2022.01.12.476124; doi: https://doi.org/10.1101/2022.01.12.476124
 
 Installation
 -------------

diff --git a/__init__.py b/__init__.py
@@ -1,3 +1,58 @@
+"""BlenderPhotonics - a Blender addon for 3-D mesh generation and Monte Carlo simulation
+
+* Authors: (c) 2021-2022 Qianqian Fang <q.fang at neu.edu>
+	   (c) 2021	 Yuxuan Zhang <zhang.yuxuan1 at northeastern.edu>
+* License: GNU General Public License V3 or later (GPLv3)
+* Version: v2022 (v0.6.0)
+* Website: http://mcx.space/bp
+* 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 [1]) and mesh-based Monte Carlo (MMC) photon simulations (via
+MMCLAB [2]) 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 also supports using MATLAB as the
+backend to run Iso2Mesh and MMCLAB via "matlab.engine" if installed.
+
+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.
+
+Installing this module via Blender menu "Edit\Preference\Add-ons\Install..."
+enables the BlenderPhotonics panel. The BlenderPhotonics panel contains
+the following 4 submodules:
+
+* Blender2Mesh: converting Blender scene to volumetric tetrahedral mesh models
+* Volume2Mesh:  converting NIfTI/JNIfTI/.mat 3D volumes to tetrahedral mesh
+* Surface2Mesh: converting and processing triangular surface meshes
+* Multiphysics Simulations: configuring and executing MMC photon simulation
+
+For each module, a dialog showing detailed parameters and sub-feature allow
+users to adjust the meshing parameters or perform various modeling tasks.
+
+To cite this work, please use the below information
+
+@article {BlenderPhotonics2022,
+  author = {Zhang, Yuxuang and Fang, Qianqian},
+  title = {{BlenderPhotonics -- a versatile environment for 3-D complex bio-tissue modeling and light transport simulations based on Blender}},
+  elocation-id = {2022.01.12.476124},
+  year = {2022},
+  doi = {10.1101/2022.01.12.476124},
+  publisher = {Cold Spring Harbor Laboratory},
+  URL = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124},
+  eprint = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124.full.pdf},
+  journal = {bioRxiv}
+}
+
+[1] Iso2Mesh: http://iso2mesh.sf.net
+[2] MMCLAB:   http://mcx.space
+
+"""
+
 bl_info = {
     "name": "BlenderPhotonics",
     "author": "(c) 2021 Yuxuan (Victor) Zhang, (c) 2021 Qianqian Fang",

diff --git a/blender2mesh.py b/blender2mesh.py
@@ -1,3 +1,25 @@
+"""Blender2Mesh - converting Blender objects/scene to 3-D tetrahedral mesh
+
+* Authors: (c) 2021-2022 Qianqian Fang <q.fang at neu.edu>
+           (c) 2021      Yuxuan Zhang <zhang.yuxuan1 at northeastern.edu>
+* License: GNU General Public License V3 or later (GPLv3)
+* Website: http://mcx.space/bp
+
+To cite this work, please use the below information
+
+@article {BlenderPhotonics2022,
+  author = {Zhang, Yuxuang and Fang, Qianqian},
+  title = {{BlenderPhotonics -- a versatile environment for 3-D complex bio-tissue modeling and light transport simulations based on Blender}},
+  elocation-id = {2022.01.12.476124},
+  year = {2022},
+  doi = {10.1101/2022.01.12.476124},
+  publisher = {Cold Spring Harbor Laboratory},
+  URL = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124},
+  eprint = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124.full.pdf},
+  journal = {bioRxiv}
+}
+"""
+
 import bpy
 import numpy as np
 import jdata as jd

diff --git a/mesh2blender.py b/mesh2blender.py
@@ -1,3 +1,25 @@
+"""Mesh2Blender - load regional mesh created by Iso2Mesh back to Blender
+
+* Authors: (c) 2021-2022 Qianqian Fang <q.fang at neu.edu>
+           (c) 2021      Yuxuan Zhang <zhang.yuxuan1 at northeastern.edu>
+* License: GNU General Public License V3 or later (GPLv3)
+* Website: http://mcx.space/bp
+
+To cite this work, please use the below information
+
+@article {BlenderPhotonics2022,
+  author = {Zhang, Yuxuang and Fang, Qianqian},
+  title = {{BlenderPhotonics -- a versatile environment for 3-D complex bio-tissue modeling and light transport simulations based on Blender}},
+  elocation-id = {2022.01.12.476124},
+  year = {2022},
+  doi = {10.1101/2022.01.12.476124},
+  publisher = {Cold Spring Harbor Laboratory},
+  URL = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124},
+  eprint = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124.full.pdf},
+  journal = {bioRxiv}
+}
+"""
+
 import bpy
 import numpy as np
 import jdata as jd

diff --git a/nii2mesh.py b/nii2mesh.py
@@ -1,3 +1,26 @@
+"""NII2Mesh - converting a 3-D volumetric image (stored in NIfTI/JNIfTI/.mat file) to tetrahedral mesh
+
+* Authors: (c) 2021-2022 Qianqian Fang <q.fang at neu.edu>
+           (c) 2021      Yuxuan Zhang <zhang.yuxuan1 at northeastern.edu>
+* License: GNU General Public License V3 or later (GPLv3)
+* Website: http://mcx.space/bp
+
+To cite this work, please use the below information
+
+@article {BlenderPhotonics2022,
+  author = {Zhang, Yuxuang and Fang, Qianqian},
+  title = {{BlenderPhotonics -- a versatile environment for 3-D complex bio-tissue modeling and light transport simulations based on Blender}},
+  elocation-id = {2022.01.12.476124},
+  year = {2022},
+  doi = {10.1101/2022.01.12.476124},
+  publisher = {Cold Spring Harbor Laboratory},
+  URL = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124},
+  eprint = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124.full.pdf},
+  journal = {bioRxiv}
+}
+"""
+
+
 import bpy
 import numpy as np
 import jdata as jd

diff --git a/niifile.py b/niifile.py
@@ -1,3 +1,25 @@
+"""NIIFile - panel file browser properties
+
+* Authors: (c) 2021-2022 Qianqian Fang <q.fang at neu.edu>
+           (c) 2021      Yuxuan Zhang <zhang.yuxuan1 at northeastern.edu>
+* License: GNU General Public License V3 or later (GPLv3)
+* Website: http://mcx.space/bp
+
+To cite this work, please use the below information
+
+@article {BlenderPhotonics2022,
+  author = {Zhang, Yuxuang and Fang, Qianqian},
+  title = {{BlenderPhotonics -- a versatile environment for 3-D complex bio-tissue modeling and light transport simulations based on Blender}},
+  elocation-id = {2022.01.12.476124},
+  year = {2022},
+  doi = {10.1101/2022.01.12.476124},
+  publisher = {Cold Spring Harbor Laboratory},
+  URL = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124},
+  eprint = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124.full.pdf},
+  journal = {bioRxiv}
+}
+"""
+
 import bpy
 from bpy.props import StringProperty, EnumProperty
 from bpy.types import PropertyGroup

diff --git a/obj2surf.py b/obj2surf.py
@@ -1,3 +1,24 @@
+"""Blender2Surf - extracting, converting and processing Blender object surfaces
+
+* Authors: (c) 2021-2022 Qianqian Fang <q.fang at neu.edu>
+* License: GNU General Public License V3 or later (GPLv3)
+* Website: http://mcx.space/bp
+
+To cite this work, please use the below information
+
+@article {BlenderPhotonics2022,
+  author = {Zhang, Yuxuang and Fang, Qianqian},
+  title = {{BlenderPhotonics -- a versatile environment for 3-D complex bio-tissue modeling and light transport simulations based on Blender}},
+  elocation-id = {2022.01.12.476124},
+  year = {2022},
+  doi = {10.1101/2022.01.12.476124},
+  publisher = {Cold Spring Harbor Laboratory},
+  URL = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124},
+  eprint = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124.full.pdf},
+  journal = {bioRxiv}
+}
+"""
+
 import bpy
 from bpy_extras.io_utils import ImportHelper
 import numpy as np

diff --git a/runmmc.py b/runmmc.py
@@ -1,8 +1,29 @@
+"""RunMMC - launch mesh-based Monte Carlo (MMC) simulations using domain configured in Blender
+
+* Authors: (c) 2021-2022 Qianqian Fang <q.fang at neu.edu>
+           (c) 2021      Yuxuan Zhang <zhang.yuxuan1 at northeastern.edu>
+* License: GNU General Public License V3 or later (GPLv3)
+* Website: http://mcx.space/bp
+
+To cite this work, please use the below information
+
+@article {BlenderPhotonics2022,
+  author = {Zhang, Yuxuang and Fang, Qianqian},
+  title = {{BlenderPhotonics -- a versatile environment for 3-D complex bio-tissue modeling and light transport simulations based on Blender}},
+  elocation-id = {2022.01.12.476124},
+  year = {2022},
+  doi = {10.1101/2022.01.12.476124},
+  publisher = {Cold Spring Harbor Laboratory},
+  URL = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124},
+  eprint = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124.full.pdf},
+  journal = {bioRxiv}
+}
+"""
+
 import bpy
 import numpy as np
 import jdata as jd
 import os
-import platform
 from .utils import *
 
 g_nphoton=10000

diff --git a/script/blender2mesh.m b/script/blender2mesh.m
@@ -1,4 +1,37 @@
 function blender2mesh(filename)
+%
+% nodedata=surf2jmesh(filename)
+%
+% loading a trangular surface mesh from a file
+%
+% author: Qianqian Fang (q.fang at neu.edu)
+%         Yuxuan Zhang (zhang.yuxuan1 at northeastern.edu)
+%
+% input:
+%	 filename: path to the surface mesh file exported from Blender, data in JMesh format
+%
+% output:
+%	 two JMesh files are saved under the temporary folder bpmwpath('')
+%          volumemesh.jmsh: contains the tetrahedral mesh
+%          regionmesh.jmsh: contains the surface of each individual regions/labels
+%
+% license: GPLv3 or later, see LICENSE.txt for details
+%
+% reference: 
+% @article {BlenderPhotonics2022,
+%  author = {Zhang, Yuxuang and Fang, Qianqian},
+%  title = {{BlenderPhotonics -- a versatile environment for 3-D complex bio-tissue modeling and light transport simulations based on Blender}},
+%  elocation-id = {2022.01.12.476124},
+%  year = {2022},
+%  doi = {10.1101/2022.01.12.476124},
+%  publisher = {Cold Spring Harbor Laboratory},
+%  URL = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124},
+%  eprint = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124.full.pdf},
+%  journal = {bioRxiv}
+% }
+%
+% -- this function is part of BlenderPhotonics (http://mcx.space/bp)
+%
 
 blender=loadjson(filename, 'FastArrayParser',0);
 

diff --git a/script/blender2surf.m b/script/blender2surf.m
@@ -1,4 +1,45 @@
 function blender2surf(filename)
+%
+% blender2surf(filename)
+%
+% Load a JMesh surface mesh file and perform a specified surface processing
+%
+% author: Qianqian Fang (q.fang at neu.edu)
+%
+% input:
+%	 filename: the path to a JMesh file containing a surface mesh, the JSON tree must contain
+%           param.action: a string can be 'repair','smooth','reorient','simplify','remesh',
+%                 'boolean-and','boolean-or','boolean-xor','boolean-diff','boolean-first',
+%                 'boolean-second','boolean-decouple'
+%           param.level: a single number to be used for the respective action; 
+%                 for 'smooth': this indicates number of iterations
+%                 for 'simplify': this indicates percentage of edges to be kept
+%                 for 'boolean-*': a negative value (-1) suggests flipping the two input surfaces
+%           the structure should contain a single or multiple JMesh objects object(i), each should have
+%           object(i).MeshNode: an Nnx3 array for vertex coordinates
+%           object(i).MeshSurf: an Nex3 integer array for triangular surface elements
+%
+% output:
+%	 the processed surface mesh is saved as a JMesh file under the temporary folder bpmwpath('')
+%          surfacemesh.jmsh: contains the processed surface mesh
+%
+% license: GPLv3 or later, see LICENSE.txt for details
+%
+% reference: 
+% @article {BlenderPhotonics2022,
+%  author = {Zhang, Yuxuang and Fang, Qianqian},
+%  title = {{BlenderPhotonics -- a versatile environment for 3-D complex bio-tissue modeling and light transport simulations based on Blender}},
+%  elocation-id = {2022.01.12.476124},
+%  year = {2022},
+%  doi = {10.1101/2022.01.12.476124},
+%  publisher = {Cold Spring Harbor Laboratory},
+%  URL = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124},
+%  eprint = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124.full.pdf},
+%  journal = {bioRxiv}
+% }
+%
+% -- this function is part of BlenderPhotonics (http://mcx.space/bp)
+%
 
 blender=loadjson(filename, 'FastArrayParser',0);
 

diff --git a/script/blendermmc.m b/script/blendermmc.m
@@ -1,4 +1,37 @@
 function blendermmc(paramfile, meshfile)
+%
+% blendermmc(paramfile, meshfile)
+%
+% Launching an MMCLAB simulation and save results to a JMesh file
+%
+% author: Qianqian Fang (q.fang at neu.edu)
+%         Yuxuan Zhang (zhang.yuxuan1 at northeastern.edu)
+%
+% input:
+%	 paramfile: the JSON file contains simulation parameters configured in Blender
+%	 meshfile:  the tetrahedral mesh file generated by BlenderPhotonics in previous step
+%
+% output:
+%	 a single JSON file mmcoutput.json contains a 1D/2D array subfield of "logflux" 
+%        is saved in the BP's temporary folder
+%
+% license: GPLv3 or later, see LICENSE.txt for details
+%
+% reference: 
+% @article {BlenderPhotonics2022,
+%  author = {Zhang, Yuxuang and Fang, Qianqian},
+%  title = {{BlenderPhotonics -- a versatile environment for 3-D complex bio-tissue modeling and light transport simulations based on Blender}},
+%  elocation-id = {2022.01.12.476124},
+%  year = {2022},
+%  doi = {10.1101/2022.01.12.476124},
+%  publisher = {Cold Spring Harbor Laboratory},
+%  URL = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124},
+%  eprint = {https://www.biorxiv.org/content/early/2022/01/14/2022.01.12.476124.full.pdf},
+%  journal = {bioRxiv}
+% }
+%
+% -- this function is part of BlenderPhotonics (http://mcx.space/bp)
+%
 
 param=loadjson(paramfile)
 meshdata=load(meshfile);