repository·master·Indexed 20 days ago
https://github.com/nipy/nibabelA Python library providing read and write access to common neuroimaging file formats, exposing image data as NumPy arrays and providing access to file headers. It includes tools for coordinate system transformations (RAS+ convention), affine matrix manipulation, and CLI utilities such as nib-diff, nib-ls, nib-nifti-dx, and tractogram converters (nib-tck2trk, nib-trk2tck).
NiBabel provides read and write access to common neuroimaging file formats. It allows for full or selective access to header information (metadata) and provides image data as NumPy arrays.
Supported formats include:
NiBabel is a Python package designed for efficient neuroimaging data processing. Key features include:
DICOM (Digital Imaging and Communications in Medicine) is a standard for storing medical data in memory and on disk, and for communicating that data over a network.
In the context of nibabel, we focus on DICOM files. A DICOM file is essentially a binary dump of the objects that DICOM sends across a network. Specifically, a DICOM file encapsulates a Data Set representing a SOP Instance (Service Object Pair Instance) related to a DICOM IOD (Information Object Definition).
Key structural concepts:
C-ECHO or C-STORE).An Attribute Macro is a named set of attributes that are described in a single table and can be referenced (included) by multiple Modules or other macros. This allows for the reuse of common attribute groups within the DICOM standard.
When a macro is "Included" in a module, the specific tags and types defined in that macro's table are added to the module's attribute set.
Nibabel determines the primary image .affine by following this priority order (implemented in get_best_affine()):
sform_code is not 0 ('unknown'), use the sform affine.qform_code is not 0 ('unknown'), use the qform affine.Every new image format in NiBabel must conform to the standard Image API. To ensure compliance, you should add a test class for your image in nibabel.tests.test_image_api. This allows the core library to interact with your format using a predictable interface.
When implementing your image, you are responsible for providing three core components:
dataobj: An array or an array proxy (implementing the ArrayProxy API).affine: A 4x4 array relating image array coordinates to RAS+ world coordinates.header: A metadata container that implements at least get_data_dtype and get_data_shape.class TestMyFormatAPI(LoadImageAPI):
def loader(self, fname):
return my_format.load(fname)
example_images = MY_FORMAT_EXAMPLE_IMAGESThe 4x4 image affine matrix $A$ encodes both the linear transformation $M$ (rotation and zoom) and the translation vector $(a, b, c)$.
If $m_{i,j}$ is the value in row $i$ and column $j$ of the 3x3 matrix $M$, the 4x4 affine matrix is structured as follows:
$$A = \begin{bmatrix} m_{1,1} & m_{1,2} & m_{1,3} & a \ m_{2,1} & m_{2,2} & m_{2,3} & b \ m_{3,1} & m_{3,2} & m_{3,3} & c \ 0 & 0 & 0 & 1 \end{bmatrix}$$
In practice, applying the transformation is often computed by breaking it into its components: $$\begin{bmatrix} x \ y \ z \end{bmatrix} = M \begin{bmatrix} i \ j \ k \end{bmatrix} + \begin{bmatrix} a \ b \ c \end{bmatrix}$$ This is mathematically equivalent to the 4x4 homogeneous multiplication as long as the last row is $[0, 0, 0, 1]$.
The 2D affine matrix $A$ maps row ($r$) and column ($c$) indices to patient coordinates $(P_x, P_y, P_z)$.
To calculate this, first define a flipped orientation matrix $F$ from the 'ImageOrientationPatient' (0020,0037) values $(i_1 .. i_6)$:
$$F = \begin{bmatrix} i_4 & i_1 \ i_5 & i_2 \ i_6 & i_3 \end{bmatrix}$$
Where the first column of $F$ is the direction cosine for the row (Y) and the second column is for the column (X). The affine $A$ is then:
$$\begin{bmatrix} P_x\ P_y\ P_z\ 1 \end{bmatrix} = \begin{bmatrix} F_{11}\Delta{r} & F_{12}\Delta{c} & 0 & S_x \ F_{21}\Delta{r} & F_{22}\Delta{c} & 0 & S_y \ F_{31}\Delta{r} & F_{32}\Delta{c} & 0 & S_z \ 0 & 0 & 0 & 1 \end{bmatrix} \begin{bmatrix} r\ c\ 0\ 1 \end{bmatrix} = A \begin{bmatrix} r\ c\ 0\ 1 \end{bmatrix}$$
Variables:
Nibabel manages the distinction between spatial and temporal axes differently depending on the file format. For many formats (like NIfTI, PAR/REC, ECAT, and MGH), the time axis is conventionally the 4th axis (index 3) in a 4D array.
However, MINC1 and MINC2 formats typically place the time axis as the first axis. To maintain consistency for users, Nibabel provides mechanisms to identify the time dimension regardless of the underlying format convention.
A Nibabel image object is an association of three components:
You can load an image using nib.load(filename). Once loaded, you can access these components via the .dataobj, .affine, and .header attributes.
import nibabel as nib
import os
# Load an image
img = nib.load('path_to_image.nii.gz')
# Access components
data_proxy = img.dataobj
aff_matrix = img.affine
header = img.headerWhen working with DICOM modules, their presence is governed by specific usage requirements defined in the standard. The following abbreviations are used to denote these requirements:
Contrast/bolus is required if contrast media was used in the image).Nibabel follows a general rule of thumb: when returning an image array, the axes are ordered according to the format's user documentation or the underlying file structure. This means the 'time' or 'volume' axis can appear at different positions depending on the file format:
When processing images, always verify the axis order for your specific format to ensure you are correctly identifying slices, time points, or encoding directions (frequency vs. phase).