Skip to content

Commit

Permalink
docs: README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
icrdr committed Apr 22, 2024
1 parent a19b6e1 commit ca9df90
Showing 14 changed files with 124 additions and 23 deletions.
105 changes: 103 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,104 @@
# BioxelNodes
BioxelNodes is a blender add-on for better volume data visualization with cycles.
[中文文档](https://uj6xfhbzp0.feishu.cn/wiki/Qx3VwHuNPimeI8kr6nDcvl1DnHf?from=from_copylink)

# Bioxel Nodes (Blender Add-on)

Bioxel Nodes is a Blender add-on for scientific volumetric data visualization. It using Blender's powerful Geometry Nodes | Cycles to process and render volumetric data.

Before us, there have been many tutorials and add-ons for importing volumetric data into Blender. However, we found that there were many details that were not addressed in place, some scientific facts were ignored, and the volume rendering was not pretty enough. With Bioxel Nodes, you can easily import the volumetric data into Blender, and more importantly, it can quickly make a beautiful realistic rendering of it.

Below are some examples with BioxelNodes. Thanks to Cycles Render, the volumetric data can be rendered with great detail:

![gallery](docs/images/gallery.png)

# Getting Started

Currently only support Blender 4.1 or above, make sure you have the correct version of Blender.

### Add-on Installation

Download the latest version https://github.com/OmooLab/BioxelNodes/releases/latest
In Blender, `Edit - Preferences - Add-ons - Install`, select the `BioxelNodes_{version}.zip` you just downloaded.

### Dependency Installation

The add-on requires a third-party python dependency called SimpleITK, click the Install SimpleITK button below to install the dependency. After clicking, Blender may get stuck, it is downloading and installing, just wait for a moment.

![dependency](docs/images/dependency.png)

This step may have failed due to network factors, just click "Set PyPI Mirror" to change the mirror.

### Basic Usage

First you need to have your volumetric data ready. If not, you can access open research data from [Dryad](https://datadryad.org) (Dryad publishes data exclusively under a [Creative Commons Public Domain License](https://creativecommons.org/public-domain/cc0/))

Note: Make sure one folder contains only one sequence, multiple sequences need to be manually split into different folders first.

In Blender, `File - Import - Volume Data as Biovels`, select **one** of the .dcm files and click on "Volume Data as Bioxels" (you can also drag one of the .dcm files directly into the 3D viewport to trigger the import, but this is limited to .dcm format files)

![importing](docs/images/importing.png)

It may take a while to read data. After finishing reading, it will pop up a dialog box

![import dialog](docs/images/import_dialog.png)

Ignore the options, just click OK!

After importing, the necessary nodes are automatically added, the reconstruction and shader are created, and then turned on the cycles rendering to directly see the result.

![result](docs/images/result.png)

Click select Bioxels Object, and open the Geometry Nodes panel to see the following node graph:

![segment node](docs/images/segment_node.png)

You can change the "Threshold" to modify the reconstruction model, or change the "Color", "Density" to modify the shader effect. All the parameters are straightforward, you can understand them by changing the values.

The node, that named "Segment", is a preset node that combines the steps of 3D reconstruction process and shading process. In general, you need to add one of the segmentation node to reconstruction first, and followed by one of the shader node to set the shader. As you can see in the following figure:

![general graph](docs/images/general_graph.png)

Currently there are 3 types of nodes

- Segmentation nodes, responsible for splitting the volume into a reconstructed model (we call them "Segment").
- Shader nodes, responsible for giving shader to the Segment.
- Slicer nodes, responsible for partially cutting the Segment.

For example:

![general graph example](docs/images/general_graph_example.png)

You can add a "Bake" node between segmentation node and shader node, if the reconstruction process consumes too much computing time. But be sure, you are selecting the volume object, not the container object.

![bake node](docs/images/bake_node.png)

# Known limitations

- Cannot read DICOM with multiple sequences.
- Sections cannot be generated
- Only sequence files are supported, packed volume data formats are not supported yet (will be supported soon)

# Future Features

- Support more volumetric data formats (.nii, .map, .txm...)
- Generate sections
- More segmentation methods, e.g. AI segmentation.
- Even better shader for volumetric rendering

# Technical Notes

The "Bioxel" in "BioxelNodes", is a combination of the words "Bio-" and "Voxel". Bioxel is a voxel that stores biological data, so maybe its chinese name should be "生素" 😂? The volumetric data made up of Bioxel is called Bioxels. We are developing a toolkit around Bioxels for better biological data visualization. but before its release, we made this Blender version of bioxels toolkit first, in order to let more people to have fun with volumetric data. Because we have been pursuing one thing:
**Science that can be beautiful at the same time.**

### Bioxels

Bioxels is based on the RAS coordinate system, Right Aanterior Superior, which was chosen over LPS because it is more compatible with most 3D CG software coordinate systems, and is in line with the 3D artist's understanding of space.

All distances within Bioxels are in Units, and are specified in Meter pre unit. However, when Bioxels is imported into 3D CG software, its size in the software is not scaled by reading the Meter pre unit directly. The reason for this is that many 3D operations in software require that the primtives not be too large or too small.

### Based on OpenVDB

Bioxels is based entirely on OpenVDB for storage and rendering. The main reason for choosing OpenVDB is that as a volumetric data format, it is the fastest way to work with most CG renderers.

### Based on Geometry Nodes

Bioxel Nodes relies on Blender Geometry Nodes to reconstruct and render volumetric data. Node-based operations ensure that the original data is not permanently altered during reconstruction and rendering operations. The fact that the processing is based on Geometry Nodes without any additional dependencies also ensures that Blender can open files without this plugin installed. Look for more support for OpenVDB in GeometryNodes so that BioxelNodes can do more in the future.
6 changes: 3 additions & 3 deletions bioxelnodes/__init__.py
Original file line number Diff line number Diff line change
@@ -6,14 +6,14 @@


bl_info = {
"name": "BiovelNodes",
"name": "Biovel Nodes",
"author": "Ma Nan",
"description": "",
"blender": (4, 0, 0),
"blender": (4, 1, 0),
"version": (0, 1, 0),
"location": "File -> Import",
"warning": "",
"category": "Import-Export"
"category": "Node"
}

auto_load.init()
8 changes: 3 additions & 5 deletions bioxelnodes/external_package/package.py
Original file line number Diff line number Diff line change
@@ -373,17 +373,15 @@ def execute(self, context):
)

result = installer.install_package(f"{self.package}=={self.version}")
if result.returncode == 0 and installer.is_installed(self.package):
if result.returncode == 0 or installer.is_installed(self.package):
self.report(
{'INFO'},
f"Successfully installed {self.package} v{self.version}"
)
else:
self.report(
{'ERROR'},
f"""
Error installing package. Please check the log files
in {preferences.log_dir}.
"""
f"""Error installing package. Please check the log files
in {preferences.log_dir}."""
)
return {'FINISHED'}
15 changes: 8 additions & 7 deletions bioxelnodes/io.py
Original file line number Diff line number Diff line change
@@ -23,7 +23,7 @@ def last_number(file: Path):
return extract_last_number(file.stem)

files.sort(key=last_number)
files = [f.as_posix() for f in files]
files = [str(f) for f in files]
return files


@@ -136,15 +136,14 @@ def execute(self, context):
self.report({"WARNING"}, "Not Supported extension.")
return {'CANCELLED'}

file_path = Path(self.filepath).resolve()
name = file_path.parent.name

files = get_data_files(self.filepath)
name = Path(self.filepath).parent.name

import SimpleITK as sitk
image = sitk.ReadImage(files)

bioxel_size = float(self.bioxel_size)

orig_spacing = tuple(self.orig_spacing)
image_spacing = image.GetSpacing()
image_shape = image.GetSize()
@@ -243,13 +242,13 @@ def execute(self, context):
vdb_dirpath.mkdir(parents=True, exist_ok=True)
vdb_path = Path(vdb_dirpath, f"{uuid4()}.vdb")

print(f"Storing the VDB file ({vdb_path.as_posix()})...")
vdb.write(vdb_path.as_posix(), grids=[grid])
print(f"Storing the VDB file ({str(vdb_path)})...")
vdb.write(str(vdb_path), grids=[grid])

# Read VDB
print(f"Importing the VDB file to Blender scene...")
bpy.ops.object.volume_import(
filepath=vdb_path.as_posix(), align='WORLD', location=(0, 0, 0), scale=(1, 1, 1))
filepath=str(vdb_path), align='WORLD', location=(0, 0, 0), scale=(1, 1, 1))

