1 line
20 KiB
JSON
Executable File
1 line
20 KiB
JSON
Executable File
{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":"<p>\u4e2d\u6587\u6587\u6863</p>"},{"location":"#bioxel-nodes","title":"Bioxel Nodes","text":"<p>Bioxel Nodes is a Blender addon for scientific volumetric data visualization. It using Blender's powerful Geometry Nodes and Cycles to process and render volumetric data.</p> <p></p> <ul> <li>Realistic rendering result, also support EEVEE NEXT.</li> <li>Support multiple formats.</li> <li>Support 4D volumetric data.</li> <li>All kinds of cutters.</li> <li>Simple and powerful nodes.</li> <li>Based on blender natively, can work without addon.</li> </ul> <p>Read the getting started to begin your journey into visualizing volumetric data!</p> <p>Welcome to our discord server, if you have any problems with this add-on.</p>"},{"location":"#support-multiple-formats","title":"Support Multiple Formats","text":"Format EXT DICOM .dcm, .DCM, .DICOM, .ima, .IMA BMP .bmp, .BMP JPEG .jpg, .JPG, .jpeg, .JPEG PNG .png, .PNG TIFF .tif, .TIF, .tiff, .TIFF Nifti .nia, .nii, .nii.gz, .hdr, .img, .img.gz Nrrd .nrrd, .nhdr HDF5 .hdf, .h4, .hdf4, .he2, .h5, .hdf5, .he5 OME .ome.tiff, .ome.tif MRC .mrc, .mrc.gz, .map, .map.gz"},{"location":"#support-4d-volumetric-data","title":"Support 4D volumetric data","text":"<p>\ud83e\udd70 4D volumetric data can also be imported into Blender.</p>"},{"location":"#support-eevee-next","title":"Support EEVEE NEXT","text":"<p>\ud83d\udc4d EEVEE NEXT is absolutely AWESOME! Bioxel Nodes is fully support EEVEE NEXT now! However, there are some limitations:</p> <ol> <li>Only one cutter supported.</li> <li>EEVEE result is not that great as Cycles does.</li> </ol>"},{"location":"#known-limitations","title":"Known Limitations","text":"<ul> <li>Only works with Cycles CPU , Cycles GPU (OptiX), EEVEE</li> <li>Section surface cannot be generated when convert to mesh (will be supported soon)</li> </ul>"},{"location":"#roadmap","title":"Roadmap","text":"<ul> <li>Better multi-format import experience</li> <li>One-click bake model with texture</li> <li>AI Segmentation to Generate Labels</li> </ul>"},{"location":"advanced/","title":"Advanced","text":"<p>WIP</p>"},{"location":"improve_performance/","title":"Improve Performance","text":"<p>Volume reconstruction and volume rendering are very consuming computation, I believe that this add-on's experience is terrible on poorly hardware. here are tips to improve the add-on performance.</p>"},{"location":"improve_performance/#use-low-res-data-as-preview","title":"Use Low-Res Data as Preview","text":"<p>The addon provides data resample function, the operation is as follows. First, in the container's geometry node, select the layer you need to resample, right-click Bioxel Nodes > Resample Value, in the dialog box, change the \"Bioxel Size\" value to twice or more than the current value, click OK. the addon will create a low-res version of the layer and load it into the container's geometry node.</p> <p></p> <p>You can see that the speed of the reconstruction has been reduced from 240 ms to 37 ms, making it possible to compute in almost real-time, and improving the speed of the feedback of the changing the parameters. Once you are satisfied with the adjustment, you can then connect the original layer to the nodes. This tip can greatly improve the operation experience of the node.</p>"},{"location":"improve_performance/#raise-the-step-rate-of-a-container","title":"Raise the Step Rate of a Container","text":"<p>Step rate is a key setting in volume rendering. The higher the step rate, the faster the rendering will be, but at the same time, the thinner the volume will look. If you want to have a very thin effect, or if you don't need to cut through component, you can always set the step rate high, you can adjust step rate in the render settings globaly. However, I recommend you to adjust the step rate of the container separately, so that it doesn't affect the rendering of the other volume in the Blender file, do as follows.</p> <p>In the container's geometry nodes panel menu, click Bioxel Nodes > Change Container Properties, in the dialog box, raise the \"Step Rate\" value (up to 100) and click OK.</p> <p></p> <p>You can see that the rendering speed is much higher, but at the same time the cuts look blurry and transparent.</p>"},{"location":"improve_performance/#balance-rendering-settings","title":"Balance rendering settings","text":"<p>I list some of the settings that affect the volume rendering most, so you can find the most balanced settings for your needs.</p> <ul> <li> <p>Light Paths > Max Bounces > Volume affects the number of bounces a volume has, the higher the value, the more transparent it will look.</p> </li> <li> <p>Light Paths > Max Bounces > Transparent affects the number of times transparent surfaces are transmitted, the higher the value, the more transparent it will look.</p> </li> <li> <p>Volumes > Step Rate Render | Viewport affects the volume rendering step, the smaller the value, the more detailed the volume will look</p> </li> </ul> <p>Bioxel Nodes provides some render setting presets for quick setup. In the top menu, click Bioxel Nodes > Render Setting Presets, including Performance (left), Balance (center), and Quality (right). Here is a comparison of them.</p> <p></p>"},{"location":"improve_performance/#rendering-with-eevee","title":"Rendering with EEVEE","text":"<p>EEVEE doesn't render volume as well as Cycles, but it does have the advantage of rendering the volumetric data, and is even a better choice if you want to get a clear view of slice. And EEVEE's real-time rendering make it possible to create interactive stuff in Blender.</p>"},{"location":"installation/","title":"Installation","text":"<p>Currently only support Blender 4.2 or above, make sure you have the correct version of Blender.</p>"},{"location":"installation/#install-in-blender-recommended","title":"Install in Blender (recommended)","text":"<p>This is the most recommended way, in the top menu, click Edit > Preferences, in \"Get Extensions\" Section, enter \"bio\" in the search box, then click Install. due to the add-on size (25MB~50MB) you may need to wait a while.</p> <p></p>"},{"location":"installation/#blender-official-extensions-website","title":"Blender Official Extensions Website","text":"<p>Or you can visit the Blender official extensions website at https://extensions.blender.org/add-ons/bioxelnodes/ Click Get Add-on, open Blender, drag in Blender and follow the instructions to install.</p>"},{"location":"installation/#manual-install","title":"Manual Install","text":"<p>You can also install BioxelNodes_{version}.zip manually by downloading from bere. In the top menu, click Edit > Preferences, Add-ons > Install from Disk and select the Zip file you just downloaded.</p>"},{"location":"qa/","title":"Q & A","text":""},{"location":"qa/#nothing-in-the-scene-when-rendering","title":"Nothing in the scene when rendering?","text":"<p>If you're using the Cycles renderer with GPU, make sure your GPU supports \"Optix\", as Bioxel Nodes relies on OSL (Open shader language) for volumetric rendering, otherwise you'll have to use the CPU for rendering.</p> <p>If you're using the EEVEE renderer, this issue is due to EEVEE not loading shaders for some unknown reason, save the file and restart Blender to fix it.</p>"},{"location":"qa/#after-updating-the-addon-the-nodes-in-the-file-have-turned-red","title":"After updating the addon, the nodes in the file have turned red?","text":"<p>This is because the version of the nodes in the file does not match the current version of the addon after updating.</p> <p>If you still want to edit the file with Bioxel Nodes, you can only roll back the addon version to the version that corresponds to the nodes.</p> <p>If you just want the file to work and you won't rely on Bioxel Nodes any more, then you can just click Bioxel Nodes > Relink Node Library > in the top menu and select the corresponding version. Check to see if the nodes are working and rendering properly, and when everything is OK, click Bioxel Nodes > Save Node Library and select the save location in the dialog box.</p>"},{"location":"step_by_step/","title":"Step by Step","text":""},{"location":"step_by_step/#download-data","title":"Download Data","text":"<p>Here is the open data from Visible Human Project (VHP) for you to learn how to use this addon. It is a CT scan image of a male head, download and unzip it to any location for later usage.</p> <p>VHP_M_CT_Head.zip</p> <p>VHP original radiology data was shared in the proprietary format that predated DICOM, complicating its use. Now all data has been harmonized to standard DICOM and released in NCI Imaging Data Commons (IDC), you also can download data from IDC by yourself.</p>"},{"location":"step_by_step/#import-data","title":"Import Data","text":"<p>In the top menu, click Bioxel Nodes > Import Volumetric Data (Init) > as Scalar, locate to the unzipped folder, select any DICOM file (don't select more than one, and don't select the folder either), and click Import as Scalar.</p> <p></p> <p>You can also choose to import data by dragging one DICOM file into the 3D viewport (some DICOM files don't have extension suffix and can't be dragged in).</p> <p>The process of reading the data may take a while, the bottom right corner of the Blender interface will show you the progress of the reading, and a dialog box will pop up when the reading is successful. Ignore all the options for now and just click OK, I will explain the purpose of these options later.</p> <p>The import process involves data conversion, so there is more waiting time, and the progress of the import is displayed in the lower right corner of the interface. After importing, the addon will create a new object, with a new geometry nodes that will serve as a \"workbench\" for manipulating the data, the new object is called the Container. The newly imported data is stored in the Container as a Layer, which is loaded into the Container's Geometry node via the \"Fetch Layer\" node (the red one), and be converted into a Component that can be rendered.</p> <p></p> <p>Next, let's preview the data in Blender.</p> <p>In the container's geometry nodes panel menu, click Bioxel Nodes > Add a Slicer. The addon will insert a node named \"Slice\" between the \"Fetch Layer\" and the \"Output\" and create a new plane object named \"Slicer\". Click the \"Slice Viewer\" button in the upper right corner of the 3D viewport to enter the preview mode, then move and rotate the \"Slicer\" object. You will see a slice image of the data, which should be familiar to anyone who has used any DICOM viewing software.</p> <p></p> <p>(If the volume disappears when you click the \"Slice Viewer\" button, save the file and restart Blender, it should be fixed, or you can turn on the Cycles rendering to see the slicer plane as well. The issue is caused by EEVEE's failure of reloading the shaders.)</p> <p>The \"Slicer\" node is used to display the slices of the data, with an external object as the location of the slice plane. This step is not necessary for visualization, but it provides a quick way to preview the data in Blender for user perception. Next, let's turn the volumetric data into a renderable object.</p>"},{"location":"step_by_step/#cutout-the-skull","title":"Cutout the skull","text":"<p>Bone tends to have much higher CT values than soft tissue, so you can split bone and soft tissue by setting a threshold. In the Geometry Nodes panel menu of the container, click Add > Bioxel Nodes > Component > Cutout by Threshold to add a \"Cutout\" node and connect it between the \"Fetch Layer\" node and the \"Output\", and then set the \"Threshold\" parameter of the \"Cutout by Threshold\" node to 0.3 and turn on the \"With Surface\" option. Switch to viewport shading to \"Render Preview\". The node graph and the render result are shown below.</p> <p></p> <p>If you want the render result to be consistent with the above image, you also need to change the default light object type from \"Point\" to \"Area\" to increase the brightness, and change the Look in Color Management to \"High Contrast\".</p> <p>You can understand the role of the \"Threshold\" parameter in shaping the output by changing it. If you feel very laggy while draging the parameter, you can temporarily turn off the \"With Surface\" option in the \"Cutout\" node. When you are satisfied, turn it on again. In addition, the volume rendering is very computationally intensive, which is also a major cause of the lag, so you can adjust the parameters in \"Slice Viewer\" mode first, and then do the Cycles rendering when you are satisfied.</p> <p>You may consider using GPU for faster rendering, but please note that Bioxel Nodes only supports Optix GPUs due to its dependency on OSL (Open shader language), and the first time you turn on GPU rendering, you may need to wait for Blender to load the appropriate dependencies (the screen will get stuck), so please be patient.</p> <p>Although the output component looks like a mesh object, it retains its internal information through its volume, so when you cut through the component, you should see an inhomogeneous cross-section made up of volume, rather than just an empty shell like any mesh object. Let's cut the skull to see its complex internal structure.</p>"},{"location":"step_by_step/#cut-and-color","title":"Cut and Color","text":"<p>In the container's geometry nodes panel menu, click Bioxel Nodes > Add a Cutter > Plane Cutter, the addon will insert a \"Cut\" node and a \"Object Cutter\" node. Also, it will create a new plane object named \"Plane Cutter\" to the scene, at this point you should be able to see that the skull has been cut through as expected.</p> <p>Just like the \"Slicer\" object, move and rotate the \"Plane Cutter\" and the position and direction of the cut will change accordingly. Please adjust the Cutter object to a vertical orientation so that it cuts the skull vertically, as shown below.</p> <p></p> <p>The CT value of the skull is inhomogeneous, which reflects the difference in substance density of the bone. We can enhance the display of this difference by coloring. In the Geometry Nodes panel menu of the container, click Add > Bioxel Nodes > Propetry > Set Color by Ramp 5 to add the \"Set Color\" node and connect it after any node. Set the node's parameters \"From Min\" to 0.3 and \"From Max\" to 0.5, as shown below.</p> <p></p> <p>When rendering is turned on, you can clearly see that the calvaria and teeth are colored red, meaning that the bone in these areas is denser. You can try to adjust the parameters of the \"Set Color\" node to recognize their roles. If you feel laggy when draging the parameters, you can temporarily turn off \"With Surface\" and switch to \"Slice Viewer\" mode.</p>"},{"location":"step_by_step/#transformation","title":"Transformation","text":"<p>You may find that the position of the skull is a bit off the origin, this is due to the fact that the addon keeps the position information from the original data record during the import process. If you need to change the position, do not move the container (object) directly as you would in 3D viewport; the addon provides dedicated \"Transform\" node to handle transformations.</p> <p>In the Geometry Nodes panel menu of the container, click Bioxel Nodes > Add a Locator, the addon will insert the \"Transform Parent\" node and create a new empty object named \"Locator\". If you move, rotate, or scale the \"Locator\", the skull will Transform as well. If you also want the origin of the rotational transformation to be set at the geometric center of the skull, just add a \"ReCenter\" node (Add > Bioxel Nodes > Transform > ReCenter) in front of the \"Transform Parent\" node, as shown below.</p> <p></p> <p>Being used to moving objects directly in the 3D viewport, you may find it strange to have an extra step to transform component like this. This is in consideration of the fact that there may be multiple components involved in one container with different transform needs, as well as future development plans for resampling mechanism, which I'll explain in more detail later.</p>"},{"location":"step_by_step/#surface-mesh","title":"Surface Mesh","text":"<p>A mesh, made up of vertexs and faces, is the \"greatest common\" in the 3D world. Therefore, in order to be compatible with other 3D workflow, the addon provides the \"To Surface\" node (Add > Bioxel Nodes > Component > ToSurface), which converts the component into a mesh. Note that the surface mesh is not editable in the container's geometry node, and can only be connected to \"Transform\" and \"Shader\" nodes.</p> <p>As shown below, you can connect \"Slime Shader\" node (Add > Bioxel Nodes > Surface > Slime Shader) after the \"To Surface\" node to give the surface a shader, or connect \"Transform\" nodes.</p> <p></p> <p>If you want to edit the mesh, click Bioxel Nodes > Extract from Container > Extract Surface in the Geometry Nodes panel menu of the container. The addon will create a new object with Geometry Nodes, in which a \"Fetch Surface\" node to read the surface mesh. You can apply this geometry node to edit the mesh as usual. Or you can leave the geometry node in place and keep it connected to the original container in real time.</p> <p></p> <p>(To show it better, I made an X-axis offset to the newly created mesh, otherwise the container and the mesh are perfectly overlapping.)</p>"},{"location":"step_by_step/#save-temporary-files","title":"Save Temporary Files","text":"<p>The layers cache is stored in a temporary folder, while the addon's custom nodes are linked to the node library file in addon directory. Both of them are exist locally by default, and if you only deliver the Blender file to other devices, the file will not work properly because the resources are missing.</p> <p>Therefore, you need to save all temporary files before you deliver the Blender file. The procedure is simple:</p> <ol> <li>Save the Blender file.</li> <li>in the top menu, click Bioxel Nodes > Save Node Library, and set the relative path.</li> <li>in the top menu, click Bioxel Nodes > Save All Layers Cache and set the relative path.</li> </ol> <p>Zip the Blender file together with the local node library file and the layer cache files (there may be more than one).</p> <p></p> <p>\ud83e\udd17 If you can follow the documentation up to this point, you're already started!</p>"},{"location":"support_format/","title":"Support Format","text":"<p>Can't wait to play with the addon using your own data? Here's a list of the formats currently supported.</p> Format EXT DICOM .dcm, .DCM, .DICOM, .ima, .IMA BMP .bmp, .BMP JPEG .jpg, .JPG, .jpeg, .JPEG PNG .png, .PNG TIFF .tif, .TIF, .tiff, .TIFF Nifti .nia, .nii, .nii.gz, .hdr, .img, .img.gz Nrrd .nrrd, .nhdr HDF5 .hdf, .h4, .hdf4, .he2, .h5, .hdf5, .he5 OME .ome.tiff, .ome.tif MRC .mrc, .mrc.gz, .map, .map.gz <p>Despite my best efforts, I still can't achieve perfect support for all volumetric data formats, and I will continue to work on this.</p>"},{"location":"support_format/#open-databases","title":"Open Databases","text":"<p>If you don't have volumetric data, then you can download from some open databases.</p> <p>Note that just because they are open and available for download does not mean you can use them for anything! Be sure to look at the description of the available scopes from website.</p> Source Object MorphoSource Open Research Data Dryad Open Research Data Cell Image Library Cells OpenOrganelle Cells Allen Cell Explorer Cells EMDB Protein, Viruses IDC Medical Images Embodi3D Medical Images Github Medical Images NIHR Medical Images Medical Segmentation Decathlon Medical Images Visible Human Project Medical Images"}]} |