updatePatientCoordinateSystem

Update patient coordinate system convention

Renamed from orient in R2025a

Syntax

orientR = updatePatientCoordinateSystem(R,targetSpace)

Description

orientR = updatePatientCoordinateSystem(R,targetSpace) updates the patient coordinate system convention of the spatial referencing information R to the specified convention targetSpace and returns an equivalent spatial referencing information object, orientR, that uses the specified patient coordinate system convention. Use this function to set or update the patient coordinate system convention, such as from LPS+ to RAS+.

Examples

Update Patient Coordinate System Convention of Medical Spatial Referencing Object

Download a chest CT volume saved as a directory of DICOM files. The volume is part of a data set containing three CT volumes. The size of the entire data set is approximately 81 MB.

Run this code to 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 the DICOM files for the first CT volume in the data set. Create a medical volume object that contains the image and spatial metadata for the CT volume.

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

The VolumeGeometry property contains a medicalref3d object that specifies the spatial referencing for the volume. Extract the medicalref3d object for the chest CT.

R = medVol.VolumeGeometry

R = 
  medicalref3d with properties:

                 VolumeSize: [512 512 88]
                   Position: [88×3 double]
             VoxelDistances: {[88×3 double]  [88×3 double]  [88×3 double]}
    PatientCoordinateSystem: "LPS+"
               PixelSpacing: [88×2 double]
                   IsAffine: 1
              IsAxesAligned: 1
                    IsMixed: 0

The PatientCoordinateSystem property of the medicalref3d object specifies the mapping between the patient coordinate system axes and the anatomical directions within the patient. The initial value, based on the DICOM file metadata, is LPS+. An LPS+ value indicates that the positive x-, y-, and z-axes point in the left, posterior, and superior directions, respectively.

R.PatientCoordinateSystem

ans = 
"LPS+"

Update the patient coordinate system convention to RAS+, which indicates that the positive x-, y-, and z-axes point in the right, anterior, and superior directions, respectively. The updatePatientCoordinateSystem object function returns a new medicalref3d object, orientR. In addition to the PatientCoordinateSystem property, the Position and VoxelDistances property values reflect the new spatial mapping of orientR.

orientR = updatePatientCoordinateSystem(R,"RAS+")

orientR = 
  medicalref3d with properties:

                 VolumeSize: [512 512 88]
                   Position: [88×3 double]
             VoxelDistances: {[-0.7285 0 0]  [0 -0.7285 0]  [0 0 2.5000]}
    PatientCoordinateSystem: "RAS+"
               PixelSpacing: [0.7285 0.7285]
                   IsAffine: 1
              IsAxesAligned: 1
                    IsMixed: 0

Input Arguments

R — Spatial referencing information

medicalref3d object

Spatial referencing information, specified as a medicalref3d object.

targetSpace — Target convention of the patient coordinate system

"LPS+" | "LAS+" | "RAS+"

Target convention of the patient coordinate system, specified as "LPS+", "LAS+", or "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.

Data Types: char | string

Output Arguments

orientR — Spatial referencing information with target patient coordinate system convention

medicalref3d object

Spatial referencing information with the target patient coordinate system convention, returned as a medicalref3d object. Which properties of this object the updatePatientCoordinateSystem function updates from R depends on the PatientCoordinateSystem property of R.

• If PatientCoordinateSystem is "unknown", then updatePatientCoordinateSystem updates only the PatientCoordinateSystem of orientR.

• If PatientCoordinateSystem is not "unknown", then updatePatientCoordinateSystem updates the VoxelDistances and Position properties of orientR, in addition to the PatientCoordinateSystem property, to maintain the correct mapping between the intrinsic and patient coordinate system axes.

Version History

Introduced in R2022b

R2025a: Renamed from orient

The orient object function is now called updatePatientCoordinateSystem. The behavior of the function remains the same, and existing instances of the old name in your code continue to work as expected.