Skip to content

Commit 11631a1

Browse files
thewtexthewtex
authored
Merge pull request #162 from thewtex/filter-syntax
2 parents 600371c + 52304c8 commit 11631a1

File tree

1 file changed

+159
-33
lines changed

1 file changed

+159
-33
lines changed

‎docs/Quick_start_guide.rst‎

Lines changed: 159 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -15,33 +15,58 @@ To install the ITK Python package::
1515
Usage
1616
-----
1717

18-
Basic examples
18+
Basic example
1919
..............
2020

2121
Here is a simple python script that reads an image, applies a median image filter (radius of 2 pixels), and writes the resulting image in a file.
2222

2323
.. literalinclude:: code/ReadMedianWrite.py
2424

25-
In `itk`, filters are optimized at compile time for each image pixel type and
26-
image dimension. There are two ways to instantiate these filters with the `itk`
27-
Python wrapping:
25+
ITK and NumPy
26+
.............
2827

29-
- *Implicit (recommended)*: Type information is automatically detected from the data. Typed filter objects and images are implicitly created.
28+
A common use case for using ITK in Python is to mingle NumPy and ITK operations on raster data. ITK provides a large number of I/O image formats and several sophisticated image processing algorithms not available in any other packages. The ability to intersperse that with the SciPy ecosystem provides a great tool for rapid prototyping.
3029

31-
.. literalinclude:: code/ImplicitInstantiation.py
32-
:lines: 8-
30+
The following script shows how to integrate NumPy and ITK:
3331

34-
- *Explicit*: This can be useful if an appropriate type cannot be determined implicitly, e.g. with the `CastImageFilter`, and when a different filter type than the default is desired.
32+
.. literalinclude:: code/MixingITKAndNumPy.py
33+
:lines: 8-33
3534

36-
Explicit instantiation of a median image filter:
3735

38-
.. literalinclude:: code/ExplicitInstantiation.py
39-
:lines: 8-
36+
Similar functions are available to work with `itk.Matrix`, VNL vectors and matrices:
4037

41-
Explicit instantiation of cast image filter:
38+
.. literalinclude:: code/MixingITKAndNumPy.py
39+
:lines: 35-
4240

43-
.. literalinclude:: code/Cast.py
44-
:lines: 10-18
41+
ITK and Xarray
42+
..............
43+
44+
An `itk.Image` can be converted to and from an `xarray.DataArray
45+
<https://xarray.pydata.org/en/stable/generated/xarray.DataArray.html>`_ while
46+
preserving metadata::
47+
48+
da = itk.xarray_from_image(image)
49+
50+
image = itk.image_from_xarray(da)
51+
52+
ITK and VTK
53+
............
54+
55+
An `itk.Image` can be converted to and from a `vtk.vtkImageData
56+
<https://vtk.org/doc/nightly/html/classvtkImageData.html>`_ while
57+
preserving metadata::
58+
59+
vtk_image = itk.vtk_image_from_image(image)
60+
61+
image = itk.image_from_vtk_image(vtk_image)
62+
63+
ITK and napari
64+
..............
65+
66+
An `itk.Image` can be converted to and from a `napari.layers.Image
67+
<https://napari.org/api/stable/napari.layers.Image.html#napari.layers.Image>`_ while
68+
preserving metadata with the `itk-napari-conversion package
69+
<https://github.com/InsightSoftwareConsortium/itk-napari-conversion>`_.
4570

4671
ITK Python types
4772
................
@@ -65,46 +90,147 @@ Types can also be obtained from their name in the C programming language:
6590
.. literalinclude:: code/CompareITKTypes.py
6691
:lines: 5
6792

68-
Instantiate an ITK object
69-
.........................
93+
To cast the pixel type of an image, use `.astype`:
7094

71-
There are two types of ITK objects. Most ITK objects (images, filters, adapters, ...) are instantiated the following way:
95+
.. literalinclude:: code/Cast.py
96+
:lines: 10-18
7297

73-
.. literalinclude:: code/InstantiateITKObjects.py
74-
:lines: 6-8
98+
Metadata dictionary
99+
...................
75100

76-
Some objects (matrix, vector, RGBPixel, ...) do not require the attribute `.New()` to be added to instantiate them:
101+
An `itk.Image` has a metadata dict of `key: value` pairs.
77102

78-
.. literalinclude:: code/InstantiateITKObjects.py
79-
:lines: 11
80103

