medicalref3d

Spatial referencing information for 3-D medical image volumes

Since R2022b

Description

A medicalref3d object stores the relationship between the intrinsic coordinate system anchored to the columns, rows, and planes of a medical image volume and the real-world patient coordinate system.

The medicalref3d object handles affine and non-affine medical image volumes. For non-affine volumes, the object stores information about the spacing and orientation of each slice in each dimension. You can also use the medicalref3d object to access and update the mapping between the patient coordinate system axes and the left-right, superior-inferior, and anterior-posterior anatomical axes.

Creation

You can create a medicalred3d object in these ways:

• medicalVolume — Creates a medicalref3d object, stored in the VolumeGeometry property.

• The medicalref3d function described here.

Syntax

R = medicalref3d(volumeSize,tform)

R = medicalref3d(volumeSize,position,pixelSpacing,cosines)

R = medicalref3d(volumeSize,position,voxelDistances)

R = medicalref3d(volumeSize)

R = medicalref3d(volumeSize,voxelSpacing)

Description

R = medicalref3d(volumeSize,tform) creates a medicalref3d object and sets the VolumeSize property. tform is an affinetform3d object that specifies an affine image volume.

R = medicalref3d(volumeSize,position,pixelSpacing,cosines) specifies the spatial referencing information for an affine or non-affine image volume by setting the Position and PixelSpacing properties, and specifies the orientation of each slice using the cosines argument.

R = medicalref3d(volumeSize,position,voxelDistances) specifies the spatial referencing information for an affine or non-affine image volume by setting the Position and VoxelDistances properties.

R = medicalref3d(volumeSize) assumes that the image volume is aligned and affine, and specifies default values of the spatial referencing information of the image volume using only the volume size. (since R2024a)

R = medicalref3d(volumeSize,voxelSpacing) specifies the spatial referencing information of the image volume by setting the VoxelDistances and PixelSpacing properties using the specified voxel spacing voxelSpacing. (since R2024a)

Input Arguments

tform — Geometric transformation between image data array and patient coordinate system

affinetform3d object

Geometric transformation between the image data array and the patient coordinate system, specified as an affinetform3d object. The A property of tform contains a 4-by-4 3-D transformation matrix that maps triplets of pixel indices in the order (column, row, slice) to (x, y, z) triplets of patient coordinates in real-world units.

cosines — Orientation of each slice in patient coordinate system

2-by-3-by-p numeric array

Orientation of each slice in the patient coordinate system, specified as a 2-by-3-by-p numeric array, where p is the number of slices in the image volume along the third dimension. Each 2-by-3 matrix specifies the orientation of one slice:

• The first row specifies the direction cosines of the first dimension, which is aligned with the rows of the data array, relative to the x-, y-, and z-axes of the patient coordinate system.

• The second row specifies the direction cosines of the second dimension, which is aligned with the columns of the data array, relative to the x-, y-, and z-axes of the patient coordinate system.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

voxelSpacing — Distance between voxel centers in each dimension

1-by-3 numeric vector of positive values

Distance between the voxel centers in each dimension, specified as a 1-by-3 numeric vector of positive values.

Data Types: single | double

Properties

VolumeSize — Number of voxels in each dimension of data array

3-element row vector of positive integers

Number of voxels in each dimension of the data array, specified as a 3-element row vector of positive integers. The three elements of VolumeSize specify the number of rows, columns, and slices, respectively, in the image data. You must set this property at object creation by using the volumeSize input argument. Otherwise, this property is read-only.

Data Types: double

Position — Patient coordinates of pixel in first index of each slice in data array

p-by-3 numeric matrix

Patient coordinates of the pixel in the first index of each slice in the data array, specified as a p-by-3 numeric matrix. p is the number of slices in the image volume along the third dimension. Each row specifies the xyz-coordinates, in real-world units, of the center of the first pixel of the corresponding slice. The first pixel is the pixel in the first row and column of the data array. You can set this property at object creation directly, by using the position input argument, or indirectly, by using the tform input argument. Otherwise, this property is read-only.

Data Types: double

VoxelDistances — 3-D displacement vectors between adjacent voxels

3-element cell array of p-by-3 numeric matrices | 3-element cell array of 1-by-3 numeric matrices

3-D displacement vectors between adjacent voxels, specified as a 3-element cell array of p-by-3 numeric matrices or 1-by-3 numeric matrices. p is the number of slices in the image volume along the third dimension. VoxelDistances defines the 3-D mapping between the intrinsic coordinate system, in voxels, and the patient coordinate system, in real-world units. Displacements can be positive or negative.

• VoxelDistances{1} specifies the real-world displacements [Δx Δy Δz] corresponding to a [1 0 0] voxel displacement.

• VoxelDistances{2} specifies the real-world displacements [Δx Δy Δz] corresponding to a [0 1 0] voxel displacement.

• VoxelDistances{3} specifies the real-world displacements [Δx Δy Δz] corresponding to a [0 0 1] voxel displacement.

For example, VoxelDistances{2}(1,:) specifies the vector between voxels of the first slice when moving along the second dimension of the data array.

If the image volume is non-affine, or if the medicalref3d object was created as the VolumeGeometry property value of a medicalVolume object for a DICOM file, then VoxelDistances specifies displacement vectors for each slice in a separate row. Otherwise, each element of VoxelDistances simplifies to a 1-by-3 matrix.

You can set this property at object creation directly, by using the voxelDistances input argument, or indirectly, by using the tform, position, pixelSpacing, cosines, or voxelSpacing input argument. Otherwise, this property is read-only.

Data Types: cell

