2?j | d Z ddlmZmZmZmZmZmZmZm Z m
Z
ddl Z ddl
Zn# e$ rZ ed edZ[ww xY wddlmZmZmZmZ ddlmZmZ ddlmZ d ed
efd Zd ej d
ee d
ee ef fdZ dee ef d
ej fdZ d ej de d ed
dfdZ G d d Z G d de Z!dS )u Read/Write single-file DICOM instances using pydicom.
.. note::
To use this plugin you need to have `pydicom `_
installed::
pip install pydicom
Backend Library: `pydicom `_
This plugin reads and writes DICOM files using pydicom. It operates in
individual files, meaning while it supports multi-frame files natively, it does
**not** assemble data across files in a directory.
Methods
-------
.. note::
Check the respective function for supported kwargs and detailed
documentation.
.. autosummary::
:toctree:
PydicomPlugin.read
PydicomPlugin.iter
PydicomPlugin.write
PydicomPlugin.properties
PydicomPlugin.metadata
Additional methods available inside the :func:`imopen `
context:
.. autosummary::
:toctree:
PydicomPlugin.write_frame
PydicomPlugin.lut_dense
PydicomPlugin.lut_linear
PydicomPlugin.instance_metadata
PydicomPlugin.shared_frame_metadata
PydicomPlugin.compression
Advanced API
------------
In addition to the default ImageIO v3 API this plugin exposes custom functions
and attributes for writing DICOM. These are available inside the
:func:`imopen ` context and allow fine-grained control over
tags, functional groups, palettes, and compression. The callables are documented
above; below is a usage example::
import imageio.v3 as iio
frames = [...] # list of (rows, cols) arrays, e.g. uint16
with iio.imopen("out.dcm", "w", plugin="pydicom") as f:
# global metadata
f.instance_metadata["PatientName"] = "Anonymous"
f.instance_metadata["Modality"] = "OT"
# bit depth
f.instance_metadata["BitsStored"] = 12
# pixel compression
f.compression = "rle" # or "jpeg-ls", "jpeg2000-lossless", ...
# shared FG (written once, applied to each frame)
f.shared_frame_metadata["PixelMeasuresSequence"] = [
{"PixelSpacing": [1.0, 1.0]}
]
# write each frame
for i, frame in enumerate(frames):
f.write_frame(
frame,
# set frame-level metadata
metadata={"FrameContentSequence": [{"FrameAcquisitionNumber": i}]},
)
meta = iio.immeta("out.dcm", plugin="pydicom")
assert meta["PatientName"] == "Anonymous"
Frames are buffered until flush (``close()`` / context exit).
Compression
-----------
Compression is imopen-only. ``imwrite`` / ``write()`` always produce an
uncompressed Dataset; set ``f.compression`` before close to run pydicom
``Dataset.compress()`` once at flush. Changing the value after some
``write_frame`` calls is fine — only the value at flush matters.
Accepted values are short names (resolved to transfer syntax UIDs) or a raw
UID string:
- ``"rle"`` — RLE Lossless
- ``"jpeg-ls"`` — JPEG-LS Lossless
- ``"jpeg-ls-near"`` — JPEG-LS Near-Lossless
- ``"jpeg2000"`` — JPEG 2000
- ``"jpeg2000-lossless"`` — JPEG 2000 Lossless
Availability depends on pydicom’s installed encoders (RLE is built-in; others
may need extra packages). Unknown names raise immediately; unsupported UIDs
fail at flush.
Example::
import imageio.v3 as iio
import numpy as np
img = np.arange(64, dtype=np.uint8).reshape(8, 8)
with iio.imopen("compressed.dcm", "w", plugin="pydicom") as f:
f.compression = "rle"
f.write(img)
Palette LUTs
------------
The plugin offers helpers to build color palettes when writing palettized
DICOM images. Supported palettes are either **dense** or **linear**:
- A **dense** palette maps each pixel index to a color from a lookup table.
- A **linear** palette maps each pixel index via piecewise-linear
interpolation between the provided ``colors`` at the provided ``indices``.
Dense color maps use the ordinary LookupTableData tags, linear maps use
SegmentedLookupTableData tags. Please ensure your reader supports these. Optional
alpha is supported as a 4th LUT channel. Pixel frames must be **index** arrays
into the LUT (not already-colored RGB).
When using a LUT, do **not** set ``BitsStored`` in ``instance_metadata``.
Example using a dense palette::
import imageio.v3 as iio
import numpy as np
frame = ... # (rows, cols) index array, with values 0..3
colormap = np.array(
[[0, 0, 0], [255, 0, 0], [0, 255, 0], [0, 0, 255]],
dtype=np.uint8,
)
with iio.imopen("palette_dense.dcm", "w", plugin="pydicom") as f:
f.lut_dense(colormap)
f.write(frame)
Example using a linear palette::
import imageio.v3 as iio
frame = ... # (rows, cols) index array, uint8
with iio.imopen("palette_linear.dcm", "w", plugin="pydicom") as f:
f.lut_linear(
colors=[(0, 0, 0), (65535, 65535, 65535)],
indices=[0, 255],
)
f.write(frame)
Calling either helper **replaces** any previous palette state and clears the
other encoding's data tags (explicit and segmented are mutually exclusive).
While we offer helpers for dense and linear, you can still manually build and assign
other tables directly to the respective metadata tags.
Pixel reconstruction
--------------------
By default ``read`` / ``iter`` / ``imread`` / ``imiter`` reconstruct the image.
This means any LUT (lookup table), grayscale correction, or ROI (region of
interest) windowing is applied before the image is returned.
Pass ``raw=True`` to skip that pipeline and get stored values
(``pixel_array(..., raw=True)``). ``improps`` / ``properties`` take the same
``raw`` flag so reported shape and dtype match ``read``.
Notes
-----
Be aware that ``.write()`` on ``""`` needs to flush immediately so
``imwrite`` can return encoded bytes. This may cause surprising behavior when used
inside an explicit ``imopen`` context.
) AnyCallableDictIteratorListOptionalSequenceTupleUnionNzSThe pydicom plugin requires pydicom. Install it via `pip install imageio[pydicom]`. ) URI_BYTESInitializationErrorIOModeRequest)ImagePropertiesPluginV3) ArrayLikevaluereturnc x t | t j rt | d S t | t j j r d | D S t | t r| S t | t t f r d | D S t | d r|
S | S )N omit_keysc , g | ]}t | S r
_as_python).0items HC:\Projects\Historical\venv\Lib\site-packages\imageio/plugins/pydicom.py
z _as_python.. s 333T
4 333 c , g | ]}t | S r r r vs r r z _as_python.. s ---!
1
---r! tolist)
isinstancepdcmDataset_dataset_to_dictsequencer byteslisttuplehasattrr% )r s r r r s % && 5 4444% /00 433U3333% %$ '' .--u----uh ||~~ Lr! dsr c i }t | }| D ];}|j |j dk r|j |v r t |j ||j < <|S )N PixelData)setkeywordr r )r/ r outomitelems r r) r) sf C y>>D 3 3 < 4<;#>#> <4 &tz 2 2DL Jr! datac t j }| D ]\ }}t ||| |S N)r' r( items_set_dataset_value)r7 r/ keyr s r _dict_to_datasetr= sB
Bjjll + +
U2sE****
Ir! r< c f t |t r t | |t | d S t |t rU|rSt d |D r:t | |t j d |D d S t | || d S )Nc 3 @ K | ]}t |t V d S r9 )r& dictr# s r z%_set_dataset_value.. s, 2V2V1:a3F3F2V2V2V2V2V2Vr! c , g | ]}t | S r r= r# s r r z&_set_dataset_value.. s! 0T0T0T1A!1D1D0T0T0Tr! ) r& r@ setattrr= r, allr' r* r )r/ r< r s r r; r; s % C)%0011111 E4 U s2V2VPU2V2V2V/V/V C //0T0Te0T0T0TUUVVVVVC r! c e Zd ZdZdeg ej f ddfdZdede fdZ
dede ddfd Z de de
fd
Zdded e de fd Zd
eee f ddfdZdS )_TagMapuB Dict-like keyword → value view that writes through to a Dataset.get_dsr Nc || _ d S r9 )_get_ds)selfrH s r __init__z_TagMap.__init__ s
r! r< c ` t t | | S r9 )r getattrrJ rK r< s r __getitem__z_TagMap.__getitem__ s" '$,,..#66777r! r c L t | || d S r9 )r; rJ )rK r< r s r __setitem__z_TagMap.__setitem__ s" 4<<>>366666r! c p t |t o!t | | S r9 )r& strr. rJ rO s r __contains__z_TagMap.__contains__ s) #s##D (D(DDr! defaultc || v r| | n|S r9 r )rK r< rV s r getz _TagMap.get s 4KKtCyyW4r! otherc D | D ]
\ }}|| |< d S r9 )r: )rK rY r< r s r updatez_TagMap.update s2 ++-- JC DII r! r9 )__name__
__module__ __qualname____doc__r r' r( rL rT r rP rR objectboolrU rX r r[ r r! r rG rG s LL xDL(8 9 d 8s 8s 8 8 8 87s 73 74 7 7 7 7E E4 E E E E5 5s 5S 5C 5 5 5 5 DcN t r! rG c
e Zd ZdZdeddf fd Zd-dZdej de dej fd Z
dd
d d e e de dej fd
Z
d
dde deej fdZdd
d d e e de defdZedd
dd ede de deeef fdZdd
ddeeee f de eeef de de e fdZe de fd Z e j deeef ddfd Z e de fd Z e j deeef ddfd Z e de e fd Z!e!j de eeef ddfd Z!dd!d"ede eeef ddfd#Z"d.d%ed&e ddfd'Z# d.d(ed)ed&e ddfd*Z$d-d+Z%d-d,Z& xZ'S )/
PydicomPluginzRead and write DICOM images via pydicom.
Parameters
----------
request : iio.Request
Image resource request.
kwargs : Any
Additional kwargs are forwarded to ``pydicom.dcmread``.
requestr Nc 0 t | || _ | j dd d | _ i | _ g | _ g | _ d| _ |j j
t j k r] t j | fi | j | _ d S # t j j $ r}t' d |d }~ww xY wt j | _ t j j | j _ t j | j _ t j | j _ t j | j _ d| j _ d S )Nstop_before_pixelsTFz'pydicom cannot read this file as DICOM.OT) superrL _dcmread_kwargs
setdefault _compression _save_kwargs_frames_frame_metadata_flushedmodeio_moder readr' dcmreadget_file_dataseterrorsInvalidDicomErrorr r( uid SecondaryCaptureImageStorage SOPClassUID generate_uidSOPInstanceUIDStudyInstanceUIDSeriesInstanceUIDModality)rK rd kwargsexc __class__s r rL zPydicomPlugin.__init__ s\
!!! 06 ''(BBCCH$H$ )G8a< : DM#E F F :t}&QRR : HH : @OSSHH4=899H !&.d%;EE4LE a<<XK'E T] 899 t}&;<<
C
1 2 2a 7 7
( t}>/QQt}I!LMMDHRXX BBEE % 0@$GGSt}3A6DQGHHDHRXX BBEE"
~66"
}55"
HRZ((EE
/DdKKWt}8;I!LMMDHRXX BBEE
~66
'9::
HRZ((EE
>R#7#7HRZ((EE
>R#7#7HRZ((EE
"~':':HRX&&EE
"~':':H ?RWWrx@@EE
"~';';H ARXX BBEE
"~';';H ARXX BBEE J!J J4=*?FFJ J J
~tDD
$=+,,F=+,,F!( 8NPT!U!U ! - 344H DM+KTRR "9Q<1H$OOL''? '.$ G G
, "=#3 4 4F "=#3 4 4F)0;QSW)X)X&)5 $%; < V^GG&(L
O ##0DHH#NNN 0 1 1 1!|| ##C(((L))G !)3XXt
r! T)r exclude_appliedr r c |r|sdnd}i }|t dfv r| t | j ddg|R t | j d rL| j j @t
| j j dd }|#| dt | t
| j dd }|*| t |d | t |t rBt
| j dd }|*| t || | |S )
u Read (non-data) DICOM tags.
Parameters
----------
index : Ellipsis or int
Metadata is built by layered ``dict.update``:
1. If ``index`` is ``...`` or ``None``, add instance-level tags
(FG sequences omitted as top-level keys;
``TransferSyntaxUID`` included from file_meta).
2. If a shared functional group is present, update with its macros.
3. If ``index`` is an ``int``, update with that frame's per-frame
FG (per-frame wins on conflict).
Classic files with no FG data therefore yield ``{}`` for an
integer ``index``.
exclude_applied : bool
If True (default) and ``raw`` is False, drop tags consumed by the
default ``read`` / ``iter`` reconstruction (rescale / windowing).
Otherwise, leave those tags in the returned dict.
raw : bool
Pair with ``read(..., raw=...)``. If ``False`` (default),
``exclude_applied`` may drop reconstruction tags. Otherwise,
those tags are kept even when ``exclude_applied`` is True.
Returns
-------
metadata : dict
Keyword → value mapping (pydicom keyword names).
)r r RescaleTyper r WindowCenterWidthExplanationVOILUTFunctionr Nr r r file_metaTransferSyntaxUIDr ) r r[ r) ru r. r rN rj rT r& r ) rK r r r omit_appliedmetats
shared_seqper_seqs r metadatazPydicomPlugin.metadata" s} `
(+
" Xt$ $ $ KK M8: &
{33
BM+7 T] 46I4PP>OO$7RAAA T],LdSS
! KK(A ,OOO P P P eS ! ! V dm-OQUVVG" ,WU^| T T TUUU r! )r is_planarndimager r c L |r0| D ]\ }}t | j || t | | j _ | j | t j | }|j dk s)|j dk r|s |j dk r|j
d dk r|d }|D ]}| | | j j
t k r?| | j S dS )a Write an image stack to DICOM.
Parameters
----------
ndimage : ArrayLike
The ndimage to write.
metadata : dict
Global metadata (instance-level) to write to the file.
is_planar : bool
If True, the provided ndimage is assumed to use planar color layout
([Frame, Channel], Height, Width). Otherwise, it is assumed to
be interleaved ([Frame], Height, Width, [Channel]).
Stored as DICOM ``PlanarConfiguration``.
kwargs : Any
Additional kwargs are forwarded to ``pydicom.dcmwrite``.
Returns
-------
bytes or None
Encoded bytes when the URI is ``""``, else ``None``.
r r r N)r: r; ru r PlanarConfigurationrl r[ r r ndimr write_framerd _uri_typer
_flushrt getvalue) rK r r r r r< r r r s r writezPydicomPlugin.writey s : > &nn . .
>
>
U"4=#u====,/ NN
) ((( j!! HMMA
)
A
#)B-1"4"4i.C $ $E U # # # # < !Y . . KKMMM<((**3355 5tr! c ( t fd S )z-Instance-level (global) metadata of the file.c j S r9 )ru rK s r z1PydicomPlugin.instance_metadata.. s t} r! )rG r s `r instance_metadataz PydicomPlugin.instance_metadata s ,,,,---r! r c t | D ]\ }}t | j || d S r9 )r@ r: r; ru )rK r r< vals r r z PydicomPlugin.instance_metadata sH U ))++ 8 8HC t}c3 7 7 7 7 8 8r! c F dt j f fd }t | S )zMetadata in the shared functional group.
The tags stored here are writen once but applied to each frame
in the dicom file.
r c t j d rt j j s;t j t j g j _ j j d S )Nr r )r. ru lenr r' r* r r( r s r get_itemz5PydicomPlugin.shared_frame_metadata..get_item st 4=*JKK
SV
<T T
@D}?U?U\^^$@ @
< =?B Br! )r' r( rG )rK r s ` r shared_frame_metadataz#PydicomPlugin.shared_frame_metadata sA C$, C C C C C C x r! c t j t t | g | j _ d S r9 )r' r* r r= r@ ru r )rK r s r r z#PydicomPlugin.shared_frame_metadata s8 7;}7M7M
d5kk
*
* +8
8
444r! c | j S )a The pixel compression to use when writing.
Available options:
- None: (system default)
- "rle": RLE lossless compression
- "jpeg-ls": JPEG-LS lossless compression
- "jpeg-ls-near": JPEG-LS near lossless compression
- "jpeg2000": JPEG 2000 lossless compression
- "jpeg2000-lossless": JPEG 2000 lossless compression
- Any transfer syntax UID string
Returns
-------
compression : str or None
Resolved transfer syntax UID, or ``None``.
)rk r s r compressionzPydicomPlugin.compression s
$ r! c | d | _ d S t | }t j j t j j t j j t j j t j j d}||v r t || | _ d S |r'|d r
d|v r || _ d S t d|dd | d )N)rlezjpeg-lsz jpeg-ls-nearjpeg2000zjpeg2000-losslessr r zUnknown compression z. Use one of: z, z# (or a transfer syntax UID string).) rk rT r' rx RLELosslessJPEGLSLosslessJPEGLSNearLosslessJPEG2000JPEG2000Losslessisdigitr join)rK r textnamess r r zPydicomPlugin.compression s = $D F5zz8'x. H 7 )!%!:
5== #E$K 0 0D F DGOO%% #++ $D F
15
1
1$))E:J:J
1
1
1
r! )r r c | j t j | | j |rt | nd dS )zAdd the given ndimage to the frames in this image.
Parameters
----------
frame : ArrayLike
Single frame array.
metadata : dict
Local metadata associated with this ndimage.
N)rm r r r rn r@ )rK r r s r r zPydicomPlugin.write_frame sP
BJu - -... ##h$HDNNNDIIIIIr! r colormap first_mappedc t j |d }d|j j z }|j d dk rdn |j d }dD ] }|| j v rt
| j | !|||g}dd|j d }t | D ]S\ } }
t | j |
d
| t | j |
d |dd| f Td | j _
dS )
ax Set the given colormap as the image's LUT.
Parameters
----------
colormap : ArrayLike
RGB(A) colormap as a 2D array of shape ``(N, 3)`` or ``(N, 4)``
with dtype ``uint8`` or ``uint16`` (up to ``2**16`` entries).
first_mapped : int
Offset subtracted from stored pixel values before indexing the LUT.
Forderr r r &GreenPaletteColorLookupTableDescriptor%BluePaletteColorLookupTableDescriptor&AlphaPaletteColorLookupTableDescriptor RedPaletteColorLookupTableData GreenPaletteColorLookupTableData BluePaletteColorLookupTableDatar 'SegmentedRedPaletteColorLookupTableData)SegmentedGreenPaletteColorLookupTableData(SegmentedBluePaletteColorLookupTableDatar RedGreenBlueAlphaNr !PaletteColorLookupTableDescriptorPaletteColorLookupTableDatar ) r r r itemsizer ru delattr enumeraterD tobytesr ) rK r r cmapr n_entriesname
descriptorr ichannels r lut_densezPydicomPlugin.lut_dense s2 z(#...4:&& A %//AATZ]
- -D t}$$
t,,, t4
4_tz!}_E#H--
JAw
===
777QQQT
""$$
3B
///r! colorsindicesc t j |d }t j | }|d dz }|dk rdn|}d}dD ] }|| j v rt | j | !|||g} d d
|j d }
t
|
D ]\ } } t | j | d | |d
d
| f }
t j d t | z d
}dd|
d f|dd < t t | dz
D ]3}d||dz || z
|
|dz f|d |dz z d |dz z < 4t | j d| d| d| j _ d
S )a Set a piecewise linear gradient as the image's LUT.
Builds a gradient LUT using DICOM's segmented palette tags.
This allows more efficient storage of a gradient palette. The
palette is defined by a sequence of knot points at different
pixel intensities.
Parameters
----------
colors : ArrayLike
Knot colors as a 2D array of shape (K, 3) or (K, 4).
indices : ArrayLike
0-based indicies of pixel intensities where each knot is
located. Assumed to be strictly increasing.
first_mapped : int
Offset subtracted from stored pixel values before indexing
the LUT.
r r r r r r r r r& Nr+ r z. s& ;;q};;;;;;r! c 0 g | ]}t |pi S r rC )r r s r r z(PydicomPlugin._flush.. s% SSSd%djb11SSSr! enforce_file_format);ro rd rp rq r r rm r rN ru r. r r stackrE r r- rT r r r r. r r r r r r HighBitkindr ascontiguousarrayr0 r1 r' valuerepVROBOWdatasetFileMetaDatasetr
is_compressedrx ExplicitVRLittleEndianr set_pixel_dataanyrn r* r r rk compressr@ rl rj save_asrt )
rK r has_paletter bits_stored photometricsamplesr r r tsyntaxr: save_kwargss
r r zPydicomPlugin._flush sJ = F < $ 4 4 F| DM F
/DaHHIIQN M;
O
T]$M
N
N
4< A%%
LOO$,Q/// t}l33
(DM $ $SY'' )KK
T]$?
@
@ dm EFFKK
\!_
!Q
&
&'KK K $ "%)BCC. GT44< A%%#t}44DM+;<<RSSSE=A]=S=S> >DM :
! ,
&&s4+<'='=>>> t 011K " "#8$ ? ? ? !DM !$,"7"7"9"9 I I[ I I I DMMMDDM s
BQ& & Q/c | j j j t j k r| | j dS )z9Flush a write buffer (if needed) and release the request.N)rd rp rq r r r finishr s r closezPydicomPlugin.close s> < $ 4 4 KKMMM r! )r N)r )(r\ r] r^ r_ r rL r r ndarrayra r r r rr r r r r r r r rT r r r r r+ r propertyrG r setterr r r r7 rB r rh
__classcell__)r s @r rc rc sz * *d * * * * * *:A A A A=
=D =RZ = = = = $ ' ' ' }' '
' ' ' 'R #( @ @ @4 @hrz6J @ @ @ @* )-%`
`
`
`
37`
`
`
`
`
J $ U U U U U
U
c3h
U U U Uv .2 3 3 3y$y/123 4S>* 3
3
% 3 3 3 3j .7 . . . X. 8tCH~ 8$ 8 8 8 8 !w ! ! ! X!$ !
4S>
d
"!
!Xc] ! ! ! X!&
%S/!:
t
0 IM
J
J
J
J-5d38n-E
J
J
J
J
J -B -B) -B3 -Bt -B -B -B -Bf FB FBFB FB FB
FB FB FB FBPX! X! X! X!t r! rc )"r_ typingr r r r r r r r
r numpyr pydicomr' ImportErrorr core.requestr
r r r core.v3_plugin_apir r r r r( rT r) r= r; rG rc r r! r rs s u un Y X X X X X X X X X X X X X X X X X X X X X
+]
K J J J J J J J J J J J : : : : : : : : c c Xc] tCQTH~ 4S> dl 4< c # $ .X X X X X H X X X X X s # 9 49