| Name | itk-dreg JSON |
| Version |
0.0.1
JSON |
| download |
| home_page | |
| Summary | ITK-DREG Distributed registration framework. |
| upload_time | 2023-11-15 19:09:43 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.9 |
| license | |
| keywords |
itk
insighttoolkit
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# itk-dreg
A framework for distributed, large-scale image registration.
## Overview
The ITK Distributed Registration module (`itk-dreg`) provides a framework based on the
Insight Toolkit (ITK) and the `dask.distributed` library for the purpose of registering
large-scale images out of memory.
Traditional image registration techniques in ITK and other libraries (Elastix, ANTs) require
in-memory processing, meaning those techniques load images fully in memory (RAM) during
registration execution. Meanwhile, large image datasets can occupy terabytes of data for a single
image on the cloud and far exceed available memory. `itk-dreg` addresses this issue as a
map-reduce problem where images are successivly subdivided into subimages, registered,
and then composed into a descriptive output. Multiple `itk-dreg` registration graphs may be
executed in succession to yield a pipeline for multiresolution image registration.
`itk-dreg` provides three major components:
- Concepts to describe the map-reduce registration problem;
- A user-ready registration method to produce `itk.DisplacementFieldTransform`s from out-of-memory
registration with Dask scheduling and ITKElastix registration;
- A developer framework to extend `itk-dreg` with novel registration and reduction methods.
## Getting Started
To use `itk-dreg`, clone the Git repository and install with `flit`.
```py
> python -m pip install flit
> git clone https://www.github.com/InsightSoftwareConsortium/itk-dreg.git
> cd itk-dreg/src
itk-dreg/src > python -m flit install
```
Several Jupyter Notebook examples are available for getting started. To run locally:
```py
itk-dreg/src > python -m flit install --extras
itk-dreg/src > cd ../examples
itk-dreg/examples > jupyter notebook
```
## Use Instructions
`itk_dreg` provides a framework to register a moving image onto a fixed image.
The output of a single run is an `itk.Transform` object that can be used
to resample the moving image onto the fixed image. Multiple runs can be chained
to successively refine registration over multiple image resolutions and over
various registration and reduction methods.
Use `itk_dreg.register.register_images` to assemble and run a task graph for distributed registration.
```py
my_initial_transform = ...
# registration method returns an update to the initial transform
my_registration_schedule = itk_dreg.register_images(
fixed_chunk_size=(x,y,z),
initial_transform=my_initial_transform,
fixed_reader_ctor=my_construct_streaming_reader_method,
moving_reader_ctor=my_construct_streaming_reader_method,
block_registration_method=my_block_pair_registration_method_subclass,
reduce_method=my_postprocess_registration_method_subclass,
overlap_factors=[0.1,0.1,0.1]
)
my_result = my_registration_schedule.registration_result.compute()
final_transform = itk.CompositeTransform()
final_transform.append_transform(my_initial_transform)
final_transform.append_transform(my_result.transforms.transform)
# we can use the result transform to resample the moving image to fixed image space
interpolator = itk.LinearInterpolateImageFunction.New(my_moving_image)
my_warped_image = itk.resample_image_filter(
my_moving_image,
transform=final_transform,
interpolator=interpolator,
use_reference_image=True,
reference_image=my_fixed_image
)
```
## Components
### Core Components
`itk_dreg` provides the following core components:
- `itk_dreg.register` defines scheduling infrastructure and the main entry point into the
`itk_dreg` registration framework.
- `itk_dreg.base` defines common types and virtual interfaces for the `itk_dreg` registration framework.
Virtual interfaces in `itk_dreg.base.registration_interface` serve as an entry point for
contributors to write their own registration and reduction methods.
- `itk_dreg.block` defines common methods to map between voxel and spatial subdomains.
These components must be installed to use the `itk_dreg` registration framework.
### Extended Components
`itk_dreg` includes a few common implementations to get started with image registration.
These components act as extensions and are not necessarily required for running `itk_dreg`.
- `itk_dreg.itk` provides ITK-based methods to aid in image streaming and dask chunk scheduling.
- `itk_dreg.elastix` adapts the ITKElastix registration routines for distributed
registration in `itk_dreg`.
- `itk_dreg.reduce_dfield` implements a transform-reduction method to estimate a single
`itk.DeformationFieldTransform` from block registration results in `itk_dreg`.
- `itk_dreg.mock` provides mock implementations of common framework components for use in
testing and debugging.
Alternate registration and transform reduction modules may be available in the future
either as part of `itk_dreg` or via community distributions.
## Contributing
Refer to [Contributing documentation](CONTRIBUTING.md) for getting started with `itk-dreg` development.
Please direct feature requests or bug reports to the `itk-dreg` [GitHub Issues](https://github.com/InsightSoftwareConsortium/itk-dreg/issues)
board.
## License
`itk-dreg` is distributed under the [Apache-2.0](LICENSE) permissive license.
## Questions and Queries
`itk-dreg` is part of the Insight Toolkit tools ecosystem for medical image processing. We encourage developers to
reach out to the ITK community with questions on the [ITK Discourse forums](https://discourse.itk.org/). Those
interested in custom or commercial development should reach out to [Kitware](https://www.kitware.com/contact/) to learn more.
## Acknowledgements
`itk-dreg` was developed in part by with support from:
- [NIH NIMH BRAIN Initiative](https://braininitiative.nih.gov/) under award 1RF1MH126732.
Raw data
{
"_id": null,
"home_page": "",
"name": "itk-dreg",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "ITK,InsightToolkit",
"author": "",
"author_email": "InsightSoftwareConsortium <matt.mccormick@kitware.com>",
"download_url": "",
"platform": null,
"description": "# itk-dreg\n\nA framework for distributed, large-scale image registration.\n\n## Overview\n\nThe ITK Distributed Registration module (`itk-dreg`) provides a framework based on the\nInsight Toolkit (ITK) and the `dask.distributed` library for the purpose of registering\nlarge-scale images out of memory.\n\nTraditional image registration techniques in ITK and other libraries (Elastix, ANTs) require\nin-memory processing, meaning those techniques load images fully in memory (RAM) during\nregistration execution. Meanwhile, large image datasets can occupy terabytes of data for a single\nimage on the cloud and far exceed available memory. `itk-dreg` addresses this issue as a\nmap-reduce problem where images are successivly subdivided into subimages, registered,\nand then composed into a descriptive output. Multiple `itk-dreg` registration graphs may be\nexecuted in succession to yield a pipeline for multiresolution image registration.\n\n`itk-dreg` provides three major components:\n- Concepts to describe the map-reduce registration problem;\n- A user-ready registration method to produce `itk.DisplacementFieldTransform`s from out-of-memory\n registration with Dask scheduling and ITKElastix registration;\n- A developer framework to extend `itk-dreg` with novel registration and reduction methods.\n\n## Getting Started\n\nTo use `itk-dreg`, clone the Git repository and install with `flit`.\n\n```py\n> python -m pip install flit\n> git clone https://www.github.com/InsightSoftwareConsortium/itk-dreg.git\n> cd itk-dreg/src\nitk-dreg/src > python -m flit install\n```\n\nSeveral Jupyter Notebook examples are available for getting started. To run locally:\n\n```py\nitk-dreg/src > python -m flit install --extras\nitk-dreg/src > cd ../examples\nitk-dreg/examples > jupyter notebook\n```\n\n## Use Instructions\n\n`itk_dreg` provides a framework to register a moving image onto a fixed image.\nThe output of a single run is an `itk.Transform` object that can be used\nto resample the moving image onto the fixed image. Multiple runs can be chained\nto successively refine registration over multiple image resolutions and over\nvarious registration and reduction methods.\n\nUse `itk_dreg.register.register_images` to assemble and run a task graph for distributed registration.\n\n\n```py\nmy_initial_transform = ...\n\n# registration method returns an update to the initial transform\n\nmy_registration_schedule = itk_dreg.register_images(\n fixed_chunk_size=(x,y,z),\n initial_transform=my_initial_transform,\n fixed_reader_ctor=my_construct_streaming_reader_method,\n moving_reader_ctor=my_construct_streaming_reader_method,\n block_registration_method=my_block_pair_registration_method_subclass,\n reduce_method=my_postprocess_registration_method_subclass,\n overlap_factors=[0.1,0.1,0.1]\n)\nmy_result = my_registration_schedule.registration_result.compute()\n\nfinal_transform = itk.CompositeTransform()\nfinal_transform.append_transform(my_initial_transform)\nfinal_transform.append_transform(my_result.transforms.transform)\n\n# we can use the result transform to resample the moving image to fixed image space\n\ninterpolator = itk.LinearInterpolateImageFunction.New(my_moving_image)\n\nmy_warped_image = itk.resample_image_filter(\n my_moving_image,\n transform=final_transform,\n interpolator=interpolator,\n use_reference_image=True,\n reference_image=my_fixed_image\n)\n\n```\n\n## Components\n\n### Core Components\n\n`itk_dreg` provides the following core components:\n\n- `itk_dreg.register` defines scheduling infrastructure and the main entry point into the\n `itk_dreg` registration framework.\n- `itk_dreg.base` defines common types and virtual interfaces for the `itk_dreg` registration framework.\n Virtual interfaces in `itk_dreg.base.registration_interface` serve as an entry point for\n contributors to write their own registration and reduction methods.\n- `itk_dreg.block` defines common methods to map between voxel and spatial subdomains.\n\nThese components must be installed to use the `itk_dreg` registration framework.\n\n### Extended Components\n\n`itk_dreg` includes a few common implementations to get started with image registration.\nThese components act as extensions and are not necessarily required for running `itk_dreg`.\n\n- `itk_dreg.itk` provides ITK-based methods to aid in image streaming and dask chunk scheduling.\n- `itk_dreg.elastix` adapts the ITKElastix registration routines for distributed\n registration in `itk_dreg`.\n- `itk_dreg.reduce_dfield` implements a transform-reduction method to estimate a single\n `itk.DeformationFieldTransform` from block registration results in `itk_dreg`.\n- `itk_dreg.mock` provides mock implementations of common framework components for use in\n testing and debugging.\n\nAlternate registration and transform reduction modules may be available in the future\neither as part of `itk_dreg` or via community distributions.\n\n## Contributing\n\nRefer to [Contributing documentation](CONTRIBUTING.md) for getting started with `itk-dreg` development.\nPlease direct feature requests or bug reports to the `itk-dreg` [GitHub Issues](https://github.com/InsightSoftwareConsortium/itk-dreg/issues)\nboard.\n\n## License\n\n`itk-dreg` is distributed under the [Apache-2.0](LICENSE) permissive license.\n\n## Questions and Queries\n\n`itk-dreg` is part of the Insight Toolkit tools ecosystem for medical image processing. We encourage developers to\nreach out to the ITK community with questions on the [ITK Discourse forums](https://discourse.itk.org/). Those\ninterested in custom or commercial development should reach out to [Kitware](https://www.kitware.com/contact/) to learn more.\n\n## Acknowledgements\n\n`itk-dreg` was developed in part by with support from:\n\n- [NIH NIMH BRAIN Initiative](https://braininitiative.nih.gov/) under award 1RF1MH126732.\n\n",
"bugtrack_url": null,
"license": "",
"summary": "ITK-DREG Distributed registration framework.",
"version": "0.0.1",
"project_urls": {
"Home": "https://github.com/InsightSoftwareConsortium/itk-dreg"
},
"split_keywords": [
"itk",
"insighttoolkit"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c2f38ad0063500539ba42e823442ed58f4bfabe89e62deb7bfc0c184557c9f64",
"md5": "1695c4f0e0eba4f110a9dc3506a395ef",
"sha256": "7437139ce9a7a82f3548436612df66a6ef89d8f9680b54cc9ba97c4bd3a89d9b"
},
"downloads": -1,
"filename": "itk_dreg-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1695c4f0e0eba4f110a9dc3506a395ef",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 41979,
"upload_time": "2023-11-15T19:09:43",
"upload_time_iso_8601": "2023-11-15T19:09:43.329006Z",
"url": "https://files.pythonhosted.org/packages/c2/f3/8ad0063500539ba42e823442ed58f4bfabe89e62deb7bfc0c184557c9f64/itk_dreg-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-15 19:09:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "InsightSoftwareConsortium",
"github_project": "itk-dreg",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "itk-dreg"
}
