Morphoblend is an add-on for Blender for the import, processing, editing, quantification, rendering and export of cellular meshes derived from light microscopy data.
MorphoBlend has been designed as a companion to PlantSeg (see PlantSeg on GitHub and the publication) a tool for cell instance segmentation in densely packed 3D volumetric images of plant tissues. Together with seg2mesh (see seg2mesh on GitHub), it alows to visualise, process, edit and quantify cells in tissues:
MorphoBlend can also be used for cell meshes generated by other modalities.
Blenderadd on.- Import cell meshes in
PLYformat. - Can efficiently handle thousands of cells.
- Built in tools for processing (coloring, renaming, filtering, sorting).
- Merging and splitting of cells.
- Easy navigation through time series
- Quantification, visualisation and export of cell attributes (volume, area, ...).
- Assign root tissues
- Extraction of 3D connectivity graph.
- Mapping of nuclei to cells
Blender v3.6.x LTS: download.- A basic understanding of Blender. See this series of videos to get started.
MorphoBlend installs as any other Blender addon.
- Download Morphoblend as a
zipfile.
- Open
Blender. - Install the addon as described here.
The following people have actively contributed to the development, improvement or test of MorphoBlend:
- Sami Bouziri
MorphoBlend is available as a tab on the right side of Blender's main 3D viewport. It consists of several modules:
- Updates
- Import
- Process
- Alter
- Analyze
- Quantify
- Render
- Export
- Navigate through time points: Mouse pointer must be in main window and time points must be collections starting with
torTfollowed by digits only (e.g.t42orT123):Ctrl + Shift + Down_arrow: next time pointCtrl + Shift + Up_arrow: previous time point
This module handles import of the cells mesh and their immediate post-processing.
Path: Type or select (click on folder icon) a folder containing the files to import. Only files in PLY format can be imported. The importer will import:
-
all files in the folder which end by
.ply -
all
plyfiles contained in sub-folders of the main folder as long as this is namedtXX(eg t03). This allows the automatic import of whole time series.
\Folder:
|---> file1.ply <- will be imported
|---> file2.txt <- will NOT be imported
|---> \t00
| |---> file3.txt <- will NOT be imported
| |---> file4.ply <- will be imported
| | (...)
| |---> file6.ply <- will be imported
|
|---> \t01
|---> file7.ply <- will be imported
|---> file8.ply <- will be importedFiles located in a subfolder will be automatically placed in a sub-collection of the same name, while all other files will be put in the Imported collection.
Microscope settings:
-
Magnification: magnification of the lense used during imaging.
-
Camera pixel size: physical dimensions of the camera pixel (default is 6.5µm).
-
Voxel size: physical dimensions of the voxel in µm. X and Y values are either computed from the camera pixel size and the magnification used or can be entered manually. This controls the anisotropic scaling of the meshes and all calculations (volume, area, dimensions...).
Post-processing:
-
Apply rotation: define the rotation (in degrees) along the X, Y & Z axis apply to all meshes after import. Useful to correct for swaps in the orientation of axis.
-
Finalize smoothing: whether all cells are remeshed and decimated to keep their aspects correct and reduce the number of triangle. Beware: not ticking this box can result in large files.
-
Color cells: to assign or not a color at random from the selected palette.
Import: Pressing this button will start the import process. The bar indicates progress.
Translate to origin: Pressing this button will translate all objects so that they are centered onto the scene origin.
The import function is relatively slow. If you have large numbers of objects to import, it is recommended to import the PLY files into a new file directly from the command line (without Blender's GUI). This speeds up the process drastically, especially on machines with several cores.
To do so, you need to launch Blender from a terminal in the so called background or headless mode and use the script import_headless.py which can be downloaded here:
blender -b -P import_headless.py -- --path ~/Desktop/Jaz_test_ply --voxel 0.250 0.1083 0.1083 --rotation O O OThe -b option tells Blender to run in the background, -P the path to the script to execute, and everything beyond -- are the script arguments.
There are three mandatory arguments:
--path: the path to the folder containing theplyfiles to import--voxel: the Voxel dimensions in µm (x/y/z)--rotation: Rotation to apply to each axis in deg (x/y/z)
See this page for instructions on how to retrieve the path to Blender on your machine.
Good to know:
- the resulting
Blenderfile is namedOutput.blendand saved at the location passed to--path - the project is automatically saved after import of all files in a time point folder (
tXXorTxx) has completed - progresses of the import are logged in
Output.log
This modules handles the selection, colouring, sorting and filtering of the cells.
Assing color: assign to a selection of cells either a specific color (prefix [C]) or a color at random in a palette (prefix [P]). In the latter case, pressing Color several times shuffle the color assignment, which is interesting when neighbouring cells have similar colors.
You can also color all cells in collection(s) matching the term on the pull down menu. Then press Color all are assigned a specific color or colored randomely from the chosen palette.
Rename: will rename all selected objects. regex-style expression can be used in the search and replace fields. Replace all will do this for all cells, also the hidden ones.
Group into collection: will move all objects which name fit the regex-style expression, to a collection of the same name.
Filter on volume: Cells which volume is in a given range are selected and listed (as aliases) in a Filter results collection. When Apply filter to all is ticked, the filtering is applied to all cells of the scene (visible or not, selected or not).
This module handles the modification of the cell meshes.
There are keyboard shortcuts to call the functions; hover the mouse over the button to reveal them.
Work List: The work list is a special collection that stores references to cells that need to be merged or split. Selected cells can be added/removed by pressing the corresponding buttons. Navigate in the list with the next/previous buttons. Important: cells in the Work List are aliases (or links) of the original cells, that remain in their original collection. Removing a cell from the working list does not remove it from its collection nor erase it.
Merge: This merges two or more selected contiguous cells in a single mesh.
Split: This splits a single cell. This is a two steps, semi automatic process:
- Phase 1 - Cutting the cells:
- Press the
Start splitbutton this will activate the mesh edit mode just for the cell to split. No need to worry about the other cells around, they can't be edited. - Using the
KNIFEorBISECTtools (located on the left tool bar), delineated a plan (BISECTtool) or a path (KNIFEtool) on the mesh along which the cells will be cut. - Press
ENTER - Press
Vto rip the mesh apart. Do not touch the mouse, use the keybaord arrows to move the cut a little (3-4 keystrokes are sufficient). - Press
ENTER.
- Press the
- Phase 2 - Finalise the split Press the
Finish Split. The split cells will be separated in two new cells and their names updated.
Demos:
Spliting with BISECT
Spliting with KNIFE
This module handles analyses on cells in tissues.
This will assign Epidermis, Cortex, Endodermis and Stele identity based on the radial distance from the center of the root. For this you must:
- define the radial plane by ticking the appropriate boxes.
- Indicate the position of the root center. You can enter the values directly in the X/Y/Z fields OR position it interactively by pressing the 'Interactive' button.
- define how far from the center the Endodermis, Cortex and Epidermis are located.
- You can assign layers only to the selected cells or to all cells (visible or not) by ticking 'Assign to all'
- You can assign a color to all cells in the layers by ticking 'Color cells'
- Layers are assigned after you press 'Assign layers'.
- Assignements can be cleared by pressing 'Clear layers'.
Demo:
This will generate the graph of cell connectivity: adjacent cells are nodes linked by an edge. Note: the area of contact between two cells is stored as an edge attribute.
- Ticking
Extract for all cellswill generate the graph of cell connectivity for every single cells, not just the selected ones. - Press
Generateto start the process. (!) Beware this can be long! Consider the headless version if mny points needs to be processed. - Once tracking data exist, pressing
Drawto visualise the resulting graph - To erase the track data, click
Clear.
The connectivity data can be exported / imported in JSON:
- select the path
- press
ImportorExport
Provided that nuclei and cells objects are present, this will map to a cell a nuclei if this one is fully enclosed into the cell mesh.
To proceed do the following:
- select all Nuclei objects and click
Add to Nuclei Set - select all Cells objects and click
Add to Cell Set - Press
Map
The Sort non mapped option will put in a subcollection all cells and nuclei that could not be mapped. This is convenient to review these.
You can clear the current sets by pressing on Clear Cells (Nuclei) Set
Generating 3D connectivity graph in headless mode:
Generating 3D connectivity graph can be very slow. If you have many to generate, it is recommended to generate them directly from the command line (without Blender's GUI). This speeds up the process drastically, especially on machines with several cores.
To do so, you need to launch Blender from a terminal in the so called background or headless mode and use the script rag_headless.py which can be downloaded here:
blender -b -P rag_headless.py -- --path input_file.blend --timepoints 02 05 07There is one mandatory argument:
--path: Path to the Blender file to process
There is one optional argument:
--timepoints: list of time points to process. Example 00 15 62. If omitted all time points are processed
See this page for instructions on how to retrieve the path to Blender on your machine.
This module handles all quantifications on cells.
Morphometrics: this computes several metrics on the selected cells. The results are displayed in a table, that can be searched, sorted, cleared and saved to disk as .CSV file. For the latter, type or set the path to the output file by pressing the folder icon. The output file will contain in addition to the name of the cell and the collections in belongs to, the following metrics:
- Volume (in µm3)
- Area of (in µm2)
- Dimensions along the X, Y and Z axis
- Coordinates of center (X, Y, Z)
Colorize metric: the selected cells will be coloured according to their Volume or Area, using the full range of the selected palette. A lookup table is displayed.
This modules contains tools to arrange and visualise cells and tissues.
Show/hide collections: This will set the visibility of any collection which names matches the string in 'Search'(regex accepted!). Press 'Set' to execute. This is very useful to toggle th visibility of tissues accross all time points.
Not yet implemented.
From v0.6 onward, MorphoBlend can automatically check for updates.
If the updater is configured to run in the backgound (see below) and an update is available a message will be displayed in this section.
Clicking on Update will install the latest version of MorphoBlend.
You can trigger a manual search for update by visiting the MorphoBlend Udpater Preferences.
You can configure the updater by going into 'Preferences > Addons > MorphoBlend'
Checking for update can be done automatically by ticking the Auto-check for Update box and configure the interval or by pressing the circular arrows button.
If an update is available, you can install it.
Important:
- After an installation you can always restore MorphoBlend to the previous version by clicking on
Restore addon backup. - It is also possible to browse all available MorphoBlend releases and install a specific version by selectin
Install Master/old version
Import: The very first import after (re)starting Blender usually skips the first file. Erasing the cells, and repeating the import solves the issue.
Quantify: colorize metric: the lookup table remains in the 3D viewport until Blender is quit & relaunched.
- Provided nuclei and cells exists as separate objects, MorphoBlend can now link cells to the nuclei they contain. The link information is preserved when measurements are made.
- MorphoBlend can now automatically update!
- Miscelanous code restructuring and improvement
- Headless extraction of the 3D connectivity graph of cells from the command line
- Basic export of each cell as
PLY - Improved performances of headless importer
- Improved performances of Filtering based on volume: implemented caching to speed up repeated filtering.
- Basic tracking of cells over time to establish lineages
- Extraction of the 3D connectivity graph of cells
- Code cleanup, bug fixing and misc. improvement
- Assign radial root tissues (layers)
- Set visibility of groups of tissues
- Headless import: it is now possible to import PLY files directly from the command line.
- Voxel dimensions (x and y) are now set from the magnification.
- Navigate through time points using the keyboard.
- Clear the Filter results collection (without deleting the objects!).
- Improved readability and style of code.
Cells which volume is in a given range are selected and listed (as aliases) in a Filter results collection. Works on a selection or on all cells of the scene (visible or not).
All cells present in a collection matching a given pattern (regex-style) can be colored.
Fixed (nasty) bug affecting the volume computation. Colorize cells according to volume or area.
Cells can be split and merged interactively. Cells to be processed can be added/removed from the Work List which can be navigated.
Quantification of cell volumes & area.
Import and Process modules implemented.