PatientCoordinateSystem — Orientation convention of patient coordinate system relative to anatomical axes

"unknown" (default) | "LPS+" | "LAS+" | "RAS+"

Orientation convention of the patient coordinate system relative to the anatomical axes, specified as "LPS+", "LAS+", "RAS+", or "unknown". For "LPS+", "LAS+", and "RAS+", the first three characters indicate the positive direction of the x-, y-, and z-axes of the patient coordinate system, respectively.

• The positive direction of the x-axis points left ("L") or right ("R").

• The positive direction of the y-axis points anterior ("A") or posterior ("P").

• The positive direction of the z-axis points inferior ("I") or superior ("S").

• "+" indicates that values increase in the stated direction.

For example, "LPS+" specifies a patient coordinate system with the x-, y-, and z-axes positive in the left, posterior, and superior directions, respectively.

The default value is "unknown". For a medicalref3d object created by the medicalVolume function, the PatientCoordinateSystem is set based on the corresponding attribute of the file metadata, if present.

Data Types: char | string

PixelSpacing — Spacing between voxel centers in first two dimensions of each slice

p-by-2 matrix of positive values | 2-element vector of positive values

Spacing between voxel centers in the first two dimensions of each slice, specified as a p-by-2 matrix or 2-element vector of positive values. p is the number of slices in the image volume along the third dimension. Each row specifies the distances between voxel centers, for one slice, in the form [dim2Spacing dim1Spacing]. Distances are in real-world units such as millimeters. This image shows the definition of dim1Spacing and dim2Spacing.

If the image volume is non-affine, or if the medicalref3d object was created as the VolumeGeometry property value of a medicalVolume object for a DICOM file, then the PixelSpacing property specifies spacing for each slice in a separate row. Otherwise, PixelSpacing simplifies to a 2-element vector.

You can set this property at object creation directly, by using the pixelSpacing input argument, or indirectly, by using the tform, voxelDistances, or voxelSpacing input argument. Otherwise, this property is read-only.

Data Types: double

IsAffine — Spatial referencing system is affine

true or 1 | false or 0

This property is read-only.

Spatial referencing system is affine, specified as a logical 1 (true) or 0 (false). An image volume is affine if these conditions are met:

• All slices are parallel to each other.

• The spacing between slices in each dimension is uniform.

• The upper-left voxels of all slices are collinear.

• No two slices are coincident, meaning no two slices are located at the same position in space.

Data Types: logical

IsAxesAligned — Image data array is aligned with patient coordinate system

true or 1 | false or 0

This property is read-only.

Image data array is aligned with the patient coordinate system, specified as a logical 1 (true) or 0 (false). A true value indicates that the directions along which the row, column, and slice indices change are aligned with the x-, y-, and z-axes of the patient coordinate system.

Data Types: logical

IsMixed — Orientation of image slices is mixed

true or 1 | false or 0

This property is read-only.

Orientation of the image slices is mixed, specified as a logical 1 (true) or 0 (false). A false value indicates that all of the slices in the image volume are parallel and have a similar orientation. A true value indicates that one or more slices are not parallel and similarly oriented to other slices.

Data Types: logical

Object Functions

intrinsicToWorldMapping	Geometric transform between intrinsic and patient coordinates of medical image volume
contains	Determine if affine image volume contains points specified in patient coordinate system
intrinsicToWorld	Map points from intrinsic coordinates to patient coordinates
oneSliceIntrinsicToWorldMapping	Geometric transform between intrinsic and patient coordinates of medical image volume slice
orient	Update patient coordinate system convention
sliceCorners	Extract patient coordinates of corner voxels for one slice
worldToIntrinsic	Map points from patient coordinates to intrinsic coordinates
worldToSubscript	Convert from patient coordinates to row and column subscripts

Examples

Create medicalref3d Object Using Volume Size and Geometric Transformation

Specify the size of the target image volume array, in voxels.

volumeSize = [256 256 100];

Specify the geometric transformation that describes the mapping between the intrinsic and patient coordinates for the target image volume. Assume the patient coordinate system has units of millimeters.

Specify the scale factors that correspond to voxel dimensions of 0.5 mm, 0.5 mm, and 1.0 mm.

sx = 0.5;
sy = 0.5;
sz = 1;

Specify the position of the first voxel of the first transverse slice, in millimeters. The position defines the translation between the intrinsic coordinate origin and the patient coordinate origin.

tx = 1000;
ty = 50;
tz = 75;

Define a 4-by-4 geometric transformation matrix that performs the voxel scaling and translation. The first column corresponds to the y-dimension of the image, and the second column corresponds to the x-dimension.

A = [0 sx 0 tx; 
    sy 0 0 ty; 
    0 0 sz tz; 
    0 0 0 1];

Create an affinetform3d object that performs the transformation.

tform = affinetform3d(A);

Create a medicalref3d object with the specified array size and geometric transformation.

R = medicalref3d(volumeSize,tform)

R = 
  medicalref3d with properties:

                 VolumeSize: [256 256 100]
                   Position: [100x3 double]
             VoxelDistances: {[0.5000 0 0]  [0 0.5000 0]  [0 0 1]}
    PatientCoordinateSystem: "Unknown"
               PixelSpacing: [0.5000 0.5000]
                   IsAffine: 1
              IsAxesAligned: 1
                    IsMixed: 0

Version History

Introduced in R2022b

R2024a: Create spatial referencing object using only volume size

Create medicalref3d objects using only the dimensions of the image volume. You can optionally generate voxel distance and pixel spacing information for the spatial referencing object by specifying the distance between voxel centers.