Metadata-Version: 2.1
Name: blender-tissue-cartography
Version: 0.0.4
Summary: Pipeline for tissue extraction and analysis of surfaces from volumetric mircroscopy data using blender
Home-page: https://github.com/nikolas-claussen/blender-tissue-cartography
Author: Nikolas
Author-email: nclaussen@ucsb.edu
License: Apache Software License 2.0
Keywords: nbdev jupyter notebook python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: scikit-image
Requires-Dist: tifffile
Requires-Dist: h5py
Requires-Dist: jupyter
Requires-Dist: tqdm
Requires-Dist: libigl
Provides-Extra: dev
Requires-Dist: nbdev ; extra == 'dev'
Requires-Dist: pymeshlab ; extra == 'dev'
Requires-Dist: trimesh ; extra == 'dev'
Requires-Dist: quaternionic ; extra == 'dev'
Requires-Dist: spherical ; extra == 'dev'

# blender-tissue-cartography


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## What this tool does

![image.png](index_files/figure-commonmark/cell-2-1-ee28c1cc-3737-4a46-b1ec-e96e9291126d.png)

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 is particularly useful in developmental
biology, analyzing 3d microscopy data by taking advantage of the
laminar, sheet-like organization of many biological tissues. For more on
tissue cartography, see our [methods
paper](https://www.biorxiv.org/content/10.1101/2025.02.04.636523v1),
[Heemskerk & Streichan 2015](https://doi.org/10.1038/nmeth.3648) and
[Mitchell & Cislo 2023](https://doi.org/10.1038/s41592-023-02081-w).

`blender_tissue_cartography` comprises an add-on to do tissue
cartography using the popular 3d creation software
[blender](https://www.blender.org/), a python library for creating
custom/automatized analysis pipelines, and a set of template analysis
pipelines/tutorials.

### Work in progress!

This project is a work in progress and may change rapidly. Please update
regularly.

## Installation

`blender_tissue_cartography` comprises both a Blender **add-on** and a
**python library**.

- The **add-on** does tissue cartography 100% within the Blender
  graphical user interface. Use the add-on if you quickly want to
  process a new dataset, or if you are not a coding expert.

- The **python library** allows expert users to develop custom or
  automatized pipelines.

**System requirements** Both the Python library and the add-on have no
minimum system requirements and can run on any modern laptop. For
processing volumetric image data, you will need sufficient RAM (at least
~4x of the size of the volumetric data, e.g. 8GB RAM dfor a 2GB
volumetric `.tif` file). Blender will run *much* faster if your computer
has a GPU. The MeshLab library which is required for some
(non-essential) operations is not available of new ARM Apple computers.

### Blender add-on

1.  Install the non-python programs: [Blender
    4.3](https://www.blender.org/) (pre-4.3 version will *not* work) and
    [Ilastik](https://www.ilastik.org/). You do not need to install
    python or any python libraries.

    - Optionally, install [Fiji](https://fiji.sc/) (for looking at 3D
      `.tif`s) and [Meshlab](https://www.meshlab.net/) (for advanced
      surface extraction and remeshing)

2.  From
    [GitHub](https://github.com/nikolas-claussen/blender-tissue-cartography),
    download the file
    `blender_addon/blender_tissue_cartography-1.0.0-[XXX].zip` where
    `[XXX]` is your operating system (e.g. `linux_x64`). You do *not*
    need to unpacl the `.zip`.

    - If your operating system is not available, you can also download
      `blender_addon/blender_tissue_cartography.py`. In this case you
      will need to install the python library `scikit-image` in
      Blender’s Python interface.

3.  [Install the
    add-on](https://docs.blender.org/manual/en/latest/editors/preferences/addons.html):
    Click “Edit -\> Preferences -\> Add-ons -\> Add-on Settings -\>
    Install from disk” and select the `.zip` file you just downloaded
    (you don’t need to unpack it).

4.  Restart Blender. The add-on can now be found under “Scene -\> Tissue
    Cartography”.

### Python library

1.  Install the non-python programs: [Fiji](https://fiji.sc/)
    (optional), [Ilastik](https://www.ilastik.org/),
    [Meshlab](https://www.meshlab.net/) (optional), and
    [Blender](https://www.blender.org/).

2.  Install Python via
    [anaconda/miniconda](https://docs.anaconda.com/miniconda/miniconda-install/),
    if you haven’t already.

3.  Install `blender_tissue_cartography`: run
    `pip install blender-tissue-cartography` in a command window.

4.  (Optional) Install extra Python library for `pymeshlab`, required
    for some advanced (re)meshing functionality. This package is not
    available on new ARM Apple computers.

    - run `pip install pymeshlab` in a command window

The project is hosted on
[pip](https://pypi.org/project/blender-tissue-cartography/), with source
code on
[GitHub](https://github.com/nikolas-claussen/blender-tissue-cartography).

#### Developer installation

If you want to extend `blender_tissue_cartography`:

1.  [Clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
    the [github
    repository](https://github.com/nikolas-claussen/blender-tissue-cartography).

2.  Create a `conda` environment with all Python dependencies and
    install the `blender_tissue_cartography` module. Open a command
    window in the `blender-tissue-cartography` directory and type:

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

3.  (Optional) Install extra Python library for `pymeshlab`, required
    for some advanced functionality (remeshing and surface
    reconstruction from within Python).

    - `pip install pymeshlab` - Note that this package is not available
      on new ARM Apple computers.

4.  Install [nbdev](https://nbdev.fast.ai/)

### Known issues

- When using the add-on, please save your `.blend` project to disk
  before using any of the add-on functionality. Otherwise, Blender may
  crash.

- 3D `.tif` files loaded into Blender are not saved to the `.blend`
  (which would explode in size). If you close Blender, you need to
  reimport your 3D image data.

- Please report any issues or bugs you find on GitHub!

## Documentation

- [Documentation
  webpage](https://nikolas-claussen.github.io/blender-tissue-cartography/)

- Datasets and interactive Jupyter notebooks for the tutorials can be
  downloaded [from
  GitHub](https://github.com/nikolas-claussen/blender-tissue-cartography/tree/main/nbs/Tutorials/)

- The [methods
  paper](https://www.biorxiv.org/content/10.1101/2025.02.04.636523v1)
  explains the general idea of tissue cartography, the design of
  `blender_tissue_cartography`, and shows several examples.

## Basic usage

For a complete set of tutorials, see the [documentation
website](https://nikolas-claussen.github.io/blender-tissue-cartography/00_tissue_cartography_overview.html#tutorials).

### Tissue cartography workflow

Tissue cartography starts with a 3D, volumetric image.

1.  Create a segmentation of your 3D data to identify the surface you
    want to extract

2.  Convert the segmentation into a mesh of your surface of interest

3.  Cartographically unwrap the mesh into a 2D plane

4.  Project your 3D data onto the unwrapped mesh

5.  Visualize the results in 3D using blender or use the 2D projected
    data for quantitative analysis.

6.  Batch process multiple 3D images (e.g. frames of a movie)

### Blender add-on

The Blender add-on allows you to carry out steps 2-5 entirely within
Blender. Here is a screenshot using the example [*Drosophila*
dataset](https://github.com/nikolas-claussen/blender-tissue-cartography/blob/main/nbs/Tutorials/addon_example/Drosophila_CAAX-mCherry.tif):

![image.png](index_files/figure-commonmark/cell-7-1-48b7a123-b1e4-4b12-ab3c-e804252bc2b7.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.

In Blender, you can edit meshes and cartographic projections
interactively - you can create a preliminary projection of your data
automatically, and use it as guidance when editing your cartographic map
in blender. Here, we edit the “seam” of our cartographic map based on
the region occupied by cells during zebrafish epiboly (tutorial 6).

![image-2.png](index_files/figure-commonmark/cell-8-1-image-2.png)

### Dynamic datasets

`blender_tissue_cartography` also allows creating cartographic
projections of dynamic datasets (i.e. movies), where the surface of
interest can move or deform over time. The user creates a cartographic
projection for a *reference timepoint* which is transfered to all other
time-points using surface-to-surface registration algorithms. This
generates consistent projections across all timepoints - see tuorials
[8](https://nikolas-claussen.github.io/blender-tissue-cartography/Tutorials/08_multiple_recordings_and_reference_meshes.html)
and
[9](https://nikolas-claussen.github.io/blender-tissue-cartography/Tutorials/09_movies_and_dynamic_surfaces.html).

### Python library

For advanced users, the `blender_tissue_cartography` library allows
creating custom and automated tissue cartography pipelines, typically
run from a jupyter computational notebook (which can also serve as lab
notebook - notes, comments on the data). `blender_tissue_cartography`
also provides tools for correct quantitative analysis of image data on
curved surfaces.

Below is a screenshot to give you an idea of the workflow for the
example *Drosophila* dataset: Volumetric data in ImageJ (center),
jupyter computational notebook to run the `blender_tissue_cartography`
module (left), and blender project with extracted mesh and texture
(right).

### Tutorials

Fully worked-out tutoruals are provided on the [documentation
webpage](https://nikolas-claussen.github.io/blender-tissue-cartography/).
Test data for the tutorials can be downloaded from the [`nbs/Tutorials/`
directory](https://github.com/nikolas-claussen/blender-tissue-cartography/tree/main/nbs/Tutorials).

For the Python library, tutorials take the form of jupyter computational
notebooks which you can download and run on your own computer (click the
green button “Code” to download a `.zip`.) To run a tutorial on your
computer, follow the installation instructions and then [launch
jupyter](https://docs.jupyter.org/en/latest/running.html) and work
through the notebooks in the `Tutorials` directory in order. I
recommended being comfortable with running simple Python code (you don’t
have to do any coding yourself).

The tutorial notebooks can be used as *templates* for your own analysis
pipelines. Here is an example of a jupyter computational notebook
(left), and the created projection visualized in Blender (right).

![image.png](index_files/figure-commonmark/cell-10-1-image.png)

#### Notes for Python beginners

- You will need a working Python installation (see here: [installing
  anaconda/miniconda](https://docs.anaconda.com/miniconda/miniconda-install/),
  and know how to [launch jupyter
  notebooks](https://docs.jupyter.org/en/latest/running.html). You will
  run the computational notebooks in your browser. Here is a [video
  tutorial](https://www.youtube.com/watch?v=HW29067qVWk)

- Create a new folder for each tissue cartography project. Do not place
  them into the folder into which you unpacked
  `blender_tissue_cartography` - otherwise, your files will be
  overwritten if you want to update the software

- The repository contains two sets of notebooks: in the `nbs` folder and
  in the `nbs/Tutorials` folder. The `nbs`-notebooks are for developing
  the code. If you don’t want to develop/adapt the code to your needs,
  you don’t need to look at them. Copy a notebook from the
  `nbs/Tutorials` folder - e.g. `03_basics_example.ipynb` - into your
  project folder to use it as a template.

- You do not need to copy functions into your notebooks manually. If you
  follow the installation instructions, the code will be installed as a
  Python package and can be “imported” by Python. See tutorials!

## Software stack

Note: the Python libraries will be installed automatically if you follow
the installation instructions above.

### Required

- Python, with the following libraries
  - [jupyter](https://jupyter.org/)
  - [numpy](https://numpy.org/) / [Matplotlib](https://matplotlib.org/)
    / [Scipy](https://scipy.org/)
  - [skimage](https://scikit-image.org) various image processing tools.
  - [h5py](https://www.h5py.org/) for reading/writing of `.h5` files.
  - [tifffile](https://github.com/cgohlke/tifffile/) for reading/writing
    of `.tif` files, including metadata.
  - [libigl](https://libigl.github.io/libigl-python-bindings) Geometry
    processing.
- [Ilastik](https://www.ilastik.org/) Image classification and
  segmentation,
- [Blender](https://www.blender.org/) Mesh editing and UV mapping.

### Optional

- [Meshlab](https://www.meshlab.net/) GUI and Python library with
  advanced surface reconstruction tools (required for some workflows).

- Python libraries:

  - [PyMeshLab](https://pymeshlab.readthedocs.io/en/latest/index.html)
    Python interface to MeshLab.
  - [nbdev](https://nbdev.fast.ai/tutorials/tutorial.html) for
    notebook-based development, if you want to add your own code

### Other useful software

- [MicroscopyNodes](https://github.com/oanegros/MicroscopyNodes) plug-in
  for rendering volumetric `.tif` files in blender
- [Boundary First
  Flattening](https://github.com/GeometryCollective/boundary-first-flattening)
  advanced tool for creating UV maps with graphical and command line
  interface
- [pyFM](https://github.com/RobinMagnet/pyFM) python library for
  mesh-to-mesh registration (for dynamic data) which may complement the
  algorithms that ship with `blender_tissue-cartography`

## Acknowledgements

This software is being developed by Nikolas Claussen in the [Streichan
lab at UCSB](https://streichanlab.physics.ucsb.edu/). We thank Cecile
Regis, Susan Wopat, Noah Mitchell, An Yan, Pieter Derksen, Matthew
Lefebvre, Sean Komura, Gary Han, Boris Fosso, and Dillon Cislo, for
sharing data, advice, and software testing.

## 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
