A Medical Visualisation Add-On for Blender
This project is still in development. The code provided here is still being developed and has not been optimised yet
This Blender add-on is intended to be used to create visulisations of radiation therapy treatment plans including DICOM images, plans, structures and dose. This can be used to create high quality figures for presentations or publications.
This package is intended for research or educational purposes only and should not be used for clinical applications. By using this add-on you accept that this software is provided without warranty and the author will not be held liable for any damages caused by the use of this software.
MedBlend requires Blender 5.0 or newer, and is intended to remain compatible with Blender 5.1.
MedBlend ships with the required pydicom wheel in the add-on package, so no separate pip step or in-app dependency installer is required.
Optional modules are needed for some features:
numpy(CT, dose, and RT structure conversion). This is included with standard Blender 5.x builds, including Blender 5.1's Python 3.13 / NumPy 2.3 environment.- OpenVDB Python bindings (volume import/export). Blender 5.x builds may expose this as either
openvdborpyopenvdb; MedBlend now accepts both names.
To download MedBlend, click the following link and select the latest release. https://github.com/drmichaeldouglass/MedBlend/tags
Download the MedBlend release zip for the version you want to install.
For most users, installing the zip through Blender is the correct process. Administrator rights are not normally required unless your OS or Blender installation location enforces them.
- Open Blender 5.0 or newer.
- Go to
Edit > Preferences. - Open
Get ExtensionsorAdd-onsdepending on your Blender build. - Choose
Install from Disk/Install...and select the MedBlend zip file. - Enable MedBlend after installation if Blender does not enable it automatically.
After the add-on is enabled, MedBlend loads its bundled Python dependency automatically. There is no separate "Install Python Modules" step.
Open the 3D viewport sidebar with N, select the Medical tab, and you should see the MedBlend import tools immediately.
If your environment does not allow normal add-on installation, you can install MedBlend manually into a portable Blender build.
Releases of Blender can be downloaded from here: https://www.blender.org/download/
Experimental builds can be downloaded here: https://builder.blender.org/download/daily/
Ensure that the version of Blender that you download is 5.0 or later. Once downloaded, unzip the file and look for Blender.exe. This version of Blender can be run locally without installation or saved to a USB drive.
Blender, by default, installs add-ons to a versioned scripts folder under your user profile (for example: C:\Users(username)\AppData\Roaming\Blender Foundation\Blender\5.0\scripts\addons). If you do not have administrator rights to your PC, you may need to manually install the add-on to the portable version of Blender you downloaded.
Start by un-zipping the MedBlend add-on zip. Once un-zipped, you should have a folder called "medblend" that contains __init__.py. Copy the "medblend" folder into your portable Blender add-ons path (for example: "D:\Blender5.0\5.0\scripts\addons\medblend_init_.py"). Your Blender path may differ.
Load Blender portable by running Blender.exe. When you select Edit > Preferences > Add-ons, you should find that MedBlend is already installed.
Enable the add-on if needed. MedBlend will load the bundled pydicom wheel from its wheels/ directory automatically when Blender starts the add-on. No dependency-install button is required.
If you build your own package, make sure the wheels/ directory is included in the zip so the bundled Python dependency can be found.
Once installed, open the 3D viewport and select the Medical category from the sidebar. Press N on the keyboard if it is not visible.
If Blender cannot write temporary VDB files in its default temp location, open the MedBlend add-on preferences and set a VDB Temp Directory that your user account can write to.
Note on saving .blend files: Blender volume objects read their voxel data from the VDB file on disk. By default MedBlend writes VDB files to Blender's session temporary directory, which is deleted when Blender exits — so a saved .blend file will lose its volume data on the next reload. If you plan to save your scene, set a persistent
VDB Temp Directoryin the MedBlend preferences first. Files in that directory are never overwritten or cleaned up automatically (each import writes a new uniquely-named file), so clear it out occasionally.
MedBlend currently has 4 main functions: Load DICOM images, Load DICOM Dose, Load DICOM structures and Load Proton Plan. Each of these functions imports a specific DICOM medical file.
-Load DICOM Images, will allow you to load a DICOM image sequence from a specified folder. When you press the load images button, a file dialog will appear. Select a single DICOM image from this folder. MedBlend will search through the same directory and load all DICOM images belonging to the same series (matching SeriesInstanceUID) into Blender automatically. These image slices will be imported and converted to a volume object which can be rendered in Blender.
-Load DICOM Dose will allow you to import radiation therapy DICOM Dose Files from a treatment planning system and display the dose distribution as a volume in Blender.
-Load DICOM structures will import a DICOM structure file from a radiation therapy treatment planning system and import each structure as a separate point cloud.
-Load Proton Plan will import a DICOM RT Ion proton therapy plan file and extract the proton spot positions and weights and display them as spheres with a radius proportional to the relative spot weight.
Some default materials for CT, MRI and Dose volumes have been included in this add-on. When a DICOM image or DICOM dose volume is imported, a default material is automatically created. Select the materials menu from the menu on the right side, and select either Image Material for CT volumes or Dose Material for dose volumes.
With the CT or dose object selected in the outliner (top right), go to the shader/material menu (red icon in lower right) and select either the Image Material or Dose Material depending on what type of volume you have imported.
To change the material properties, select the Shading tab from the top edge and you should see the Material node setup shown in the bottom panel. MedBlend works with both the Eevee and Cycles render engines but Cycles generally produces better results without too many changes. You can change from Eevee to Cycles from the panel on the right. From the material nodes (shown in panel at the bottom), the brightness of the volume can be changed by increasing the "multiply" value. The pixel threshold can be adjusted by moving the slider points in the colour ramp node.
Generally, DICOM CT is not normalised and pixel values (Hounsfield units) can range from -1000 to > 2000 usually. A value of -10000 generally indicates air density, a value of 0 indicates water density and bone and other high density materials have values >1000. To account for this in the shader material, it may be necessary to add a Map Range node after the volume info node and setting the maximum and miniumum input values to suit your specific dataset.
Rather than viewing the DICOM data as a volume, it is possible to convert the CT data into a mesh. This can be performed by apply the volume to mesh modifier in Blender.
Start by creating a place-holder object. From the add menu, add a cube into the scene. This cube object will hold the volume to mesh modifier.
With the cube selected, go to the modifer menu, select Add Modifier and add a Volume to Mesh modifier.
From the object property, select the CT volume. Depending on the normalisation of the volume, you will need to adjust the threshold to visulise the data. For most CT data, a threshold value of 100 is a good starting point
This is what the mesh should look like with a threshold set to 100. You can apply this modifier from the Volume to Mesh modifier panel to bake the mesh which will allow for manual adjustments.
Here are some examples:
A CT scan, structures and dose volumes imported and overlayed.
DICOM structures for a test prostate radiotherapy plan showing organs at risk such as prostate, urethra, bladder, rectum and the external structure.
A test proton therapy plan on a phantom. The CT images, dose distribution and proton spots are shown.
- Not tested on MRI, SPECT, PET or other imaging modalities.
- Imported CT, dose, structure, and proton spot objects are now all placed in the DICOM patient coordinate system (millimetres mapped to metres), so they co-register automatically regardless of import order. Note that the CT volume is therefore no longer centred at the world origin.
- Proton beam orientation (gantry and couch rotation) assumes a head-first supine (HFS) patient; other patient orientations have not been verified and a warning is shown when the plan reports a different patient position.
- If bundled dependencies were missing from the installed package, MedBlend will fail to load. Reinstall using the official release zip and ensure the
wheels/directory is included.
Please report any bugs as an issue on this repository
Import radaition therapy DICOM plan files to visulise MLC or proton spot positions in the patient CT
Visulise brachytherapy dwell point positions and dwell times
MedBlend: A Medical Visualisation Add-On for Blender, M.Douglass https://github.com/drmichaeldouglass/MedBlend
DOI: 10.5281/zenodo.10633327