Main Content

VolumeSource

Source of 3-D medical image data for groundTruthMedical object

Since R2022b

Description

A VolumeSource object defines the source of ground truth data for 3-D medical image volumes. Use this object to specify the volume data sources for a groundTruthMedical object. Each source must be a single DICOM, NIfTI, or NRRD file or multiple DICOM files comprising one 3-D volume.

Creation

When you export labels from a Medical Image Labeler app volume session, the DataSource property of the exported groundTruthMedical object contains a VolumeSource object.

To create a VolumeSource object programmatically, such as when programmatically creating a groundTruthMedical object, use the medical.labeler.loading.VolumeSource function.

Description

example

volSrc = medical.labeler.loading.VolumeSource(source) creates a VolumeSource object for loading the 3-D medical image data stored in the files or directory specified by source.

The data source for a VolumeSource object must be readable by a medicalVolume object and have a primary slice direction of "sagittal", "coronal", "transverse", or "oblique", which indicates that all slices are parallel. The Orientation property of the medicalVolume object specifies the primary slice direction. VolumeSource does not support volumes with a primary orientation that is "mixed" or "unknown".

VolumeSource does not support volumes with more than three dimensions.

example

volSource = medical.labeler.loading.VolumeSource(sourceTable) creates a VolumeSource object for loading the image data specified in a table, sourceTable, returned by the dicomCollection function.

Input Arguments

expand all

Source file names, specified as an n-by-1 cell array, where n is the total number of image volumes to store in the groundTruthMedical object.

Specify each element of source as one of these options:

  • Name of a single DICOM, NIfTI, or NRRD file defining one image volume, specified as a string scalar.

  • List of file names defining one multi-file DICOM image volume, specified as a string array.

  • Name of directory containing files defining one multi-file DICOM image volume, specified as a string scalar.

Data Types: cell

Table of source file names, specified as a table returned by the dicomCollection function. Each row in sourceTable must specify a valid DICOM series that contains a 3-D image volume readable by a medicalVolume object. The file name or list of file names for each DICOM series is stored in the Filenames column of the table returned by dicomCollection.

Data Types: table

Properties

expand all

This property is read-only.

Source of the ground truth data, specified as an n-by-1 cell array, where n is the total number of image volumes to store in the groundTruthMedical object. Each element contains the file path or file paths corresponding to one image volume, stored as a string scalar for single files or a string array for multi-file DICOM volumes.

Data Types: cell

Examples

collapse all

Create a volume data source using a subset of the Medical Segmentation Decathlon data set [1]. The subset of data includes two CT chest volumes and corresponding label images stored in the NIfTI file format. Download the MedicalVolumNIfTIData.zip file from the MathWorks® website, then unzip the file. 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");

Create a VolumeSource object specifying the two CT volumes.

filePath1 = fullfile(dataFolder,"lung_027.nii.gz");
filePath2 = fullfile(dataFolder,"lung_043.nii.gz");
source = {filePath1; filePath2};
dataSource = medical.labeler.loading.VolumeSource(source);

Verify that the filenames are stored in the Source property of the data source object.

dataSource.Source;

[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 a volume data source 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.

sourceTable = dicomCollection(dataFolder);

Create a volume data source specifying the files in sourceTable.

dataSource = medical.labeler.loading.VolumeSource(sourceTable);

Verify that each element of the Source property value contains a string array of filenames for one CT volume. The file names are extracted from the Filenames column of sourceTable.

dataSource.Source;

Version History

Introduced in R2022b