#########
imagedata
#########
|coverage|
|Docs Badge|
|zenodo| |joss|
|pypi| |pyversions| |downloads| |buildstatus|
Imagedata is a python library to read and write medical image data into numpy arrays.
Imagedata will handle multi-dimensional data.
In particular, imagedata will read and sort DICOM 3D and 4D series based on
defined tags.
Imagedata will handle geometry information between the formats.
The following formats are included:
* DICOM
* Nifti
* ITK (MetaIO)
* Matlab
* PostScript (input only)
Other formats can be added through a plugin architecture.
Install
-------------------
.. code-block::
pip install imagedata
Documentation
----------------
See the Documentation_ page for info.
.. _Documentation: https://imagedata.readthedocs.io
Example code
-------------------
A simple example reading two time series from dirA and dirB, and writing their mean to dirMean:
.. code-block:: python
from imagedata import Series
a = Series('dirA', 'time')
b = Series('dirB', 'time')
assert a.shape == b.shape, "Shape of a and b differ"
# Notice how a and b are treated as numpy arrays
c = (a + b) / 2
c.write('dirMean')
Sorting
-------
Sorting of DICOM slices is considered a major task. Imagedata will sort slices into volumes based on slice location.
Volumes may be sorted on a number of DICOM tags:
* 'time': Dynamic time series, sorted on acquisition time
* 'b': Diffusion weighted series, sorted on diffusion b value
* 'fa': Flip angle series, sorted on flip angle
* 'te': Sort on echo time TE
In addition, volumes can be sorted on user defined tags.
Non-DICOM formats usually don't specify the labelling of the 4D data.
In this case, you can specify the sorting manually.
Viewing
-------
A simple viewer. Scroll through the image stack, step through the tags of a 4D dataset.
These operations are possible:
* Read-out voxel value: Move mouse over.
* Window/level adjustment: Move mouse with left key pressed.
* Scroll through slices of an image stack: Mouse scroll wheel, or up/down array keys.
* Step through tags (time, b-values, etc.): Left/right array keys.
* Move through series when many series are displayed: PageUp/PageDown keys.
.. code-block:: python
# View a Series instance
a.show()
# View both a and b Series
a.show(b)
# View several Series
a.show([b, c, d])
Converting data from DICOM and back
-----------------------------------
In many situations you need to process patient data using a tool that do not accept DICOM data.
In order to maintain the coupling to patient data, you may convert your data to e.g. Nifti and back.
Example using the command line utility image_data:
.. code-block:: bash
image_data --of nifti niftiDir dicomDir
# Now do your processing on Nifti data in niftiDir/, leaving the result in niftiResult/.
# Convert the niftiResult back to DICOM, using dicomDir as a template
image_data --of dicom --template dicomDir dicomResult niftiResult
# The resulting dicomResult will be a new DICOM series that could be added to a PACS
# Set series number and series description before transmitting to PACS using DICOM transport
image_data --sernum 1004 --serdes 'Processed data' \
dicom://server:104/AETITLE dicomResult
The same example using python code:
.. code-block:: python
from imagedata import Series
a = Series('dicomDir')
a.write('niftiDir', formats=['nifti']) # Explicitly select nifti as output format
# Now do your processing on Nifti data in niftiDir/, leaving the result in niftiResult/.
b = Series('niftiResult', template=a) # Or template='dicomDir'
b.write('dicomResult') # Here, DICOM is default output format
# Set series number and series description before transmitting to PACS using DICOM transport
b.seriesNumber = 1004
b.seriesDescription = 'Processed data'
b.write(' dicom://server:104/AETITLE')
Series fields
-------------
The Series object is inherited from numpy.ndarray, adding a number of useful fields:
Axes
a.axes defines the unit and size of each dimension of the matrix
Addressing
4D: a[tags, slices, rows, columns]
3D: a[slices, rows, columns]
2D: a[rows, columns]
RGB: a[..., rgb]
patientID, patientName, patientBirthDate
Identifies patient
accessionNumber
Identifies study
seriesNumber, seriesDescription, imageType
Labels DICOM data
slices
Returns number of slices
spacing
Returns spacing for each dimension. Units depend on dimension, and could e.g. be mm or sec.
tags
Returns tags for each slice
timeline
Returns time steps for when a time series
transformationMatrix
The transformation matrix to calculate physical coordinates from pixel coordinates
Series instancing
-----------------
From image data file(s):
.. code-block:: python
a = Series('in_dir')
From a list of directories:
.. code-block:: python
a = Series(['1', '2', '3'])
From a numpy array:
.. code-block:: python
e = np.eye(128)
a = Series(e)
Series methods
--------------
write()
Write the image data as a Matlab file to out_dir:
.. code-block:: python
a.write('out_dir', formats=['mat'])
slicing
The image data array can be sliced like numpy.ndarray. The axes will be adjusted accordingly.
This will give a 3D **b** image when **a** is 4D.
.. code-block:: python
b = a[0, ...]
Archives
--------
The Series object can access image data in a number of **archives**. Some archives are:
Filesystem
Access files in directories on the local file system.
.. code-block:: python
a = Series('in_dir')
Zip
Access files inside zip files.
.. code-block:: python
# Read all files inside file.zip:
a = Series('file.zip')
# Read named directory inside file.zip:
b = Series('file.zip?dir_a')
# Write the image data to DICOM files inside newfile.zip:
b.write('newfile.zip', formats=['dicom'])
Transports
----------
file
Access local files (default):
.. code-block:: python
a = Series('file:in_dir')
dicom
Access files using DICOM Storage protocols. Currently, writing (implies sending) DICOM images only:
.. code-block:: python
a.write('dicom://server:104/AETITLE')
Command line usage
------------------
The command line program *image_data* can be used to convert between various image data formats:
.. code-block:: bash
image_data --order time out_dir in_dirs
.. |Docs Badge| image:: https://readthedocs.org/projects/imagedata/badge/
:alt: Documentation Status
:scale: 100%
:target: https://imagedata.readthedocs.io
.. |buildstatus| image:: https://github.com/erling6232/imagedata/actions/workflows/python-app.yml/badge.svg?branch=master
:target: https://github.com/erling6232/imagedata/actions/workflows/python-app.yml
:alt: Build Status
.. _buildstatus: https://github.com/erling6232/imagedata/actions/workflows/python-app.yml
.. |coverage| image:: https://codecov.io/gh/erling6232/imagedata/branch/master/graph/badge.svg?token=GT9KZV2TWT
:alt: Coverage
:target: https://codecov.io/gh/erling6232/imagedata
.. |pypi| image:: https://img.shields.io/pypi/v/imagedata.svg
:target: https://pypi.python.org/pypi/imagedata
:alt: PyPI Version
.. |joss| image:: https://joss.theoj.org/papers/6a1bc6ea5a200a7a9204cfafcd6e49b8/status.svg
:target: https://joss.theoj.org/papers/6a1bc6ea5a200a7a9204cfafcd6e49b8
:alt: JOSS Status
.. |zenodo| image:: https://zenodo.org/badge/123263810.svg
:target: https://zenodo.org/badge/latestdoi/123263810
:alt: Zenodo DOI
.. |pyversions| image:: https://img.shields.io/pypi/pyversions/imagedata.svg
:target: https://pypi.python.org/pypi/imagedata/
:alt: Supported Python Versions
.. |downloads| image:: https://img.shields.io/pypi/dm/imagedata?color=blue
:target: https://pypistats.org/packages/imagedata
:alt: PyPI Downloads
Raw data
{
"_id": null,
"home_page": "https://github.com/erling6232/imagedata",
"name": "imagedata",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.8",
"maintainer_email": null,
"keywords": "dicom, python, medical, imaging, pydicom, pynetdicom, itk",
"author": "Erling Andersen",
"author_email": "Erling.Andersen@Helse-Bergen.NO",
"download_url": "https://files.pythonhosted.org/packages/57/0b/3371229feff832952fee9fe0ddbad777bc92a383af481d212a74ce701044/imagedata-3.5.4.tar.gz",
"platform": null,
"description": "#########\nimagedata\n#########\n\n|coverage|\n|Docs Badge|\n\n|zenodo| |joss|\n\n|pypi| |pyversions| |downloads| |buildstatus|\n\n\nImagedata is a python library to read and write medical image data into numpy arrays.\nImagedata will handle multi-dimensional data.\nIn particular, imagedata will read and sort DICOM 3D and 4D series based on\ndefined tags.\nImagedata will handle geometry information between the formats.\n\nThe following formats are included:\n\n* DICOM\n* Nifti\n* ITK (MetaIO)\n* Matlab\n* PostScript (input only)\n\nOther formats can be added through a plugin architecture.\n\nInstall\n-------------------\n\n.. code-block::\n\n pip install imagedata\n\nDocumentation\n----------------\nSee the Documentation_ page for info.\n\n.. _Documentation: https://imagedata.readthedocs.io\n\nExample code\n-------------------\n\nA simple example reading two time series from dirA and dirB, and writing their mean to dirMean:\n\n.. code-block:: python\n\n from imagedata import Series\n a = Series('dirA', 'time')\n b = Series('dirB', 'time')\n assert a.shape == b.shape, \"Shape of a and b differ\"\n # Notice how a and b are treated as numpy arrays\n c = (a + b) / 2\n c.write('dirMean')\n\nSorting\n-------\n\nSorting of DICOM slices is considered a major task. Imagedata will sort slices into volumes based on slice location.\nVolumes may be sorted on a number of DICOM tags:\n\n* 'time': Dynamic time series, sorted on acquisition time\n* 'b': Diffusion weighted series, sorted on diffusion b value\n* 'fa': Flip angle series, sorted on flip angle\n* 'te': Sort on echo time TE\n\nIn addition, volumes can be sorted on user defined tags.\n\nNon-DICOM formats usually don't specify the labelling of the 4D data.\nIn this case, you can specify the sorting manually.\n\nViewing\n-------\n\nA simple viewer. Scroll through the image stack, step through the tags of a 4D dataset.\nThese operations are possible:\n\n* Read-out voxel value: Move mouse over.\n* Window/level adjustment: Move mouse with left key pressed.\n* Scroll through slices of an image stack: Mouse scroll wheel, or up/down array keys.\n* Step through tags (time, b-values, etc.): Left/right array keys.\n* Move through series when many series are displayed: PageUp/PageDown keys.\n\n.. code-block:: python\n\n # View a Series instance\n a.show()\n\n # View both a and b Series\n a.show(b)\n\n # View several Series\n a.show([b, c, d])\n\nConverting data from DICOM and back\n-----------------------------------\n\nIn many situations you need to process patient data using a tool that do not accept DICOM data.\nIn order to maintain the coupling to patient data, you may convert your data to e.g. Nifti and back.\n\nExample using the command line utility image_data:\n\n.. code-block:: bash\n\n image_data --of nifti niftiDir dicomDir\n # Now do your processing on Nifti data in niftiDir/, leaving the result in niftiResult/.\n\n # Convert the niftiResult back to DICOM, using dicomDir as a template\n image_data --of dicom --template dicomDir dicomResult niftiResult\n # The resulting dicomResult will be a new DICOM series that could be added to a PACS\n\n # Set series number and series description before transmitting to PACS using DICOM transport\n image_data --sernum 1004 --serdes 'Processed data' \\\n dicom://server:104/AETITLE dicomResult\n\nThe same example using python code:\n\n.. code-block:: python\n\n from imagedata import Series\n a = Series('dicomDir')\n a.write('niftiDir', formats=['nifti']) # Explicitly select nifti as output format\n\n # Now do your processing on Nifti data in niftiDir/, leaving the result in niftiResult/.\n\n b = Series('niftiResult', template=a) # Or template='dicomDir'\n b.write('dicomResult') # Here, DICOM is default output format\n\n # Set series number and series description before transmitting to PACS using DICOM transport\n b.seriesNumber = 1004\n b.seriesDescription = 'Processed data'\n b.write(' dicom://server:104/AETITLE')\n\nSeries fields\n-------------\n\nThe Series object is inherited from numpy.ndarray, adding a number of useful fields:\n\nAxes\n a.axes defines the unit and size of each dimension of the matrix\n \nAddressing\n 4D: a[tags, slices, rows, columns]\n \n 3D: a[slices, rows, columns]\n \n 2D: a[rows, columns]\n \n RGB: a[..., rgb]\n \npatientID, patientName, patientBirthDate\n Identifies patient\n\naccessionNumber\n Identifies study\n\nseriesNumber, seriesDescription, imageType\n Labels DICOM data\n\nslices\n Returns number of slices\n \nspacing\n Returns spacing for each dimension. Units depend on dimension, and could e.g. be mm or sec.\n \ntags\n Returns tags for each slice\n \ntimeline\n Returns time steps for when a time series\n \ntransformationMatrix\n The transformation matrix to calculate physical coordinates from pixel coordinates\n\nSeries instancing\n-----------------\n\nFrom image data file(s):\n\n.. code-block:: python\n\n a = Series('in_dir')\n \nFrom a list of directories:\n\n.. code-block:: python\n\n a = Series(['1', '2', '3'])\n\nFrom a numpy array:\n\n.. code-block:: python\n\n e = np.eye(128)\n a = Series(e)\n\nSeries methods\n--------------\n\nwrite()\n Write the image data as a Matlab file to out_dir:\n \n.. code-block:: python\n\n a.write('out_dir', formats=['mat'])\n\nslicing\n The image data array can be sliced like numpy.ndarray. The axes will be adjusted accordingly.\n This will give a 3D **b** image when **a** is 4D.\n\n.. code-block:: python\n\n b = a[0, ...]\n \nArchives\n--------\n\nThe Series object can access image data in a number of **archives**. Some archives are:\n\nFilesystem\n Access files in directories on the local file system.\n\n.. code-block:: python\n\n a = Series('in_dir')\n \nZip\n Access files inside zip files.\n \n\n.. code-block:: python\n\n # Read all files inside file.zip:\n a = Series('file.zip')\n\n # Read named directory inside file.zip:\n b = Series('file.zip?dir_a')\n \n # Write the image data to DICOM files inside newfile.zip:\n b.write('newfile.zip', formats=['dicom'])\n\nTransports\n----------\n\nfile\n Access local files (default):\n \n.. code-block:: python\n\n a = Series('file:in_dir')\n \ndicom\n Access files using DICOM Storage protocols. Currently, writing (implies sending) DICOM images only:\n \n.. code-block:: python\n\n a.write('dicom://server:104/AETITLE')\n\nCommand line usage\n------------------\n\nThe command line program *image_data* can be used to convert between various image data formats:\n\n.. code-block:: bash\n\n image_data --order time out_dir in_dirs\n\n.. |Docs Badge| image:: https://readthedocs.org/projects/imagedata/badge/\n :alt: Documentation Status\n :scale: 100%\n :target: https://imagedata.readthedocs.io\n\n.. |buildstatus| image:: https://github.com/erling6232/imagedata/actions/workflows/python-app.yml/badge.svg?branch=master\n :target: https://github.com/erling6232/imagedata/actions/workflows/python-app.yml\n :alt: Build Status\n\n.. _buildstatus: https://github.com/erling6232/imagedata/actions/workflows/python-app.yml\n\n.. |coverage| image:: https://codecov.io/gh/erling6232/imagedata/branch/master/graph/badge.svg?token=GT9KZV2TWT\n :alt: Coverage\n :target: https://codecov.io/gh/erling6232/imagedata\n\n.. |pypi| image:: https://img.shields.io/pypi/v/imagedata.svg\n :target: https://pypi.python.org/pypi/imagedata\n :alt: PyPI Version\n\n.. |joss| image:: https://joss.theoj.org/papers/6a1bc6ea5a200a7a9204cfafcd6e49b8/status.svg\n :target: https://joss.theoj.org/papers/6a1bc6ea5a200a7a9204cfafcd6e49b8\n :alt: JOSS Status\n\n.. |zenodo| image:: https://zenodo.org/badge/123263810.svg\n :target: https://zenodo.org/badge/latestdoi/123263810\n :alt: Zenodo DOI\n\n.. |pyversions| image:: https://img.shields.io/pypi/pyversions/imagedata.svg\n :target: https://pypi.python.org/pypi/imagedata/\n :alt: Supported Python Versions\n\n.. |downloads| image:: https://img.shields.io/pypi/dm/imagedata?color=blue\n :target: https://pypistats.org/packages/imagedata\n :alt: PyPI Downloads\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Read/write medical image data",
"version": "3.5.4",
"project_urls": {
"Documentation": "https://imagedata.readthedocs.io",
"Homepage": "https://github.com/erling6232/imagedata",
"Source Code": "https://github.com/erling6232/imagedata"
},
"split_keywords": [
"dicom",
" python",
" medical",
" imaging",
" pydicom",
" pynetdicom",
" itk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e033edba7986d74776627a126694025ebeea77938b652ae5b372b7129446be56",
"md5": "cab117673a3ab38c39be57f503c4ec22",
"sha256": "e55ae31a484df349162c962fa37da5edf3bbc75407b455b729254ff063ae4f73"
},
"downloads": -1,
"filename": "imagedata-3.5.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cab117673a3ab38c39be57f503c4ec22",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.8",
"size": 142901,
"upload_time": "2024-04-25T11:28:18",
"upload_time_iso_8601": "2024-04-25T11:28:18.602556Z",
"url": "https://files.pythonhosted.org/packages/e0/33/edba7986d74776627a126694025ebeea77938b652ae5b372b7129446be56/imagedata-3.5.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "570b3371229feff832952fee9fe0ddbad777bc92a383af481d212a74ce701044",
"md5": "750ec574bc1a1eed07c3ca33368c12a1",
"sha256": "df7b91301505ef81adf5638922c4f366a1f98c96e9ca88d042fafc297e1400bd"
},
"downloads": -1,
"filename": "imagedata-3.5.4.tar.gz",
"has_sig": false,
"md5_digest": "750ec574bc1a1eed07c3ca33368c12a1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.8",
"size": 27631445,
"upload_time": "2024-04-25T11:28:20",
"upload_time_iso_8601": "2024-04-25T11:28:20.974725Z",
"url": "https://files.pythonhosted.org/packages/57/0b/3371229feff832952fee9fe0ddbad777bc92a383af481d212a74ce701044/imagedata-3.5.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-25 11:28:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "erling6232",
"github_project": "imagedata",
"travis_ci": true,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "imagedata"
}
JSON
