# MagellanMapper
MagellanMapper is a graphical imaging informatics suite for 3D reconstruction and automated analysis of whole specimens and atlases. Its design philosophy is to make the raw 3D images as accessible as possible, simplify annotation from nuclei to atlases, and scale from the laptop or desktop to the cloud in cross-platform environments.
<a href="https://www.ncbi.nlm.nih.gov/pmc/articles/PMC7781073/"><img align="right" width="200" src="https://user-images.githubusercontent.com/1258953/179440433-0326c4d5-9a9b-4bae-92c7-d09416375bc5.png" title="Current Protocols cover image"></a>
## Quick Reference
- [Docs are now on ReadTheDocs!](https://magellanmapper.readthedocs.io/en/latest/)
- **NEW**: [Vignette of pipelines](bin/sample_cmds_bash.ipynb)
- [Installation](#quick-install) (more [details](docs/install.md))
- [Intro to running MagellanMapper](#run-magellanmapper)
- [Using the viewers](docs/viewers.md)
- [Command-line interface](docs/cli.md)
- [Configuration and settings](docs/settings.md)
- [Publications](#related-publications-and-datasets)
## Quick Install
Install MagellanMapper with its graphical interface and registration tools:
```shell
pip install "magellanmapper[gui,itk]"
```
Then launch MagellanMapper:
```shell
mm
```
## Full Install
Alternatively, [Conda](https://docs.conda.io/en/latest/miniconda.html) can be used to install MagellanMapper along with support for importing proprietary image file formats (*note: not currently working on Apple Silicon (Mac M-chip) platforms*):
```shell
conda env create -n mag -f https://raw.githubusercontent.com/sanderslab/magellanmapper/master/envs/environment_rel.yml
```
Then activate the environment (`mag`) and run MagellanMapper:
```shell
conda activate mag
mm
```
If you have [Java](https://www.azul.com/downloads/?package=jdk), you can do the same through Pip:
```shell
pip install "magellanmapper[most]" --extra-index-url https://pypi.fury.io/dd8/
```
The extra index accesses a few [customized dependencies](docs/install.md#custom-packages) for MagellanMapper.
For the latest updates and fixes, download from Git and install:
```shell
git clone https://github.com/sanderslab/magellanmapper.git
cd magellanmapper
conda env create -n mag -f environment.yml
python run.py
```
Or for Pip, replace the `conda` line with:
```shell
pip install -e ".[most]" --extra-index-url https://pypi.fury.io/dd8/
```
### More ways to install and run
See the [install docs](docs/install.md) for more details, including:
- [Installer scripts](docs/install.md#installer-scripts), which install Miniconda and MagellanMapper without requiring command-line usage
- [Installer packages](docs/install.md#installer-packages), for point-and-click installation
## Using MagellanMapper
MagellanMapper consists of a graphical user interface (GUI), command-line interface (CLI), and application programming interface (API) for Python programmatic access. See the [GUI docs](docs/viewers.md) for graphical usage and the [CLI docs](docs/cli.md) for scripting.
For automated tasks, see the [`sample_cmds_bash.ipynb`](bin/sample_cmds_bash.ipynb) Jupyter Notebook (or the older [`sample_cmds.sh`](bin/sample_cmds.sh) script) that shows examples of running the CLI and exploring images in the GUI. See ReadTheDocs for more details, including [viewer shortcuts](docs/viewers.md) and customizing [settings](docs/settings.md) for your image analysis.
Have a question? Found a bug? Want a feature? Please [ask](https://github.com/sanderslab/magellanmapper/issues)!
### Image file import
Large images or proprietary microscopy formats such as CZI can be imported by MagellanMapper into NumPy format, which allows on-the-fly loading to reduce memory requirements and initial loading time. In the "Import" tab, you can select files, view and update metadata, and import the files.
Medical imaging formats such as `.mha` (or `.mhd/.raw`) and `.nii` (or `.nii.gz`) can be opened with the SimpleITK/SimpleElastix library and do not require separate import.
### Sample 3D data
To try out functions with sample images, download any of these files:
- [Sample region of nuclei at 4x (`sample_region.zip`)](https://github.com/sanderslab/magellanmapper/releases/download/v1.1.3/sample_region.zip)
- [Sample downsampled tissue cleared whole brain (`sample_brain.zip`)](https://github.com/sanderslab/magellanmapper/releases/download/v1.1.3/sample_brain.zip)
- [Allen Developing Mouse Brain Atlas E18.5 (`ADMBA-E18pt5.zip`)](https://github.com/sanderslab/magellanmapper/releases/download/v1.1.3/ADMBA-E18pt5.zip)
## Related publications and datasets
- For more information on the methods used for 3D atlas construction, please see: https://elifesciences.org/articles/61408
- For step-by-step instructions on using v1.3.x of the software, please see: https://currentprotocols.onlinelibrary.wiley.com/doi/abs/10.1002/cpns.104 (now [open access on PubMed](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC7781073/)!); see [ReadTheDocs](https://magellanmapper.readthedocs.io/en/latest/) for ongoing updates
- The 3D reconstructed versions of the Allen Developing Mouse Brain Atlas: https://search.kg.ebrains.eu/instances/Project/b8a8e2d3-4787-45f2-b010-589948c33f20
- Sample wild-type whole mouse brains at age P0: https://search.kg.ebrains.eu/instances/Dataset/2423e103-35e9-40cf-ab0c-0e3d08d24d5a
Licensed under the open-source [BSD-3 license](LICENSE.txt)
Author: David Young, 2017, 2023, Stephan Sanders Lab
Raw data
{
"_id": null,
"home_page": "https://github.com/sanderslab/magellanmapper",
"name": "magellanmapper",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "David Young",
"author_email": "david@textflex.com",
"download_url": "https://files.pythonhosted.org/packages/a8/dd/f40f294726c06a7b834e001e3114c7c080690f21224ebac86004ae6a9e38/magellanmapper-1.6b4.tar.gz",
"platform": null,
"description": "# MagellanMapper\n\nMagellanMapper is a graphical imaging informatics suite for 3D reconstruction and automated analysis of whole specimens and atlases. Its design philosophy is to make the raw 3D images as accessible as possible, simplify annotation from nuclei to atlases, and scale from the laptop or desktop to the cloud in cross-platform environments.\n\n\n\n<a href=\"https://www.ncbi.nlm.nih.gov/pmc/articles/PMC7781073/\"><img align=\"right\" width=\"200\" src=\"https://user-images.githubusercontent.com/1258953/179440433-0326c4d5-9a9b-4bae-92c7-d09416375bc5.png\" title=\"Current Protocols cover image\"></a>\n\n\n## Quick Reference\n\n- [Docs are now on ReadTheDocs!](https://magellanmapper.readthedocs.io/en/latest/)\n- **NEW**: [Vignette of pipelines](bin/sample_cmds_bash.ipynb)\n- [Installation](#quick-install) (more [details](docs/install.md))\n- [Intro to running MagellanMapper](#run-magellanmapper)\n- [Using the viewers](docs/viewers.md)\n- [Command-line interface](docs/cli.md)\n- [Configuration and settings](docs/settings.md)\n- [Publications](#related-publications-and-datasets)\n\n\n## Quick Install\n\nInstall MagellanMapper with its graphical interface and registration tools:\n\n```shell\npip install \"magellanmapper[gui,itk]\"\n```\n\nThen launch MagellanMapper:\n\n```shell\nmm\n```\n\n## Full Install\n\nAlternatively, [Conda](https://docs.conda.io/en/latest/miniconda.html) can be used to install MagellanMapper along with support for importing proprietary image file formats (*note: not currently working on Apple Silicon (Mac M-chip) platforms*):\n\n```shell\nconda env create -n mag -f https://raw.githubusercontent.com/sanderslab/magellanmapper/master/envs/environment_rel.yml\n```\n\nThen activate the environment (`mag`) and run MagellanMapper:\n\n```shell\nconda activate mag\nmm\n```\n\nIf you have [Java](https://www.azul.com/downloads/?package=jdk), you can do the same through Pip:\n\n```shell\npip install \"magellanmapper[most]\" --extra-index-url https://pypi.fury.io/dd8/\n```\n\nThe extra index accesses a few [customized dependencies](docs/install.md#custom-packages) for MagellanMapper.\n\nFor the latest updates and fixes, download from Git and install:\n\n```shell\ngit clone https://github.com/sanderslab/magellanmapper.git\ncd magellanmapper\nconda env create -n mag -f environment.yml\npython run.py\n```\n\nOr for Pip, replace the `conda` line with:\n\n```shell\npip install -e \".[most]\" --extra-index-url https://pypi.fury.io/dd8/\n```\n\n\n### More ways to install and run\n\nSee the [install docs](docs/install.md) for more details, including:\n\n- [Installer scripts](docs/install.md#installer-scripts), which install Miniconda and MagellanMapper without requiring command-line usage\n- [Installer packages](docs/install.md#installer-packages), for point-and-click installation\n\n## Using MagellanMapper\n\nMagellanMapper consists of a graphical user interface (GUI), command-line interface (CLI), and application programming interface (API) for Python programmatic access. See the [GUI docs](docs/viewers.md) for graphical usage and the [CLI docs](docs/cli.md) for scripting.\n\nFor automated tasks, see the [`sample_cmds_bash.ipynb`](bin/sample_cmds_bash.ipynb) Jupyter Notebook (or the older [`sample_cmds.sh`](bin/sample_cmds.sh) script) that shows examples of running the CLI and exploring images in the GUI. See ReadTheDocs for more details, including [viewer shortcuts](docs/viewers.md) and customizing [settings](docs/settings.md) for your image analysis.\n\nHave a question? Found a bug? Want a feature? Please [ask](https://github.com/sanderslab/magellanmapper/issues)!\n\n### Image file import\n\nLarge images or proprietary microscopy formats such as CZI can be imported by MagellanMapper into NumPy format, which allows on-the-fly loading to reduce memory requirements and initial loading time. In the \"Import\" tab, you can select files, view and update metadata, and import the files.\n\nMedical imaging formats such as `.mha` (or `.mhd/.raw`) and `.nii` (or `.nii.gz`) can be opened with the SimpleITK/SimpleElastix library and do not require separate import. \n\n### Sample 3D data\n\nTo try out functions with sample images, download any of these files:\n\n- [Sample region of nuclei at 4x (`sample_region.zip`)](https://github.com/sanderslab/magellanmapper/releases/download/v1.1.3/sample_region.zip)\n- [Sample downsampled tissue cleared whole brain (`sample_brain.zip`)](https://github.com/sanderslab/magellanmapper/releases/download/v1.1.3/sample_brain.zip)\n- [Allen Developing Mouse Brain Atlas E18.5 (`ADMBA-E18pt5.zip`)](https://github.com/sanderslab/magellanmapper/releases/download/v1.1.3/ADMBA-E18pt5.zip)\n\n## Related publications and datasets\n\n- For more information on the methods used for 3D atlas construction, please see: https://elifesciences.org/articles/61408\n- For step-by-step instructions on using v1.3.x of the software, please see: https://currentprotocols.onlinelibrary.wiley.com/doi/abs/10.1002/cpns.104 (now [open access on PubMed](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC7781073/)!); see [ReadTheDocs](https://magellanmapper.readthedocs.io/en/latest/) for ongoing updates\n- The 3D reconstructed versions of the Allen Developing Mouse Brain Atlas: https://search.kg.ebrains.eu/instances/Project/b8a8e2d3-4787-45f2-b010-589948c33f20\n- Sample wild-type whole mouse brains at age P0: https://search.kg.ebrains.eu/instances/Dataset/2423e103-35e9-40cf-ab0c-0e3d08d24d5a\n\nLicensed under the open-source [BSD-3 license](LICENSE.txt)\n\nAuthor: David Young, 2017, 2023, Stephan Sanders Lab\n",
"bugtrack_url": null,
"license": "BSD-3",
"summary": "3D atlas analysis and annotation",
"version": "1.6b4",
"project_urls": {
"Homepage": "https://github.com/sanderslab/magellanmapper"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9d547052454b67e3c6aa36414e4ca80c1e72a85bf3ad4947e607ce5291a0dae8",
"md5": "0c22056e39d561d457f74d47865e2de4",
"sha256": "f6213525b8a7b064808745d2060810a19834e26b1994239ca805c61ec7ef2c03"
},
"downloads": -1,
"filename": "magellanmapper-1.6b4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0c22056e39d561d457f74d47865e2de4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 487577,
"upload_time": "2024-04-13T18:10:05",
"upload_time_iso_8601": "2024-04-13T18:10:05.909682Z",
"url": "https://files.pythonhosted.org/packages/9d/54/7052454b67e3c6aa36414e4ca80c1e72a85bf3ad4947e607ce5291a0dae8/magellanmapper-1.6b4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a8ddf40f294726c06a7b834e001e3114c7c080690f21224ebac86004ae6a9e38",
"md5": "b629bb39f4966ac835913ed4f5f59ce0",
"sha256": "b29e7f904d968f565442ebd40c74dcb043b7840efb904aed8fc2684b1137c3e5"
},
"downloads": -1,
"filename": "magellanmapper-1.6b4.tar.gz",
"has_sig": false,
"md5_digest": "b629bb39f4966ac835913ed4f5f59ce0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 451557,
"upload_time": "2024-04-13T18:10:08",
"upload_time_iso_8601": "2024-04-13T18:10:08.577514Z",
"url": "https://files.pythonhosted.org/packages/a8/dd/f40f294726c06a7b834e001e3114c7c080690f21224ebac86004ae6a9e38/magellanmapper-1.6b4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-13 18:10:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sanderslab",
"github_project": "magellanmapper",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "magellanmapper"
}
JSON
