dicomCollection

Gather details about related series of DICOM files

Syntax

collection = dicomCollection(directory)

collection = dicomCollection(filenames)

collection = dicomCollection(DICOMDIR)

collection = dicomCollection(___,Name=Value)

Description

collection = dicomCollection(directory) gathers details about the DICOM files contained in directory and returns the file details in the table collection. The dicomCollection function aggregates details by DICOM series, using the value of the SeriesInstanceUID metadata field in each file to determine series membership. A DICOM series is a logically related set of images from an imaging operation.

collection = dicomCollection(filenames) gathers details about the DICOM files with the specified filenames, filenames.

collection = dicomCollection(DICOMDIR) gathers details about the DICOM files referenced in the DICOM directory file DICOMDIR. A DICOM directory file (DICOMDIR) is a special DICOM file that serves as a directory to a collection of DICOM files stored on removable media, such as CD- or DVD-ROMs.

collection = dicomCollection(___,Name=Value) specifies one or more optional name-value arguments.

Examples

Gather Details from DICOM Files in Sample Image Folder

Gather information about the DICOM files in the Image Processing Toolbox™ sample image folder.

details = dicomCollection(fullfile(matlabroot,"toolbox/images/imdata"))

details=6×14 table
               StudyDateTime               SeriesDateTime           PatientName      PatientSex     Modality     Rows    Columns    Channels    Frames    StudyDescription    SeriesDescription                             StudyInstanceUID                                                     SeriesInstanceUID                                                      Filenames                         
          ________________________    ________________________    _______________    __________    __________    ____    _______    ________    ______    ________________    _________________    __________________________________________________________________    __________________________________________________________________    ___________________________________________________________

    s1    {0×0 double            }    {0×0 double            }    ""                    ""         "RTSTRUCT"      0         0         0           1      ""                  ""                   "1.2.826.0.1.3680043.8.274.1.1.2729954696.96242.3632970675.507"       "1.2.826.0.1.3680043.8.274.1.1.7145442384.75872.7982248107.258"       {["B:\matlab\toolbox\images\imdata\rtstruct.dcm"         ]}
    s2    {[30-Apr-1993 11:27:24]}    {[30-Apr-1993 11:27:24]}    "Anonymized"          ""         "CT"          512       512         1           1      "RT ANKLE"          ""                   "1.2.840.113619.2.1.1.322987881.621.736170080.681"                    "1.2.840.113619.2.1.2411.1031152382.365.736169244"                    {["B:\matlab\toolbox\images\imdata\CT-MONO2-16-ankle.dcm"]}
    s3    {[14-Dec-2013 15:47:31]}    {[14-Dec-2013 15:54:33]}    "GORBERG MITZI"       "F"        "MR"          512       512         1          22      "CSP"               "AX T2"              "1.2.840.113619.2.244.3596.11880862.13689.1386517653.214"             "1.2.840.113619.2.244.3596.11880862.13689.1386517653.217"             {22×1 string                                              }
    s4    {[03-Oct-2011 19:18:11]}    {[03-Oct-2011 18:59:02]}    ""                    "M"        "MR"          512       512         1           1      "RIGHT KNEE"        ""                   "1.3.6.1.4.1.9590.100.1.2.320418845013189618318250681693358291211"    "1.3.6.1.4.1.9590.100.1.2.287740981712351622214874344032214809569"    {["B:\matlab\toolbox\images\imdata\knee1.dcm"            ]}
    s5    {[03-Oct-2011 19:18:11]}    {[03-Oct-2011 19:05:04]}    ""                    "M"        "MR"          512       512         1           1      "RIGHT KNEE"        ""                   "1.3.6.1.4.1.9590.100.1.2.320498134711034521212730362051554545799"    "1.3.6.1.4.1.9590.100.1.2.316302984111738034326701385064023497963"    {["B:\matlab\toolbox\images\imdata\knee2.dcm"            ]}
    s6    {[30-Jan-1994 11:25:01]}    {0×0 double            }    "Anonymized"          ""         "US"          430       600         1          10      "Echocardiogram"    "PS LAX MR & AI"     "999.999.3859744"                                                     "999.999.94827453"                                                    {["B:\matlab\toolbox\images\imdata\US-PAL-8-10x-echo.dcm"]}

Gather Details About DICOM Files from DICOMDIR File