bioxels_obj = bpy.context.active_object

@@ -482,5 +481,7 @@ def execute(self, context):
# print('output_path', output_path)
# print('source_path', source_path)
shutil.copy(source_path, output_path)

self.report({"INFO"}, "Successfully Exported")

return {'FINISHED'}
13 changes: 7 additions & 6 deletions bioxelnodes/nodes.py
Original file line number Diff line number Diff line change
@@ -9,8 +9,8 @@ def add_driver_to_node_factory(source_prop, target_prop):
import bpy
from bioxelnodes.utils import add_direct_driver, get_bioxels_obj
bioxels_obj = get_bioxels_obj(bpy.context.active_object)
container_obj = bioxels_obj.parent
if bioxels_obj:
container_obj = bioxels_obj.parent
add_direct_driver(
target=node,
target_prop='{target_prop}',
@@ -28,9 +28,10 @@ def set_prop_to_node_factory(source_prop, target_prop):
import bpy
from bioxelnodes.utils import get_bioxels_obj
bioxels_obj = get_bioxels_obj(bpy.context.active_object)
container_obj = bioxels_obj.parent
if bioxels_obj:
node.inputs.get('{target_prop}').default_value = container_obj.get('{source_prop}')
container_obj = bioxels_obj.parent
node.inputs.get('{target_prop}').default_value = container_obj.get(
'{source_prop}')
else:
print('Cannot find any bioxels.')
"""
@@ -44,7 +45,7 @@ def set_prop_to_node_factory(source_prop, target_prop):
'items': [
{
'label': 'Segment',
'icon': 'OUTLINER_OB_META',
'icon': 'BONE_DATA',
'node_type': 'BioxelNodes_Segment',
'node_description': '',
'node_callback': "\n".join([
@@ -54,7 +55,7 @@ def set_prop_to_node_factory(source_prop, target_prop):
},
{
'label': 'Anatomy',
'icon': 'OUTLINER_OB_META',
'icon': 'CONSTRAINT_BONE',
'node_type': 'BioxelNodes_Anatomy',
'node_description': '',
'node_callback': "\n".join([
@@ -141,6 +142,6 @@ def set_prop_to_node_factory(source_prop, target_prop):
custom_nodes = CustomNodes(
menu_items=MENU_ITEMS,
nodes_file=Path(__file__).parent/"assets/Nodes.blend",
root_label='BioxelNodes',
root_label='Bioxel Nodes',
root_icon="FILE_VOLUME",
)
Binary file added docs/images/bake_node.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/dependency.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/gallery.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/general_graph.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/general_graph_example.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/import_dialog.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/importing.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/result.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/segment_node.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit ca9df90

Please sign in to comment.