81-
In case of doubt, look at the attributes of the object you are trying to instantiate.
104+
The metadata dictionary can be retrieved with::
105+
106+
meta_dict = dict(image)
107+
108+
For example::
109+
110+
In [3]: dict(image)
111+
Out[3]:
112+
{'0008|0005': 'ISO IR 100',
113+
'0008|0008': 'ORIGINAL\\PRIMARY\\AXIAL',
114+
'0008|0016': '1.2.840.10008.5.1.4.1.1.2',
115+
'0008|0018': '1.3.12.2.1107.5.8.99.484849.834848.79844848.2001082217554549',
116+
'0008|0020': '20010822',
117+
118+
Individual dictionary items can be accessed or assigned::
119+
120+
print(image['0008|0008'])
121+
122+
image['origin'] = [4.0, 2.0, 2.0]
123+
124+
In the Python dictionary interface to image metadata, keys for the spatial
125+
metadata, the *'origin'*, *'spacing'*, and *'direction'*, are reversed in
126+
order from `image.GetOrigin()`, `image.GetSpacing()`, `image.GetDirection()`
127+
to be consistent with the `NumPy array index order
128+
<https://scikit-image.org/docs/dev/user_guide/numpy_images.html#notes-on-the-order-of-array-dimensions>`_
129+
resulting from pixel buffer array views on the image.
130+
131+
Access pixel data with NumPy indexing
132+
.....................................
133+
134+
Array views of an `itk.Image` provide a way to set and get pixel values with NumPy indexing syntax, e.g.::
82135

83-
Filter Parameters
136+
In [6]: image[0,:2,4] = [5,5]
137+
138+
In [7]: image[0,:4,4:6]
139+
Out[7]:
140+
NDArrayITKBase([[ 5, -997],
141+
[ 5, -1003],
142+
[ -993, -999],
143+
[ -996, -994]], dtype=int16)
144+
145+
Input/Output (IO)
146+
.................
147+
148+
Convenient functions are provided read and write from ITK's many supported
149+
file formats::
150+
151+
image = itk.imread('image.tif')
152+
153+
# Read in with a specific pixel type.
154+
image = itk.imread('image.tif', itk.F)
155+
156+
# Read in an image series.
157+
# Pass a sorted list of files.
158+
image = itk.imread(['image1.png', 'image2.png', 'image3.png'])
159+
160+
# Read in a volume from a DICOM series.
161+
# Pass a directory.
162+
# Only a single series, sorted spatially, will be returned.
163+
image = itk.imread('/a/dicom/directory/')
164+
165+
# Write an image.
166+
itk.imwrite(image, 'image.tif')
167+
168+
169+
# Read a mesh.
170+
mesh = itk.meshread('mesh.vtk')
171+
172+
# Write a mesh.
173+
itk.meshwrite(mesh, 'mesh.vtk')
174+
175+
176+
# Read a spatial transform.
177+
transform = itk.transformread('transform.h5')
178+
179+
# Write a spatial transform.
180+
itk.transformwrite(transform, 'transform.h5')
181+
182+
Image filters and Image-like inputs and outputs
183+
...............................................
184+
185+
All `itk` functional image filters operate on an `itk.Image` but also:
186+
187+
- `xarray.DataArray <https://xarray.pydata.org/en/stable/generated/xarray.DataArray.html>`_ *
188+
- `numpy.ndarray <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html>`_
189+
- `dask.array.Array <https://docs.dask.org/en/latest/array.html>`_
190+
191+
* Preserves image metadata
192+
193+
Filter parameters
84194
.................
85195

86196
ITK filter parameters can be specified in the following ways:
87197

88198
.. literalinclude:: code/FilterParameters.py
89199
:lines: 10-
90200

201+
Filter types
202+
............
203+
204+
In `itk`, filters are optimized at compile time for each image pixel type and
205+
image dimension. There are two ways to instantiate these filters with the `itk`
206+
Python wrapping:
207+
208+
- *Implicit (recommended)*: Type information is automatically detected from the data. Typed filter objects and images are implicitly created.
91209

92-
Mixing ITK and NumPy
93-
--------------------
210+
.. literalinclude:: code/ImplicitInstantiation.py
211+
:lines: 8-
94212

95-
A common use case for using ITK in Python is to mingle NumPy and ITK operations on raster data. ITK provides a large number of I/O image formats and several sophisticated image processing algorithms not available in any other packages. The ability to intersperse that with the SciPy ecosystem provides a great tool for rapid prototyping.
213+
- *Explicit*: This can be useful if an appropriate type cannot be determined implicitly or when a different filter type than the default is desired.
96214

97-
The following script shows how to integrate NumPy and ITK:
215+
To specify the type of the filter, use the `ttype` keyword argument. Explicit instantiation of a median image filter:
98216

99-
.. literalinclude:: code/MixingITKAndNumPy.py
100-
:lines: 8-33
217+
.. literalinclude:: code/ExplicitInstantiation.py
218+
:lines: 8-
101219

220+
Instantiate an ITK object
221+
.........................
102222

103-
Similar functions are available to work with `itk.Matrix`, VNL vectors and matrices:
223+
There are two types of ITK objects. Most ITK objects, such as images, filters, or adapters, are instantiated the following way:
104224

105-
.. literalinclude:: code/MixingITKAndNumPy.py
106-
:lines: 35-
225+
.. literalinclude:: code/InstantiateITKObjects.py
226+
:lines: 6-8
107227

228+
Some objects, like a Matrix, Vector, or RGBPixel, do not require the attribute `.New()` to be added to instantiate them:
229+
230+
.. literalinclude:: code/InstantiateITKObjects.py
231+
:lines: 11
232+
233+
In case of doubt, look at the attributes of the object you are trying to instantiate.
108234

109235
Examples
110236
--------

0 commit comments

Comments
 (0)