Metadata-Version: 2.4
Name: driftlessmap
Version: 1.1.0
Summary: Interactive histology registration and brain-atlas mapping
Author: Pearl Saldanha, Jacopo Paglia, Jonathan R. Whitlock, Mohebi & Associates, Ali Mohebi
Author-email: Jingyi Guo Fuglstad <jingyi.g.fuglstad@gmail.com>
Maintainer: Mohebi & Associates, Ali Mohebi
License-Expression: MIT
Project-URL: Homepage, https://github.com/mohebi-n-associates/DriftlessMap
Project-URL: Bug Tracker, https://github.com/mohebi-n-associates/DriftlessMap/issues
Project-URL: Documentation, https://github.com/mohebi-n-associates/DriftlessMap#readme
Project-URL: Maintaining Organization, https://www.mohebi-associates.org/
Project-URL: Lead Maintainer, https://www.mohebial.com/
Keywords: brain atlas,histological image registration,probe coordinates
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: PyQt6<7,>=6.8
Requires-Dist: pyqtgraph<0.15,>=0.14
Requires-Dist: PyOpenGL<4,>=3.1.7
Requires-Dist: superqt<0.9,>=0.8
Requires-Dist: opencv-python<6,>=4.10
Requires-Dist: numba<1,>=0.61
Requires-Dist: numpy<3,>=2.0
Requires-Dist: scipy<2,>=1.13
Requires-Dist: requests<3,>=2.32
Requires-Dist: nibabel<6,>=5.2
Requires-Dist: pynrrd<2,>=1.0
Requires-Dist: tifffile>=2024.7
Requires-Dist: pandas<4,>=2.2
Requires-Dist: natsort<9,>=8.4
Requires-Dist: imagecodecs>=2024.6
Provides-Extra: czi
Requires-Dist: aicspylibczi>=3.3.1; python_version < "3.14" and extra == "czi"
Provides-Extra: test
Requires-Dist: pytest>=8.3; extra == "test"
Requires-Dist: ruff>=0.9; extra == "test"
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "test"
Dynamic: license-file

# 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](https://github.com/Whitlock-Group/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](LICENSE.txt), [project history](ORIGINS.md),
[contributors](CONTRIBUTORS.md), [authors](AUTHOR.txt), and
[acknowledgements](THANKS.txt).

Current development is led by
[Mohebi & Associates](https://www.mohebi-associates.org/), with
[Ali Mohebi](https://www.mohebial.com/) 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](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

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

```bash
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:

```bash
driftlessmap
python -m driftlessmap
```

```python
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:

```bash
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](MANUAL.md) for installation, atlas,
registration, reconstruction, persistence, export, and troubleshooting
guidance. The original [HERBS Cookbook](CookBook.pdf) and [tutorials](Tutorial)
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.

<img src="./driftlessmap/herbs.png" width="800px" alt="Historical HERBS interface used as the basis for DriftlessMap">

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](WhatsNew.md) 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](LICENSE.txt) and
[ORIGINS.md](ORIGINS.md).

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