medicalVolume
Description
A medicalVolume
object stores the voxel data and spatial
referencing information for the medical image volume contained in a single DICOM, NIfTI, or
NRRD file, or in a directory of DICOM files. The medicalVolume
object
specifies the mapping between the intrinsic image coordinate system, the patient coordinate
system, and the anatomical planes. The medicalVolume
object and its object
functions provide a standardized interface for accessing voxel data, spatial referencing, and
intensity scaling information.
Creation
Syntax
Description
creates a medVol
= medicalVolume(dirname
)medicalVolume
object for the image volume contained in a
multifile DICOM series in the directory dirname
.
creates a medVol
= medicalVolume(filenames
)medicalVolume
object for the image volume stored in the single
DICOM, NIfTI, or NRRD file or list of DICOM files specified by
filenames
.
creates a medVol
= medicalVolume(sourceTable
)medicalVolume
object for the image volume listed in
sourceTable
. The table must contain only one row that specifies the
metadata for a DICOM volume.
creates a medVol
= medicalVolume(sourceTable
,rowname
)medicalVolume
object for the image volume listed in the row
rowname
of sourceTable
. Use this syntax to
specify one row of a multirow table by name or by numeric index.
creates a medVol
= medicalVolume(imds
)medicalVolume
object for the image volume specified by the
image datastore object imds
.
creates a medVol
= medicalVolume(voxels
,VolumeGeometry
)medicalVolume
by directly specifying the Voxels and
VolumeGeometry properties.
Input Arguments
dirname
— Name of directory containing medical image volume data
string scalar | character vector
Name of the directory containing the medical image volume data, specified as a
string scalar or a character vector. Specify dirname
as the name
of a directory containing multiple DICOM files corresponding to one image
volume.
filenames
— Name of file or files containing medical image volume data
string scalar | character vector | string array
Name of the file or files containing the medical image volume data, specified as a
string scalar, character vector, or string array. Specify
filenames
as a single DICOM, NIfTI, or NRRD file or as a list
of DICOM files corresponding to one image volume.
sourceTable
— Collection of DICOM file metadata
table
Collection of DICOM file metadata, specified as a table returned by the dicomCollection
function.
rowname
— Name or index of table row
string scalar | character vector | positive integer
Name or index of table row, specified as a string scalar, character vector, or
positive integer. Specify rowname
as a string scalar or character
vector to specify a row of sourceTable
by name. Specify
rowname
as a positive integer to specify a row by its numeric
index.
imds
— Datastore specifying list of DICOM files containing medical image volume data
ImageDatastore
object
Datastore specifying a list of DICOM files containing medical image volume data,
specified as an ImageDataStore
object. The list of files must
correspond to one medical image volume.
Properties
Voxels
— Image voxel values
m-by-n-by-p numeric
array | N-D numeric array
Image voxel values, specified as an
m-by-n-by-p numeric array or
an N-D numeric array. The first three dimensions of
Voxels
correspond to the spatial dimensions of the patient
coordinate system.
For DICOM files, medicalVolume
rescales the intensity values using
the RescaleIntercept
and RescaleSlope
metadata
attributes, if they are present in the file. Additionally,
medicalVolume
converts DICOM intensities of data type
uint16
to data type int16
or
single
.
If the
RescaleSlope
attribute value is unspecified or an integer, thenmedicalVolume
converts the intensity values fromuint16
toint16
.If the
RescaleSlope
attribute value is fractional, thenmedicalVolume
converts the intensity values fromuint16
tosingle
.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| logical
VolumeGeometry
— Spatial referencing information
medicalref3d
object
Spatial referencing information, specified as a medicalref3d
object. The coordinates and distances specified by VolumeGeometry
are in the units specified by the SpatialUnits
property, if
available in the file
metadata.
SpatialUnits
— Real-world spatial units
"unknown"
(default) | string scalar
Real-world spatial units, specified as a string scalar or a character vector. If the
data source is a DICOM file, then the SpatialUnits
value is
"mm"
(millimeters). If the data source is a NIfTI or NRRD file, the
object extracts the spatial units from the SpaceUnits
or
spaceunits
metadata attribute, respectively, if present in the
file.
Data Types: string
VoxelSpacing
— Distances between voxel centers in each dimension
1-by-3 numeric vector
This property is read-only.
Distances between voxel centers in each dimension, specified as a 1-by-3 numeric
vector. The values of VoxelSpacing
are in the units specified by
the SpatialUnits
property. If
VolumeGeometry.IsAffine
is false
, then the
object calculates the spacing for each dimension as the average spacing across all
slices.
Data Types: double
Orientation
— Slice plane with greatest spatial resolution
"coronal"
| "mixed"
| "oblique"
| "sagittal"
| "tranverse"
| "unknown"
This property is read-only.
Slice plane with the greatest spatial resolution, specified as one of these values:
"coronal"
— Coronal plane."sagittal"
— Sagittal plane."transverse"
— Transverse plane."mixed"
— Image volume slices are not parallel. This value occurs when theIsMixed
property of theVolumeGeometry
object istrue
."oblique"
— Image slices are not aligned with the anatomical axes."unknown"
— Mapping between image coordinate system and anatomical axes is unknown. This value occurs when thePatientCoordinateSystem
property of theVolumeGeometry
object is"unknown"
.
Data Types: string
NumCoronalSlices
— Number of slices in coronal direction
numeric scalar | []
This property is read-only.
Number of slices in the coronal direction, specified as a numeric scalar or empty
array. NumCoronalSlices
is empty in these cases:
PatientCoordinateSystem
property of theVolumeGeometry
object is"unknown"
.Image volume is oblique.
Image volume contains a temporal dimension with multiple slices at each spatial location.
Data Types: double
NumSagittalSlices
— Number of slices in sagittal direction
numeric scalar | []
This property is read-only.
Number of slices in the sagittal direction, specified as a numeric scalar or empty
array. NumSagittalSlices
is empty in these cases:
PatientCoordinateSystem
property of theVolumeGeometry
object is"unknown"
.Image volume is oblique.
Image volume contains a temporal dimension with multiple slices at each spatial location.
Data Types: double
NumTransverseSlices
— Number of slices in transverse direction
numeric scalar | []
This property is read-only.
Number of slices in the transverse direction, specified as a numeric scalar or empty
array. NumTransverseSlices
is empty in these cases:
PatientCoordinateSystem
property of theVolumeGeometry
object is"unknown"
.Image volume is oblique.
Image volume contains a temporal dimension with multiple slices at each spatial location.
Data Types: double
PlaneMapping
— Mapping between image data dimensions and anatomical planes
1-by-3 string array
This property is read-only.
Mapping between image data dimensions and anatomical planes, specified as a 1-by-3
string array. If the spatial referencing information is available in the source file,
PlaneMapping
contains the strings
"transverse"
, "coronal"
, and
"sagittal"
. For example, if the first element of
PlaneMapping
is "coronal"
, then moving along
the first dimension of Voxels
corresponds to moving between slices
in the coronal plane.
If the PatientCoordinateSystem
property of the
VolumeGeometry
object is "unknown"
, or if the
volume is oblique, the values of PlaneMapping
are
"unknown"
or "oblique"
, respectively.
Example:
["transverse","coronal","sagittal"]
Data Types: string
NormalVector
— Unit vector normal to first slice of image volume
1-by-3 numeric vector
This property is read-only.
Unit vector normal to the first slice of the image volume, specified as a 1-by-3
numeric vector. The first slice of the volume corresponds to the points stored in
Voxels
(:,:,1)
.
Data Types: double
Modality
— Imaging modality used to capture image volume data
"unknown"
(default) | string scalar
This property is read-only.
Imaging modality used to capture the image volume data, specified as a string
scalar. The modality is extracted from the file metadata, if present. Common values
include, but are not limited to, "CT"
for computed tomography,
"MR"
for magnetic resonance, "NM"
for nuclear
medicine, and "US"
for ultrasound. If the modality is not specified
in the file metadata, the default value is "unknown"
.
Data Types: string
WindowCenters
— Center of display range window of each slice
[]
(default) | p-by-1 numeric vector
This property is read-only.
Center of the display range window for each slice, specified as a
p-by-1 numeric vector, where p is the number of
slices in the image volume along the third dimension. The object extracts the
WindowCenters
property value from the file metadata, if
available. If the display window metadata is not available, then
WindowCenters
is empty.
Data Types: double
WindowWidths
— Width of display window of each slice
[]
(default) | p-by-1 numeric vector
This property is read-only.
Width of display window of each slice, specified as a p-by-1
numeric vector, where p is the number of slices in the image volume
along the third dimension. The object extracts the WindowWidths
property value from the file metadata, if available. If the display window metadata is
not available, then WindowWidths
is empty.
Data Types: double
Object Functions
extractSlice | Extract voxels and spatial details for one slice of medical volume |
replaceSlice | Replace voxel values for one slice of medical volume |
resample | Resample medical image volume in different patient coordinate system |
sliceCorners | Extract coordinates of corner voxels for one slice of medical volume |
sliceLimits | Extract X-, Y-, Z-limits for one slice of medical volume |
volshow | Display medical volume in patient coordinates |
montage | Display medical image slices or frames as montage in patient coordinates |
write | Write affine medical volume data to NIfTI file |
Examples
Create Medical Volume Object for Multifile DICOM File
Create a medical volume object using 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. 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 for the CT volume.
medVol = medicalVolume(dataFolder)
medVol = medicalVolume with properties: Voxels: [512×512×88 int16] VolumeGeometry: [1×1 medicalref3d] SpatialUnits: "mm" Orientation: "transverse" VoxelSpacing: [0.7285 0.7285 2.5000] NormalVector: [0 0 1] NumCoronalSlices: 512 NumSagittalSlices: 512 NumTransverseSlices: 88 PlaneMapping: ["sagittal" "coronal" "transverse"] Modality: "CT" WindowCenters: [88×1 double] WindowWidths: [88×1 double]
Create Medical Volume Object from Filename
Create a medical volume object using a CT chest volume from the Medical Segmentation Decathlon data set [1]. Download the MedicalVolumNIfTIData.zip
file from the MathWorks website, then unzip the file. The file contains two CT chest volumes and corresponding label images, stored in the NIfTI file format. The size of the data file is approximately 76 MB.
zipFile = matlab.internal.examples.downloadSupportFile("medical","MedicalVolumeNIfTIData.zip"); filepath = fileparts(zipFile); unzip(zipFile,filepath) dataFolder = fullfile(filepath,"MedicalVolumeNIfTIData");
Specify the file name of the first CT volume.
filePath = fullfile(dataFolder,"lung_027.nii.gz");
Create a medical volume object for the CT volume.
medVol = medicalVolume(filePath)
medVol = medicalVolume with properties: Voxels: [512×512×264 single] VolumeGeometry: [1×1 medicalref3d] SpatialUnits: "mm" Orientation: "transverse" VoxelSpacing: [0.8594 0.8594 1.2453] NormalVector: [0 0 -1] NumCoronalSlices: 512 NumSagittalSlices: 512 NumTransverseSlices: 264 PlaneMapping: ["sagittal" "coronal" "transverse"] Modality: "unknown" WindowCenters: 0 WindowWidths: 0
[1] Medical Segmentation Decathlon. "Lung." Tasks. Accessed May 10, 2018. http://medicaldecathlon.com/.
The Medical Segmentation Decathlon data set is provided under the CC-BY-SA 4.0 license. All warranties and representations are disclaimed. See the license for details.
Create Medical Volume Object from DICOM Collection
Create a medical volume object using 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. 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");
Gather the details about the DICOM files in the dataFolder
directory into a table by using the dicomCollection
function. The files belong to one CT volume series, so the table has one row.
sourceTable = dicomCollection(dataFolder);
Create a medical volume object for the CT volume by specifying the single-row DICOM collection table.
medVol = medicalVolume(sourceTable)
medVol = medicalVolume with properties: Voxels: [512×512×88 int16] VolumeGeometry: [1×1 medicalref3d] SpatialUnits: "mm" Orientation: "transverse" VoxelSpacing: [0.7285 0.7285 2.5000] NormalVector: [0 0 1] NumCoronalSlices: 512 NumSagittalSlices: 512 NumTransverseSlices: 88 PlaneMapping: ["sagittal" "coronal" "transverse"] Modality: "CT" WindowCenters: [88×1 double] WindowWidths: [88×1 double]
Create Medical Volume Object from Specified Row of DICOM Collection
Create a medical volume object using a data set containing three chest CT scans. Each CT scan is saved as a directory of DICOM files. The size of the 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) dataFolder = fullfile(filepath,"MedicalVolumeDICOMData");
Gather the details about the DICOM files in the dataFolder
directory into a table by using the dicomCollection
function. The table contains three rows, each corresponding to one of three CT DICOM series.
sourceTable = dicomCollection(dataFolder);
Create a medical volume object for the second CT volume by specifying the DICOM collection table and a numeric row index.
medVol = medicalVolume(sourceTable,2)
medVol = medicalVolume with properties: Voxels: [512×512×88 int16] VolumeGeometry: [1×1 medicalref3d] SpatialUnits: "mm" Orientation: "transverse" VoxelSpacing: [0.7617 0.7617 2.5000] NormalVector: [0 0 1] NumCoronalSlices: 512 NumSagittalSlices: 512 NumTransverseSlices: 88 PlaneMapping: ["sagittal" "coronal" "transverse"] Modality: "CT" WindowCenters: [88×1 double] WindowWidths: [88×1 double]
Create Medical Volume Object from Image Datastore
Create a medical volume object using 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. 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 an image datastore containing the DICOM files in the dataFolder
directory. Specify a custom read function to read the DICOM files.
dicomds = imageDatastore(dataFolder, ... FileExtensions=".dcm",ReadFcn=@(x) dicomread(x));
Create a medical volume object for the CT volume.
medVol = medicalVolume(dicomds)
medVol = medicalVolume with properties: Voxels: [512×512×88 int16] VolumeGeometry: [1×1 medicalref3d] SpatialUnits: "mm" Orientation: "transverse" VoxelSpacing: [0.7285 0.7285 2.5000] NormalVector: [0 0 1] NumCoronalSlices: 512 NumSagittalSlices: 512 NumTransverseSlices: 88 PlaneMapping: ["sagittal" "coronal" "transverse"] Modality: "CT" WindowCenters: [88×1 double] WindowWidths: [88×1 double]
Create Medical Volume Object from Voxels and Spatial Details
Create a medical volume object using 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. 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 for the CT volume.
medVol = medicalVolume(dataFolder);
The Voxels
property contains the intensity values of each voxel. The VolumeGeometry
property contains a medicalref3d
object defining the spatial referencing for the image volume.
V = medVol.Voxels; R = medVol.VolumeGeometry;
Modify the voxel data by applying a 3-D Gaussian filter.
sigma = 2; filterV = imgaussfilt3(V,sigma);
Create a new medicalVolume
object that contains the smoothed voxel values. To maintain the same spatial referencing as the original volume, specify the original medicalref3d
object R
.
medVolFiltered = medicalVolume(filterV,R);
Display Medical Image Volume in Slice Viewer
Run this code to download a data set from the MathWorks® website and unzip the downloaded folder. The data set contains three CT volumes that are each saved as a directory of DICOM files. The size of the entire data set is approximately 81 MB.
zipFile = matlab.internal.examples.downloadSupportFile("medical","MedicalVolumeDICOMData.zip"); filepath = fileparts(zipFile); unzip(zipFile,filepath)
The folder dataFolder
contains the downloaded scan used by this example, LungCT01
.
dataFolder = fullfile(filepath,"MedicalVolumeDICOMData","LungCT01");
Create a medical image volume object that contains the image data and spatial referencing information for the CT volume. The Orientation
property indicates that the primary slice direction is "transverse"
.
medVol = medicalVolume(dataFolder)
medVol = medicalVolume with properties: Voxels: [512×512×88 int16] VolumeGeometry: [1×1 medicalref3d] SpatialUnits: "mm" Orientation: "transverse" VoxelSpacing: [0.7285 0.7285 2.5000] NormalVector: [0 0 1] NumCoronalSlices: 512 NumSagittalSlices: 512 NumTransverseSlices: 88 PlaneMapping: ["sagittal" "coronal" "transverse"] Modality: "CT" WindowCenters: [88×1 double] WindowWidths: [88×1 double]
View the transverse slices of the volume in the slice viewer. By default, the viewer uses the properties of medVol
to scale anisotropic voxels, set the intensity display range, and orient slices. The viewer opens on the center slice. Use the scroll bar to navigate to other slices.
sv = sliceViewer(medVol,Parent=figure)
sv = sliceViewer with properties: SliceDirection: [0 0 1] SliceNumber: 45 Parent: [1×1 Panel] Colormap: [256×3 double] DisplayRange: [-160 240] ScaleFactors: [1 1 1] DisplayRangeInteraction: 'on'
Create Medical Volume Object from Voxels
Since R2024a
Read the voxels of an MRI volume from a TIFF file using the tiffreadVolume
function.
voxels = tiffreadVolume("mri.tif");
Create a medicalref3d
object containing the volume geometry using only the volume size of the MRI volume.
volGeometry = medicalref3d(size(voxels))
volGeometry = medicalref3d with properties: VolumeSize: [128 128 27] Position: [27x3 double] VoxelDistances: {[1 0 0] [0 1 0] [0 0 1]} PatientCoordinateSystem: "Unknown" PixelSpacing: [1 1] IsAffine: 1 IsAxesAligned: 1 IsMixed: 0
Specify a patient coordinate system for visualization.
volGeometry.PatientCoordinateSystem = "LPS+";
Create a medicalVolume
object using the voxel data and the volume geometry.
medVol = medicalVolume(voxels,volGeometry)
medVol = medicalVolume with properties: Voxels: [128x128x27 uint8] VolumeGeometry: [1x1 medicalref3d] SpatialUnits: "unknown" Orientation: "transverse" VoxelSpacing: [1 1 1] NormalVector: [0 0 1] NumCoronalSlices: 128 NumSagittalSlices: 128 NumTransverseSlices: 27 PlaneMapping: ["sagittal" "coronal" "transverse"] Modality: "unknown" WindowCenters: [] WindowWidths: []
Visualize a slice of the medical volume.
slice = extractSlice(medVol,15,"transverse");
figure
imshow(slice)
Version History
Introduced in R2022bR2023a: The medicalVolume
object converts DICOM intensities from unsigned to signed values
When reading DICOM files, the medicalVolume
object converts intensity
values of data type uint16
to data type int16
or
single
. If the DICOM file specifies the
RescaleIntercept
and RescaleSlope
metadata
attributes, medicalVolume
converts the values before rescaling them. By
converting unsigned uint16
values to signed values before rescaling, the
new behavior preserves the full data range of the rescaled intensities, including negative values.
If the
RescaleSlope
attribute value is unspecified or an integer, thenmedicalVolume
converts the intensities fromuint16
toint16
.If the
RescaleSlope
attribute value is fractional, thenmedicalVolume
converts the intensities fromuint16
tosingle
.
In R2022b, medicalVolume
stored intensity values as the same
data type as in the DICOM file. For DICOM files that stored intensities as data type
uint16
, medicalVolume
limited rescaled values to the
range [0, 216-1], and set all negative intensities to
0
before storing them in the Voxels
property.
See Also
Comando de MATLAB
Ha hecho clic en un enlace que corresponde a este comando de MATLAB:
Ejecute el comando introduciéndolo en la ventana de comandos de MATLAB. Los navegadores web no admiten comandos de MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)