blender-tissue-cartography

Extract surfaces from volumetric microscopy data and map image data to 2D using Blender

image.png

Click here for a 2-minute video demo

Tissue cartography extracts and cartographically projects curved surfaces from volumetric image data. This turns your 3D data into 2D data, which is much easier to visualize, analyze, and computationally process. Tissue cartography takes advantage of the fact that many biological systems are organized as thin, curved sheets (for example, epithelia). For more info, see our methods paper and Heemskerk & Streichan 2015.

This repository contains two tissue-cartography tools:

  1. An add-on for the 3d creation software Blender to do tissue cartography 100% in an interactive, graphical user interface (Version 2 now available). Use the add-on to quickly process a new dataset, or if you are not a coding expert.

    • A companion add-on exposes mesh-improvement filters from MeshLab in Blender, useful for cleaning up meshes obtained from 3D image segmentations.

  2. A Python library for custom and automatized analysis pipelines. The library is available on pip, and as source in this GitHub directory.

Blender has powerful tools for mesh editing, cartographic mapping, and 3D visualization. You can learn to use Blender from one of many tutorials or the manual. With blender_tissue_cartography, you can process surfaces with complex and deforming shapes, where tools like localzprojector break down.

For what can I use tissue cartography?

You can use tissue cartography to replace Z-projections on Z-stacks from a confocal microscope. Even in a mildly curved tissue, it yields much better results since it follows the curved surface. Tissue cartography really shines when analyzing strongly curved surfaces like the Drosophila blastoderm (figure above). Here are some use cases:

Installation

System requirements

Processing volumetric image data requires sufficient RAM (at least ~4x of the size of the image). Blender will run much faster if your computer has a GPU.

Blender add-on

  1. Install Blender 4.5 (pre-4.2 version will not work)

    • Optional: install Fiji (for looking at 3D .tifs) and Ilastik (for 3D segmentation).

  2. Download the add-on .zip from GitHub. Choose the file that matches your operating system, like blender_tissue_cartography-2.0.0-windows_x64.zip.

    • If your OS is unavailable, download the add-on source code, and install the python library scikit-image in Blender’s Python interface.

  3. Install the add-on: Click “Edit -> Preferences -> Add-ons -> Add-on Settings -> Install from disk” and select the .zip file you just downloaded.

  4. Restart Blender. The add-on is under “Scene -> Tissue Cartography”.

  5. Optional: Install the MeshLab add-on (for improving meshes obtained from 3D image data). Download the matching pymeshlab_remesh-*.zip for your OS from GitHub and install it the same way as the main add-on. The panel appears under “Scene -> PyMeshLab Remeshing”.

Python library

  1. Optional: Install Blender

  2. Install blender-tissue-cartography from pip: run pip install blender-tissue-cartography in a command window.

  3. (Optional) Install the Python library for pymeshlab for advanced (re)meshing functionality. Run pip install pymeshlab in a command window

Developer instructions

To extend the Blender add-on:

  1. Download the add-on source code.

  2. Read the add-on developer readme.

To extend the Python library:

  1. Clone the GitHub repository.

  2. Create a conda environment and install the blender_tissue_cartography module:

    • conda env create -n blender_tissue_cartography -f environment.yml
    • conda activate blender_tissue_cartography
    • pip install -e .

  3. Install nbdev. The Python library is developed in Jupyter notebooks that are exported to Python modules and the documentation webpage.

Basic Usage

Tissue cartography workflow

The workflow starts with a 3D, volumetric image, and a 3D segmentation of the object you want to extract. This repo does not contain any image segmentation tools as excellent software is already available (e.g. Ilastik)

  1. Meshing Convert the 3D segmentation into a surface.

  2. UV mapping Cartographically unwrap the surface into a 2D plane.

  3. Projection of your 3D image data to 2D.

  4. Analysis and visualization of the results in 2D or 3D. Use the 2D projections for quantitative analysis.

  5. Batch processing: of multiple 3D images, like frames of a movie.

Each step can also be carried out with external tools - just import/export the required files into Blender/python.

Dynamic datasets

In movies, the surface of interest can move or deform over time. Aligning recordings of multiple samples leads to a similar problem. The add-on and library also provide tools for this more complex use case. You create a cartographic projection for a reference time point which is aligned to all other time points. This generates consistent projections across multiple frames or samples.

Blender add-on

The add-on can carry out steps 1-5 entirely within Blender, so you can edit meshes and cartographic projections interactively. Here is a screenshot using the example Drosophila blastoderm dataset:

image.png

Left: Projected 2D image. Center: 3D view of image data (volume bounding box, image slices, and extracted surface). Right: Tissue Cartography add-on panel.

blender_tissue_cartography Python library

With the Python library, you can build automated and custom tissue cartography pipelines. The library also has tools for quantitative image analysis on projections (to mathematically account for cartographic distortion).

Documentation

The documentation covers common issues & troubleshooting. Please report any bugs on GitHub!

Other useful software for tissue cartography

Citation

If you use blender_tissue_cartography for your work, please cite:

Nikolas Claussen, Cécile Regis, Susan Wopat, and Sebastian Streichan: Blender tissue cartography: an intuitive tool for the analysis of dynamic 3D microscopy data. bioRxiv 2025.02.04.636523; doi: https://doi.org/10.1101/2025.02.04.636523

Acknowledgements

This software is being developed by Nikolas Claussen. We thank the Streichan lab at UCSB (in particular Susan Wopat and Matthew Lefebvre), Cecile Regis, Noah Mitchell, An Yan, Dillon Cislo, and the Irvine lab at Rutgers for feedback, sharing data, and software testing.

Publications using blender_tissue_cartography

If your publication/preprint uses this software, please let us know!