# 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/f2/6e/bc62592f567a9c0a1a25da328487dd40d170307e858a0f05f041ce56785c/ormir_pyvoxel-0.0.7.tar.gz",
"platform": null,
"description": "# Voxel\r\n[](https://opensource.org/licenses/Apache-2.0)\r\n\r\n[](https://codecov.io/gh/pyvoxel/pyvoxel)\r\n[](https://pyvoxel.readthedocs.io/en/latest/?badge=latest)\r\n\r\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)\r\n\r\n***This is a fork of the original pyvoxel from Arjun Desai. The original repository can be found [here](https://github.com/pyvoxel/pyvoxel).\r\nThis repository is maintained by [ORMIR](https://ormim.org).***\r\n\r\nVoxel provides fast Pythonic data structures and tools for wrangling with medical images.\r\n\r\n## Installation\r\nVoxel requires Python 3.7+. The core module depends on numpy, nibabel, pydicom, requests, and tqdm.\r\n\r\nTo install Voxel, run:\r\n\r\n```bash\r\npip install ormir-pyvoxel\r\n```\r\n\r\n## Features\r\n### Simplified, Efficient I/O\r\nVoxel provides efficient readers for DICOM and NIfTI formats built on nibabel and pydicom.\r\nMulti-slice DICOM data can be loaded in parallel with multiple workers and structured into\r\nthe appropriate 3D volume(s). For example, multi-echo and dynamic contrast-enhanced\r\n(DCE) MRI scans have multiple volumes acquired at different echo times and trigger times,\r\nrespectively. These can be loaded into multiple volumes with ease:\r\n\r\n```python\r\nimport voxel as vx\r\n\r\nxray = vx.load(\"path/to/xray.dcm\")\r\nct_scan = vx.load(\"path/to/ct/folder/\")\r\n\r\nmulti_echo_scan = vx.load(\"/path/to/multi-echo/scan\", group_by=\"EchoNumbers\")\r\ndce_scan = vx.load(\"/path/to/dce/scan\", group_by=\"TriggerTime\")\r\n```\r\n\r\n### Data-Embedded Medical Images\r\nVoxel's `MedicalVolume` data structure supports array-like operations (arithmetic, slicing, etc.) on medical images while preserving spatial\r\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:\r\n\r\n```python\r\n# Reformat image into Superior->Inferior, Anterior->Posterior, Left->Right directions.\r\nmv_a = mv_a.reformat((\"SI\", \"AP\", \"LR\"))\r\n\r\n# Get and set metadata\r\nstudy_description = mv_a.get_metadata(\"StudyDescription\")\r\nmv_a.set_metadata(\"StudyDescription\", \"A sample study\")\r\n\r\n# Perform NumPy operations like you would on image data.\r\nrss = np.sqrt(mv_a**2 + mv_b**2)\r\n\r\n# Move to GPU 0 for CuPy operations\r\nmv_gpu = mv_a.to(vx.Device(0))\r\n\r\n# Take slices. Metadata will be sliced appropriately.\r\nmv_subvolume = mv_a[10:20, 10:20, 4:6]\r\n```\r\n\r\n### Easily Prepare Data for AI Pipelines\r\nVoxel enables you to preprocess DICOM images for deep learning in a few lines of code:\r\n\r\n```python\r\n# Load a scan, and prepare it for AI/visualization\r\nmv = (\r\n vx.load(\"/dicoms\")\r\n .apply_rescale()\r\n .apply_window()\r\n .to_grayscale()\r\n)\r\n\r\n# Zero-copy to PyTorch\r\narr = mv.to_torch()\r\n```\r\n\r\n### Connect with PACS\r\nVoxel provides easy access to data stored in a PACS environment through DICOMweb.\r\nThis makes loading data from a remote server just as easy as using the local filesystem.\r\n\r\n```python\r\n# Download an MRI from a local Orthanc instance\r\nmv = vx.load(\"http://localhost:8042/dicom-web/studies/x/series/y\", params={\"Modality\": \"MR\"})\r\n\r\n# Re-use the session for multiple requests\r\nwith vx.HttpReader(verbose=True) as hr:\r\n mv_a = hr.load(\"http://localhost:8042/dicom-web/studies/v/series/w\")\r\n mv_b = hr.load(\"http://localhost:8042/dicom-web/studies/x/series/y\")\r\n```\r\n\r\n## Contribute\r\nIf you would like to contribute to Voxel, we recommend you clone the repository and\r\ninstall Voxel with `pip` in editable mode.\r\n\r\n```bash\r\ngit clone git@github.com:pyvoxel/pyvoxel.git\r\ncd pyvoxel\r\npip install -e '.[dev,docs]'\r\nmake dev\r\n```\r\n\r\nTo run tests, build documentation and contribute, run\r\n```bash\r\nmake autoformat test build-docs\r\n```\r\n\r\n## Citation\r\nVoxel is a refactored version of the [DOSMA](https://github.com/ad12/dosma) package that focuses on medical image data structures and I/O.\r\nIf you use Voxel in your research, please cite the following work:\r\n\r\n```\r\n@inproceedings{desai2019dosma,\r\n title={DOSMA: A deep-learning, open-source framework for musculoskeletal MRI analysis},\r\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},\r\n booktitle={Proc 27th Annual Meeting ISMRM, Montreal},\r\n pages={1135},\r\n year={2019}\r\n}\r\n```\r\n\r\nIn addition to Voxel, please also consider citing the work that introduced the method used for analysis.\r\n",
"bugtrack_url": null,
"license": "GNU",
"summary": "I/O routines for medical imaging data",
"version": "0.0.7",
"project_urls": {
"Documentation": "https://pyvoxel.readthedocs.io/",
"Homepage": "https://github.com/ormir-mids/ormir-pyvoxel"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "af78ae5c77a353cf2017b5aa61929ca65d17690828c05fd64ccb47e6ed0f1231",
"md5": "9799ceb7ea84211d8c68b00b94a59600",
"sha256": "fa0cb8d07d9b4f3f61362a7a4f87d320c0cdc6ee9c53fc80971e22dab068db59"
},
"downloads": -1,
"filename": "ormir_pyvoxel-0.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9799ceb7ea84211d8c68b00b94a59600",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 66166,
"upload_time": "2024-12-05T17:09:18",
"upload_time_iso_8601": "2024-12-05T17:09:18.422085Z",
"url": "https://files.pythonhosted.org/packages/af/78/ae5c77a353cf2017b5aa61929ca65d17690828c05fd64ccb47e6ed0f1231/ormir_pyvoxel-0.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f26ebc62592f567a9c0a1a25da328487dd40d170307e858a0f05f041ce56785c",
"md5": "49a417be50eb35b0a8e5d186753ae810",
"sha256": "a7f1b551a74c61797fe58574767ef424ec801f46e0b7c94f022ff6a4a787c18c"
},
"downloads": -1,
"filename": "ormir_pyvoxel-0.0.7.tar.gz",
"has_sig": false,
"md5_digest": "49a417be50eb35b0a8e5d186753ae810",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 70755,
"upload_time": "2024-12-05T17:09:20",
"upload_time_iso_8601": "2024-12-05T17:09:20.378792Z",
"url": "https://files.pythonhosted.org/packages/f2/6e/bc62592f567a9c0a1a25da328487dd40d170307e858a0f05f041ce56785c/ormir_pyvoxel-0.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-05 17:09: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
