DriftlessMap

Interactive histology registration and brain-atlas mapping.

DriftlessMap is an open-source desktop application for registering histological images to reference brain atlases, reconstructing probes and other anatomical objects, and visualizing data in 2D and 3D. The name refers to Wisconsin's Driftless Area and to the project's focus on dependable spatial mapping.

Origin and independence

DriftlessMap began as a fork of HERBS — Histological E-data Registration in rodent Brain Spaces — originally created by Jingyi Guo Fuglstad, Pearl Saldanha, Jacopo Paglia, Jonathan R. Whitlock, and HERBS contributors.

DriftlessMap is independently maintained. It is not affiliated with or endorsed by the original HERBS developers. Their foundational work remains credited in the Git history, license, project history, contributors, authors, and acknowledgements.

Current development is led by Mohebi & Associates, with Ali Mohebi as project lead and maintainer.

If DriftlessMap contributes to published research, please cite both the software version used and the original HERBS paper:

Fuglstad, J. G., Saldanha, P., Paglia, J., & Whitlock, J. R. (2023). Histological E-data Registration in rodent Brain Spaces. eLife, 12, e83496. https://doi.org/10.7554/eLife.83496

See CITATION.cff for machine-readable citation metadata.

Features

• 2D and 3D visualization of volumetric brain atlases and arbitrary slices.
• Interactive histology-to-atlas registration with local elastic deformation.
• Probe planning, reconstruction, contact mapping, and CSV export.
• Drawing, cell, virus-expression, and user-defined object workflows.
• Safe, versioned project and object archives.
• Support for custom compatible atlases.

Install from PyPI

DriftlessMap 1.2.0 supports Python 3.10–3.14 and Qt 6 through PyQt6. Python 3.14 in a dedicated environment is recommended for new installations.

Install the latest stable release:

python -m pip install driftlessmap

For a dedicated Conda environment:

conda create --name DriftlessMap python=3.14 -y
conda activate DriftlessMap
python -m pip install --upgrade pip
python -m pip install driftlessmap

Launch the application with any of:

driftlessmap
python -m driftlessmap

import driftlessmap

driftlessmap.run()

For an editable development install, clone the repository and use python -m pip install -e ..

Zeiss CZI files

CZI support uses the optional aicspylibczi package, whose prebuilt packages currently support Python through 3.13:

conda create --name DriftlessMap-CZI python=3.13 -y
conda activate DriftlessMap-CZI
python -m pip install --upgrade pip
python -m pip install "driftlessmap[czi]"

Compatibility with HERBS

The rebrand is designed not to strand existing research data:

• DriftlessMap reads legacy .herbs, .herbslayer, .herbsobj, .herbsslice, and .herbstri files.
• New files use .dmap, .dmaplayer, .dmapobj, .dmapslice, and .dmaptri.
• DriftlessMap installs only the driftlessmap Python package and command. It does not overwrite the original HERBS package, so both distributions can be installed in the same environment. New code should use import driftlessmap.
• Existing HERBS_CONFIG_DIR overrides remain supported. New configurations should use DRIFTLESSMAP_CONFIG_DIR.
• Some persisted coordinate field names retain herbs because changing them would break existing datasets and downstream analysis scripts.

The original HERBS application may not be able to open files newly written by DriftlessMap. Keep backups before converting important projects.

Documentation

Read the DriftlessMap User Manual for installation, atlas, registration, reconstruction, persistence, export, and troubleshooting guidance. The original HERBS Cookbook and tutorials remain useful for workflows whose interface has not changed.

The screenshot below is retained from HERBS for historical workflow reference; its title bar predates the DriftlessMap rebrand.

Do not store downloaded atlases inside the source or installed package directory. Keep each atlas in its own external folder.

See What’s New in DriftlessMap for release history and migration notes.

License

DriftlessMap is distributed under the MIT License. The original HERBS copyright and permission notice are preserved, and a separate copyright notice covers subsequent DriftlessMap modifications. See LICENSE.txt and ORIGINS.md.

Please report issues or start discussions at https://github.com/mohebi-n-associates/DriftlessMap.