DICOM reader
csareader | CSA header reader from SPM spec |
dicomreaders | |
dicomwrappers | |
dwiparams | |
structreader |
CSA header reader from SPM spec
CSAError | |
CSAReadError | |
get_acq_mat_txt(csa_dict) | |
get_b_matrix(csa_dict) | |
get_b_value(csa_dict) | |
get_csa_header(dcm_data[, csa_type]) | Get CSA header information from DICOM header |
get_g_vector(csa_dict) | |
get_ice_dims(csa_dict) | |
get_n_mosaic(csa_dict) | |
get_scalar(csa_dict, tag_name) | |
get_slice_normal(csa_dict) | |
get_vector(csa_dict, tag_name, n) | |
is_mosaic(csa_dict) | Return True if the data is of Mosaic type |
nt_str(s) | Strip string to first null |
read(csa_str) | Read CSA header from string csa_str |
DicomReadError | |
mosaic_to_nii(dcm_data) | Get Nifti file from Siemens |
read_mosaic_dir(dicom_path[, globber, ...]) | Read all Siemens mosaic DICOMs in directory, return arrays, params |
read_mosaic_dwi_dir(dicom_path[, globber, ...]) | |
slices_to_series(wrappers) | Sort sequence of slice wrappers into series |
Classes to wrap DICOM objects and files
The wrappers encapsulate the capabilities of the different DICOM formats.
They also allow dictionary-like access to named fields.
For calculated attributes, we return None where needed data is missing. It seemed strange to raise an error during attribute processing, other than an AttributeError - breaking the ‘properties manifesto’. So, any processing that needs to raise an error, should be in a method, rather than in a property, or property-like thing.
MosaicWrapper(dcm_data[, csa_header, n_mosaic]) | Class for Siemens mosaic format data |
MultiframeWrapper(dcm_data) | Wrapper for Enhanced MR Storage SOP Class |
SiemensWrapper(dcm_data[, csa_header]) | Wrapper for Siemens format DICOMs |
Wrapper(dcm_data) | Class to wrap general DICOM files |
WrapperError | |
WrapperPrecisionError | |
none_or_close(val1, val2[, rtol, atol]) | Match if val1 and val2 are both None, or are close |
wrapper_from_data(dcm_data) | Create DICOM wrapper from DICOM data object |
wrapper_from_file(file_like, *args, **kwargs) | Create DICOM wrapper from file_like object |
Process diffusion imaging parameters
Thus:
b = norm(q)
g = q / norm(q)
(norm(q) is the Euclidean norm of q)
The B matrix B is a symmetric positive semi-definite matrix. If q_est is the closest q vector equivalent to the B matrix, then:
B ~ (q_est . q_est.T) / norm(q_est)
B2q(B[, tol]) | Estimate q vector from input B matrix B |
nearest_pos_semi_def(B) | Least squares positive semi-definite tensor estimation |
q2bg(q_vector[, tol]) | Return b value and q unit vector from q vector q_vector |
Stream-like reader for packed data
Unpacker(buf[, ptr, endian]) | Class to unpack values from buffer object |
Utilities for working with DICOM datasets
find_private_section(dcm_data, group_no, creator) | Return start element in group group_no given creator name creator |
Bases: nibabel.nicom.csareader.CSAError
x.__init__(...) initializes x; see help(type(x)) for signature
Get CSA header information from DICOM header
Return None if the header does not contain CSA information of the specified csa_type
Parameters: | dcm_data : dicom.Dataset
csa_type : {‘image’, ‘series’}, optional
|
---|---|
Returns: | csa_info : None or dict
|
Return True if the data is of Mosaic type
Parameters: | csa_dict : dict
|
---|---|
Returns: | tf : bool
|
Strip string to first null
Parameters: | s : bytes |
---|---|
Returns: | sdash : str
|
Read CSA header from string csa_str
Parameters: | csa_str : str
|
---|---|
Returns: | header : dict
|
Get Nifti file from Siemens
Parameters: | dcm_data : dicom.DataSet
|
---|---|
Returns: | img : Nifti1Image
|
Read all Siemens mosaic DICOMs in directory, return arrays, params
Parameters: | dicom_path : str
globber : str, optional
check_is_dwi : bool, optional
dicom_kwargs : None or dict
|
---|---|
Returns: | data : 4D array
affine : (4,4) array
b_values : (N,) array
unit_gradients : (N, 3) array
|
Sort sequence of slice wrappers into series
This follows the SPM model fairly closely
Parameters: | wrappers : sequence
|
---|---|
Returns: | series : sequence
|
Bases: nibabel.nicom.dicomwrappers.SiemensWrapper
Class for Siemens mosaic format data
Mosaic format is a way of storing a 3D image in a 2D slice - and it’s as simple as you’d imagine it would be - just storing the slices in a mosaic similar to a light-box print.
We need to allow for this when getting the data and (because of an idiosyncrasy in the way Siemens stores the images) calculating the position of the first voxel.
Adds attributes:
Initialize Siemens Mosaic wrapper
The Siemens-specific information is in the csa_header, either passed in here, or read from the input dcm_data.
Parameters: | dcm_data : object
csa_header : None or mapping, optional
n_mosaic : None or int, optional
|
---|
Initialize Siemens Mosaic wrapper
The Siemens-specific information is in the csa_header, either passed in here, or read from the input dcm_data.
Parameters: | dcm_data : object
csa_header : None or mapping, optional
n_mosaic : None or int, optional
|
---|
Get scaled image data from DICOMs
Resorts data block from mosaic to 3D
Returns: | data : array
|
---|
Notes
The apparent image in the DICOM file is a 2D array that consists of blocks, that are the output 2D slices. Let’s call the original array the slab, and the contained slices slices. The slices are of pixel dimension n_slice_rows x n_slice_cols. The slab is of pixel dimension n_slab_rows x n_slab_cols. Because the arrangement of blocks in the slab is defined as being square, the number of blocks per slab row and slab column is the same. Let n_blocks be the number of blocks contained in the slab. There is also n_slices - the number of slices actually collected, some number <= n_blocks. We have the value n_slices from the ‘NumberOfImagesInMosaic’ field of the Siemens private (CSA) header. n_row_blocks and n_col_blocks are therefore given by ceil(sqrt(n_slices)), and n_blocks is n_row_blocks ** 2. Also n_slice_rows == n_slab_rows / n_row_blocks, etc. Using these numbers we can therefore reconstruct the slices from the 2D DICOM pixel array.
Return position of first voxel in data block
Adjusts Siemens mosaic position vector for bug in mosaic format position. See dicom_mosaic in doc/theory for details.
Parameters: | None : |
---|---|
Returns: | img_pos : (3,) array
|
Return image shape as returned by get_data()
Bases: nibabel.nicom.dicomwrappers.Wrapper
Wrapper for Enhanced MR Storage SOP Class
tested with Philips’ Enhanced DICOM implementation
Attributes: | is_multiframe : boolean
frames : sequence
shared : object
|
---|---|
Methods: | image_shape(self) : image_orient_patient(self) : voxel_sizes(self) : image_position(self) : series_signature(self) : get_data(self) : |
Initializes MultiframeWrapper
Parameters: | dcm_data : object
|
---|
Initializes MultiframeWrapper
Parameters: | dcm_data : object
|
---|
Note that this is _not_ LR flipped
The array shape as it will be returned by get_data()
Get i, j, k voxel sizes
Bases: nibabel.nicom.dicomwrappers.Wrapper
Wrapper for Siemens format DICOMs
Adds attributes:
Initialize Siemens wrapper
The Siemens-specific information is in the csa_header, either passed in here, or read from the input dcm_data.
Parameters: | dcm_data : object
csa_header : None or mapping, optional
|
---|
Initialize Siemens wrapper
The Siemens-specific information is in the csa_header, either passed in here, or read from the input dcm_data.
Parameters: | dcm_data : object
csa_header : None or mapping, optional
|
---|
Get DWI B matrix referring to voxel space
Parameters: | None : |
---|---|
Returns: | B : (3,3) array or None
|
Get DWI q vector referring to voxel space
Parameters: | None : |
---|---|
Returns: | q: (3,) array :
|
Add ICE dims from CSA header to signature
Bases: object
Class to wrap general DICOM files
Methods:
Attributes and things that look like attributes:
Initialize wrapper
Parameters: | dcm_data : object
|
---|
Initialize wrapper
Parameters: | dcm_data : object
|
---|
Return b value for diffusion or None if not available
Return b vector for diffusion or None if not available
Get values from underlying dicom data
Return mapping between voxel and DICOM coordinate system
Parameters: | None : |
---|---|
Returns: | aff : (4,4) affine
|
Get scaled image data from DICOMs
We return the data as DICOM understands it, first dimension is rows, second dimension is columns
Returns: | data : array
|
---|
Return unscaled pixel array from DICOM
Note that this is _not_ LR flipped
Return position of first voxel in data block
Parameters: | None : |
---|---|
Returns: | img_pos : (3,) array
|
The array shape as it will be returned by get_data()
Just because we use this a lot for sorting
Return True if other appears to be in same series
Parameters: | other : object
|
---|---|
Returns: | tf : bool
|
Return rotation matrix between array indices and mm
Note that we swap the two columns of the ‘ImageOrientPatient’ when we create the rotation matrix. This is takes into account the slightly odd ij transpose construction of the DICOM orientation fields - see doc/theory/dicom_orientaiton.rst.
Signature for matching slices into series
We use signature in self.is_same_series(other).
Returns: | signature : dict
|
---|
A number that is higher for higher slices in Z
Comparing this number between two adjacent slices should give a difference equal to the voxel size in Z.
See doc/theory/dicom_orientation for description
voxel sizes for array as returned by get_data()
Bases: nibabel.nicom.dicomwrappers.WrapperError
x.__init__(...) initializes x; see help(type(x)) for signature
Match if val1 and val2 are both None, or are close
Parameters: | val1 : None or array-like val2 : None or array-like rtol : float, optional
atol : float, optional
|
---|---|
Returns: | tf : bool
|
Examples
>>> none_or_close(None, None)
True
>>> none_or_close(1, None)
False
>>> none_or_close(None, 1)
False
>>> none_or_close([1,2], [1,2])
True
>>> none_or_close([0,1], [0,2])
False
Create DICOM wrapper from DICOM data object
Parameters: | dcm_data : dicom.dataset.Dataset instance or similar
|
---|---|
Returns: | dcm_w : dicomwrappers.Wrapper or subclass
|
Create DICOM wrapper from file_like object
Parameters: | file_like : object
*args : positional
**kwargs : keyword
|
---|---|
Returns: | dcm_w : dicomwrappers.Wrapper or subclass
|
Estimate q vector from input B matrix B
We require that the input B is symmetric positive definite.
Because the solution is a square root, the sign of the returned vector is arbitrary. We set the vector to have a positive x component by convention.
Parameters: | B : (3,3) array-like
tol : None or float
|
---|---|
Returns: | q : (3,) vector
|
Least squares positive semi-definite tensor estimation
Reference: Niethammer M, San Jose Estepar R, Bouix S, Shenton M, Westin CF. On diffusion tensor estimation. Conf Proc IEEE Eng Med Biol Soc. 2006;1:2622-5. PubMed PMID: 17946125; PubMed Central PMCID: PMC2791793.
Parameters: | B : (3,3) array-like
|
---|---|
Returns: | npds : (3,3) array
|
Examples
>>> B = np.diag([1, 1, -1])
>>> nearest_pos_semi_def(B)
array([[ 0.75, 0. , 0. ],
[ 0. , 0.75, 0. ],
[ 0. , 0. , 0. ]])
Return b value and q unit vector from q vector q_vector
Parameters: | q_vector : (3,) array-like
tol : float, optional
|
---|---|
Returns: | b_value : float
g_vector : shape (3,) ndarray
|
Examples
>>> q2bg([1, 0, 0])
(1.0, array([ 1., 0., 0.]))
>>> q2bg([0, 10, 0])
(10.0, array([ 0., 1., 0.]))
>>> q2bg([0, 0, 0])
(0.0, array([ 0., 0., 0.]))
Bases: object
Class to unpack values from buffer object
The buffer object is usually a string. Caches compiled struct format strings so that repeated unpacking with the same format string should be faster than using struct.unpack directly.
Examples
>>> a = b'1234567890'
>>> upk = Unpacker(a)
>>> upk.unpack('2s') == (b'12',)
True
>>> upk.unpack('2s') == (b'34',)
True
>>> upk.ptr
4
>>> upk.read(3) == b'567'
True
>>> upk.ptr
7
Initialize unpacker
Parameters: | buf : buffer
ptr : int, optional
endian : None or str, optional
|
---|
Initialize unpacker
Parameters: | buf : buffer
ptr : int, optional
endian : None or str, optional
|
---|
Return byte string of length n_bytes at current position
Returns sub-string from self.buf and updates self.ptr to the position after the read data.
Parameters: | n_bytes : int, optional
|
---|---|
Returns: | s : byte string |
Unpack values from contained buffer
Unpacks values from self.buf and updates self.ptr to the position after the read data.
Parameters: | fmt : str
|
---|---|
Returns: | values : tuple
|
Return start element in group group_no given creator name creator
Private attribute tags need to announce where they will go by putting a tag in the private group (here group_no) between elements 1 and 0xFF. The element number of these tags give the start of matching information, in the higher tag numbers.
Parameters: | dcm_data : dicom dataset
group_no : int
creator : str or bytes or regex
|
---|---|
Returns: | element_start : int
|