Main Content

resample

Resample medical image volume in different patient coordinate system

Since R2022b

collapse all in page

Syntax

medVolResampled = resample(medVol,R)
medVolResampled = resample(medVol,R,Name=Value)

Description

medVolResampled = resample(medVol,R) resamples the voxel data stored in the medicalVolume object medVol in the patient coordinate system specified by R. The updated voxel data is returned in a new medicalVolume object, medVolResampled.

example

medVolResampled = resample(medVol,R,Name=Value) specifies additional options for resampling the voxel data using name-value arguments. For example, Method="linear" specifies a linear method for resampling.

Examples

collapse all

Open Live Script

Resample a chest CT volume to a target voxel size, without changing the spatial limits in the patient coordinate system. This can be useful to standardize the voxel spacing in a data set of scans acquired using different settings.

The CT volume is saved as a directory of DICOM files. The volume is part of a data set containing three CT scans. The size of the entire data set is approximately 81 MB. Download the data set from the MathWorks® website, then unzip the folder.

zipFile = matlab.internal.examples.downloadSupportFile("medical","MedicalVolumeDICOMData.zip");
filepath = fileparts(zipFile);
unzip(zipFile,filepath)

Specify the directory of DICOM files for the first CT volume in the data set.

dataFolder = fullfile(filepath,"MedicalVolumeDICOMData","LungCT01");

Create a medical volume object, medVol, for the CT volume. The voxel size is 0.7285-by-0.7825-by-2.5 mm.

medVol = medicalVolume(dataFolder);
medVol.VoxelSpacing
ans = 1×3

    0.7285    0.7285    2.5000

Resample medVol so that it has a voxel size of 0.5-by-0.5-by-1.25 mm. First, calculate the ratio between the original voxel size and the target voxel size, in millimeters, in each dimension.

targetVoxelSize = [0.5 0.5 1.25];
ratios = targetVoxelSize ./ medVol.VoxelSpacing;

Calculate the target dimensions, in voxels, of the resampled volume.

origSize = size(medVol.Voxels);
newSize = round(origSize ./ ratios);

Define the spatial referencing for the resampled volume. First, get the mapping between the intrinsic and patient coordinate systems of medVol by using the intrinsicToWorldMapping object function. The output, origMapping, is an affinetform3d object that contains a transformation matrix in its A property.

origRef = medVol.VolumeGeometry;
origMapping = intrinsicToWorldMapping(origRef);
tform = origMapping.A;

Transform the matrix tform so that it corresponds to the target voxel size. Create an affinetform3d object, newMapping, that contains the transformed matrix.

newMapping4by4 = tform.* [ratios([2 1 3]) 1];
newMapping = affinetform3d(newMapping4by4);

Create a medicalref3d object that describes the target spatial referencing for the resampled volume. 

newRef = medicalref3d(newSize,newMapping);

To maintain the mapping between the patient coordinate axes and the anatomical planes, use the orient object function to set the PatientCoordinateSystem property of newRef to match origRef. 

newRef = orient(newRef,origRef.PatientCoordinateSystem);

Resample medVol by using the resample object function. The voxel size of the new medical volume matches the target size.

newVol = resample(medVol,newRef)
newVol = 
  medicalVolume with properties:

                 Voxels: [746×746×176 int16]
         VolumeGeometry: [1×1 medicalref3d]
           SpatialUnits: "unknown"
            Orientation: "transverse"
           VoxelSpacing: [0.5000 0.5000 1.2500]
           NormalVector: [0 0 1]
       NumCoronalSlices: 746
      NumSagittalSlices: 746
    NumTransverseSlices: 176
           PlaneMapping: ["sagittal"    "coronal"    "transverse"]
               Modality: "unknown"
          WindowCenters: []
           WindowWidths: []

Input Arguments

collapse all

Medical volume, specified as a medicalVolume object.

Spatial referencing object, specified as a medicalref3d object. R defines the spatial details for the resampled volume.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: resample(medVol,R,Method="linear") calculates the voxel values in medVolResampled by linearly interpolating voxel values at the corresponding locations in medVol.

Fill value, specified as a numeric scalar. The value of FillValue must be supported by the data type of the voxel data stored in the Voxels property of R. If an output voxel in the volume defined by R falls outside the input volume, medVol, resample sets the corresponding value of medVolResampled to FillValue.

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

Resampling method, specified as "cubic", "linear", or "nearest".

Data Types: char | string

Output Arguments

collapse all

Resampled medical volume, returned as a medicalVolume object. The VolumeGeometry property of medVolResampled contains the spatial referencing information specified by R. The resampled voxel data is stored in the Voxels property of medVolResampled.

Algorithms

The resample function calculates the voxel values in the output volume, medVolResampled, by mapping locations in the output volume to the corresponding locations in the input volume (an inverse mapping). When the center of the voxel in the output volume does not map to the center of a voxel in the input volume, resample interpolates the input voxel values to calculate the output values.

resample performs the mapping in the patient coordinate systems of each volume. The function assumes that the patient coordinate systems of the input and output volumes have the same orientation convention, specified by the PatientCoordinateSystem property of a medicalref3d object, and that the patient coordinate systems have the same origin.

Version History

Introduced in R2022b

See Also

|

Topics