# Voxel
[](https://opensource.org/licenses/Apache-2.0)
[](https://codecov.io/gh/pyvoxel/pyvoxel)
[](https://pyvoxel.readthedocs.io/en/latest/?badge=latest)
[Documentation](http://pyvoxel.readthedocs.io/) | [Installation](https://pyvoxel.readthedocs.io/en/latest/introduction.html) | [Basic Usage](https://pyvoxel.readthedocs.io/en/latest/user_guide.html)
***This is a fork of the original pyvoxel from Arjun Desai. The original repository can be found [here](https://github.com/pyvoxel/pyvoxel).
This repository is maintained by [ORMIR](https://ormim.org).***
Voxel provides fast Pythonic data structures and tools for wrangling with medical images.
## Installation
Voxel requires Python 3.7+. The core module depends on numpy, nibabel, pydicom, requests, and tqdm.
To install Voxel, run:
```bash
pip install ormir-pyvoxel
```
## Features
### Simplified, Efficient I/O
Voxel provides efficient readers for DICOM and NIfTI formats built on nibabel and pydicom.
Multi-slice DICOM data can be loaded in parallel with multiple workers and structured into
the appropriate 3D volume(s). For example, multi-echo and dynamic contrast-enhanced
(DCE) MRI scans have multiple volumes acquired at different echo times and trigger times,
respectively. These can be loaded into multiple volumes with ease:
```python
import voxel as vx
xray = vx.load("path/to/xray.dcm")
ct_scan = vx.load("path/to/ct/folder/")
multi_echo_scan = vx.load("/path/to/multi-echo/scan", group_by="EchoNumbers")
dce_scan = vx.load("/path/to/dce/scan", group_by="TriggerTime")
```
### Data-Embedded Medical Images
Voxel's `MedicalVolume` data structure supports array-like operations (arithmetic, slicing, etc.) on medical images while preserving spatial
attributes and accompanying metadata. This structure supports NumPy interoperability intelligent reformatting, fast low-level computations, and native GPU support. For example, given MedicalVolumes `mv_a` and `mv_b` we can do the following:
```python
# Reformat image into Superior->Inferior, Anterior->Posterior, Left->Right directions.
mv_a = mv_a.reformat(("SI", "AP", "LR"))
# Get and set metadata
study_description = mv_a.get_metadata("StudyDescription")
mv_a.set_metadata("StudyDescription", "A sample study")
# Perform NumPy operations like you would on image data.
rss = np.sqrt(mv_a**2 + mv_b**2)
# Move to GPU 0 for CuPy operations
mv_gpu = mv_a.to(vx.Device(0))
# Take slices. Metadata will be sliced appropriately.
mv_subvolume = mv_a[10:20, 10:20, 4:6]
```
### Easily Prepare Data for AI Pipelines
Voxel enables you to preprocess DICOM images for deep learning in a few lines of code:
```python
# Load a scan, and prepare it for AI/visualization
mv = (
vx.load("/dicoms")
.apply_rescale()
.apply_window()
.to_grayscale()
)
# Zero-copy to PyTorch
arr = mv.to_torch()
```
### Connect with PACS
Voxel provides easy access to data stored in a PACS environment through DICOMweb.
This makes loading data from a remote server just as easy as using the local filesystem.
```python
# Download an MRI from a local Orthanc instance
mv = vx.load("http://localhost:8042/dicom-web/studies/x/series/y", params={"Modality": "MR"})
# Re-use the session for multiple requests
with vx.HttpReader(verbose=True) as hr:
mv_a = hr.load("http://localhost:8042/dicom-web/studies/v/series/w")
mv_b = hr.load("http://localhost:8042/dicom-web/studies/x/series/y")
```
## Contribute
If you would like to contribute to Voxel, we recommend you clone the repository and
install Voxel with `pip` in editable mode.
```bash
git clone git@github.com:pyvoxel/pyvoxel.git
cd pyvoxel
pip install -e '.[dev,docs]'
make dev
```
To run tests, build documentation and contribute, run
```bash
make autoformat test build-docs
```
## Citation
Voxel is a refactored version of the [DOSMA](https://github.com/ad12/dosma) package that focuses on medical image data structures and I/O.
If you use Voxel in your research, please cite the following work:
```
@inproceedings{desai2019dosma,
title={DOSMA: A deep-learning, open-source framework for musculoskeletal MRI analysis},
author={Desai, Arjun D and Barbieri, Marco and Mazzoli, Valentina and Rubin, Elka and Black, Marianne S and Watkins, Lauren E and Gold, Garry E and Hargreaves, Brian A and Chaudhari, Akshay S},
booktitle={Proc 27th Annual Meeting ISMRM, Montreal},
pages={1135},
year={2019}
}
```
In addition to Voxel, please also consider citing the work that introduced the method used for analysis.
Raw data
{
"_id": null,
"home_page": "https://github.com/ormir-mids/ormir-pyvoxel",
"name": "ormir-pyvoxel",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Arjun Desai, Francesco Santini, ORMIR Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/09/de/0b2abab1476043caad273c2b48172acc8da143b222e8b2fdf650013df36c/ormir_pyvoxel-0.0.8.tar.gz",
"platform": null,
"description": "# Voxel\n[](https://opensource.org/licenses/Apache-2.0)\n\n[](https://codecov.io/gh/pyvoxel/pyvoxel)\n[](https://pyvoxel.readthedocs.io/en/latest/?badge=latest)\n\n[Documentation](http://pyvoxel.readthedocs.io/) | [Installation](https://pyvoxel.readthedocs.io/en/latest/introduction.html) | [Basic Usage](https://pyvoxel.readthedocs.io/en/latest/user_guide.html)\n\n***This is a fork of the original pyvoxel from Arjun Desai. The original repository can be found [here](https://github.com/pyvoxel/pyvoxel).\nThis repository is maintained by [ORMIR](https://ormim.org).***\n\nVoxel provides fast Pythonic data structures and tools for wrangling with medical images.\n\n## Installation\nVoxel requires Python 3.7+. The core module depends on numpy, nibabel, pydicom, requests, and tqdm.\n\nTo install Voxel, run:\n\n```bash\npip install ormir-pyvoxel\n```\n\n## Features\n### Simplified, Efficient I/O\nVoxel provides efficient readers for DICOM and NIfTI formats built on nibabel and pydicom.\nMulti-slice DICOM data can be loaded in parallel with multiple workers and structured into\nthe appropriate 3D volume(s). For example, multi-echo and dynamic contrast-enhanced\n(DCE) MRI scans have multiple volumes acquired at different echo times and trigger times,\nrespectively. These can be loaded into multiple volumes with ease:\n\n```python\nimport voxel as vx\n\nxray = vx.load(\"path/to/xray.dcm\")\nct_scan = vx.load(\"path/to/ct/folder/\")\n\nmulti_echo_scan = vx.load(\"/path/to/multi-echo/scan\", group_by=\"EchoNumbers\")\ndce_scan = vx.load(\"/path/to/dce/scan\", group_by=\"TriggerTime\")\n```\n\n### Data-Embedded Medical Images\nVoxel's `MedicalVolume` data structure supports array-like operations (arithmetic, slicing, etc.) on medical images while preserving spatial\nattributes and accompanying metadata. This structure supports NumPy interoperability intelligent reformatting, fast low-level computations, and native GPU support. For example, given MedicalVolumes `mv_a` and `mv_b` we can do the following:\n\n```python\n# Reformat image into Superior->Inferior, Anterior->Posterior, Left->Right directions.\nmv_a = mv_a.reformat((\"SI\", \"AP\", \"LR\"))\n\n# Get and set metadata\nstudy_description = mv_a.get_metadata(\"StudyDescription\")\nmv_a.set_metadata(\"StudyDescription\", \"A sample study\")\n\n# Perform NumPy operations like you would on image data.\nrss = np.sqrt(mv_a**2 + mv_b**2)\n\n# Move to GPU 0 for CuPy operations\nmv_gpu = mv_a.to(vx.Device(0))\n\n# Take slices. Metadata will be sliced appropriately.\nmv_subvolume = mv_a[10:20, 10:20, 4:6]\n```\n\n### Easily Prepare Data for AI Pipelines\nVoxel enables you to preprocess DICOM images for deep learning in a few lines of code:\n\n```python\n# Load a scan, and prepare it for AI/visualization\nmv = (\n vx.load(\"/dicoms\")\n .apply_rescale()\n .apply_window()\n .to_grayscale()\n)\n\n# Zero-copy to PyTorch\narr = mv.to_torch()\n```\n\n### Connect with PACS\nVoxel provides easy access to data stored in a PACS environment through DICOMweb.\nThis makes loading data from a remote server just as easy as using the local filesystem.\n\n```python\n# Download an MRI from a local Orthanc instance\nmv = vx.load(\"http://localhost:8042/dicom-web/studies/x/series/y\", params={\"Modality\": \"MR\"})\n\n# Re-use the session for multiple requests\nwith vx.HttpReader(verbose=True) as hr:\n mv_a = hr.load(\"http://localhost:8042/dicom-web/studies/v/series/w\")\n mv_b = hr.load(\"http://localhost:8042/dicom-web/studies/x/series/y\")\n```\n\n## Contribute\nIf you would like to contribute to Voxel, we recommend you clone the repository and\ninstall Voxel with `pip` in editable mode.\n\n```bash\ngit clone git@github.com:pyvoxel/pyvoxel.git\ncd pyvoxel\npip install -e '.[dev,docs]'\nmake dev\n```\n\nTo run tests, build documentation and contribute, run\n```bash\nmake autoformat test build-docs\n```\n\n## Citation\nVoxel is a refactored version of the [DOSMA](https://github.com/ad12/dosma) package that focuses on medical image data structures and I/O.\nIf you use Voxel in your research, please cite the following work:\n\n```\n@inproceedings{desai2019dosma,\n title={DOSMA: A deep-learning, open-source framework for musculoskeletal MRI analysis},\n author={Desai, Arjun D and Barbieri, Marco and Mazzoli, Valentina and Rubin, Elka and Black, Marianne S and Watkins, Lauren E and Gold, Garry E and Hargreaves, Brian A and Chaudhari, Akshay S},\n booktitle={Proc 27th Annual Meeting ISMRM, Montreal},\n pages={1135},\n year={2019}\n}\n```\n\nIn addition to Voxel, please also consider citing the work that introduced the method used for analysis.\n",
"bugtrack_url": null,
"license": "GNU",
"summary": "I/O routines for medical imaging data",
"version": "0.0.8",
"project_urls": {
"Documentation": "https://pyvoxel.readthedocs.io/",
"Homepage": "https://github.com/ormir-mids/ormir-pyvoxel"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8fa25babc7a73f0044552e94577c26137e4c2b7fc52e8111aeb67437bbfed2b9",
"md5": "7242476ba2cc27435fadc21ff1d067fa",
"sha256": "117e9c03151da655b93a1a15538034f610c967cefcccd94f975fd07d861d91c2"
},
"downloads": -1,
"filename": "ormir_pyvoxel-0.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7242476ba2cc27435fadc21ff1d067fa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 65769,
"upload_time": "2025-02-03T12:58:17",
"upload_time_iso_8601": "2025-02-03T12:58:17.923550Z",
"url": "https://files.pythonhosted.org/packages/8f/a2/5babc7a73f0044552e94577c26137e4c2b7fc52e8111aeb67437bbfed2b9/ormir_pyvoxel-0.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "09de0b2abab1476043caad273c2b48172acc8da143b222e8b2fdf650013df36c",
"md5": "4da29b06925310bce18c7fc5ed65a0f5",
"sha256": "106e7373eaf7568aa236a51b6c96a655eb5a078e368658a10bcab9fddd87db07"
},
"downloads": -1,
"filename": "ormir_pyvoxel-0.0.8.tar.gz",
"has_sig": false,
"md5_digest": "4da29b06925310bce18c7fc5ed65a0f5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 70355,
"upload_time": "2025-02-03T12:58:20",
"upload_time_iso_8601": "2025-02-03T12:58:20.012111Z",
"url": "https://files.pythonhosted.org/packages/09/de/0b2abab1476043caad273c2b48172acc8da143b222e8b2fdf650013df36c/ormir_pyvoxel-0.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-03 12:58:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ormir-mids",
"github_project": "ormir-pyvoxel",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "dataclasses",
"specs": [
[
">=",
"0.6"
]
]
},
{
"name": "numpy",
"specs": []
},
{
"name": "natsort",
"specs": []
},
{
"name": "nibabel",
"specs": []
},
{
"name": "packaging",
"specs": []
},
{
"name": "pydicom",
"specs": [
[
">=",
"2.2.0"
]
]
},
{
"name": "PyYAML",
"specs": [
[
">=",
"5.4.1"
]
]
},
{
"name": "requests",
"specs": []
},
{
"name": "tabulate",
"specs": []
},
{
"name": "termcolor",
"specs": []
},
{
"name": "tqdm",
"specs": [
[
">=",
"4.42.0"
]
]
}
],
"lcname": "ormir-pyvoxel"
}
JSON