Gather information about DICOM files in a folder from a DICOMDIR file.

details = dicomCollection(fullfile(matlabroot,"toolbox/images/imdata/DICOMDIR"))

details=4×14 table
             StudyDateTime        SeriesDateTime    PatientName     PatientSex    Modality    Rows    Columns    Channels    Frames    StudyDescription    SeriesDescription    StudyInstanceUID                            SeriesInstanceUID                                                    Filenames                       
          ____________________    ______________    ____________    __________    ________    ____    _______    ________    ______    ________________    _________________    ________________    __________________________________________________________________    _______________________________________________________

    s1    30-Apr-1993 11:27:24      {0×0 char}      "Anonymized"        ""          "CT"      512       512         1           1      "RT ANKLE"                 ""                   ""           "1.2.840.113619.2.1.2411.1031152382.365.736169244"                    "B:\matlab\toolbox\images\imdata\CT-MONO2-16-ankle.dcm"
    s2    30-Jan-1994 11:25:01      {0×0 char}      "Anonymized"        ""          "US"      430       600         1          10      "Echocardiogram"           ""                   ""           "999.999.94827453"                                                    "B:\matlab\toolbox\images\imdata\US-PAL-8-10x-echo.dcm"
    s3    03-Oct-2011 19:18:11      {0×0 char}      ""                  ""          "MR"      512       512         1           1      "RIGHT KNEE"               ""                   ""           "1.3.6.1.4.1.9590.100.1.2.287740981712351622214874344032214809569"    "B:\matlab\toolbox\images\imdata\knee1.dcm"            
    s4    03-Oct-2011 19:18:11      {0×0 char}      ""                  ""          "MR"      512       512         1           1      "RIGHT KNEE"               ""                   ""           "1.3.6.1.4.1.9590.100.1.2.316302984111738034326701385064023497963"    "B:\matlab\toolbox\images\imdata\knee2.dcm"            

Input Arguments

directory — Folder containing DICOM files

string scalar | character vector

Name of a folder containing DICOM files, specified as a string scalar or character vector.

Example: details = dicomCollection(fullfile(matlabroot,"toolbox/images/imdata"))

Data Types: char | string

filenames — List of DICOM filenames

vector of strings

List of DICOM filenames, specified as a vector of strings specifying the names of files that make up one or more multi-file DICOM volumes.

Data Types: string

DICOMDIR — DICOM directory file

string scalar | character vector

DICOM directory file, specified as a string scalar or character vector.

A DICOM directory file (DICOMDIR) is a special DICOM file that serves as a directory to a collection of DICOM files stored on removable media, such as CD- or DVD-ROMs. When devices write DICOM files to removable media, they typically write a DICOMDIR file on the disk to serve as a list of the disk contents.

You can specify DICOMDIR using its absolute path, relative path, or location on the MATLAB^® path.

Example: details = dicomCollection(fullfile(matlabroot,"toolbox/images/imdata/DICOMDIR"))

Data Types: char | string

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: dicomCollection(directory,IncludeSubfolders=true) recursively searches for DICOM files below directory.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: dicomCollection(directory,"IncludeSubfolders",true) recursively searches for DICOM files below directory.

IncludeSubfolders — Include subfolders in search

true or 1 (default) | false or 0

Include subfolders in search, specified as a logical 1 (true) or 0 (false). When set to true, the dicomCollection function recursively searches for DICOM files below directory. When set to false, the dicomCollection function only includes files within directory in the search.

Data Types: logical

DisplayWaitbar — Display waitbar

true or 1 (default) | false or 0

Since R2025a

Display waitbar, specified as a logical 1 (true) or 0 (false). The function displays a waitbar when you specify DisplayWaitbar as true.

Data Types: logical

Output Arguments

collection — Metadata from DICOM files

table

Metadata from DICOM files, returned as a table. The dicomCollection function aggregates the information by DICOM series.

Extended Capabilities

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

The dicomCollection function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2017b

R2026a: Specify list of filenames

The function now accepts a list of DICOM filenames, specified as a vector of strings, as the input source.

R2025a: Enable or disable display of waitbar

Enable or disable display of waitbar using the DisplayWaitbar name-value argument.

R2024b: Support for thread-based environments

dicomCollection now supports thread-based environments.

R2022a: Improved performance

The performance of the dicomCollection function is improved. The function is about 30–50% faster than in the previous release.