dicomFile

Process DICOM file

Since R2023a

Description

The dicomFile object and its object functions enable you to selectively read, parse, access, modify, and write the metadata of a DICOM file. You can also simultaneously access the pixel data of the DICOM file. Compared to the dicominfo and dicomwrite functions, which cannot parse and modify DICOM metadata selectively, the dicomread function, which can read only pixel data from a DICOM file, and the dicomfind and dicomupdate functions, which operate on the metadata returned by dicominfo, the flexibility and speed of the dicomFile object and its object functions makes it more efficient than these functions when processing a large number of DICOM files.

Creation

Syntax

dFile = dicomFile(filename)

dFile = dicomFile(filename,Dictionary=dict)

Description

dFile = dicomFile(filename) creates a dicomFile object for the DICOM file filename. You can use the object to read, parse, access, modify, and write the metadata and pixel data of the DICOM file. filename is the absolute or relative path to the DICOM file, and sets the Filename property.

dFile = dicomFile(filename,Dictionary=dict) specifies the DICOM data dictionary dict to use to parse the DICOM metadata. dict is the absolute or relative path to the DICOM data dictionary, and sets the Dictionary property.

Properties

Filename — Name of DICOM file

string scalar | character vector

This property is read-only.

Name of the DICOM file, specified as a string scalar or character vector.

Data Types: char | string

AttributeNames — List of DICOM file attribute names

vector of strings

This property is read-only.

List of DICOM file attribute names, stored as a vector of strings.

Data Types: string

Dictionary — Path of DICOM data dictionary

fullfile(matlabroot,"toolbox","images","iptformats","dicom-dict.txt") (default) | string scalar | character vector

This property is read-only.

Path of DICOM data dictionary, specified as a string scalar or character vector.

Data Types: char | string

DICOM Attribute Properties

Some of the dependent attributes of a DICOM file are properties of the dicomFile object that are updated automatically when you modify the pixel data. Other attributes of the DICOM file are not properties of the dicomFile object.

TransferSyntaxUID — TransferSyntaxUID attribute of DICOM file

string scalar | character vector

TransferSyntaxUID attribute of the DICOM file, stored as a character vector.

Data Types: string | char

Modality — Modality attribute of DICOM file

string scalar | character vector

Modality attribute of the DICOM file, stored as a character vector.

Data Types: string | char

MediaStorageSOPClassUID — MediaStorageSOPClassUID attribute of DICOM file

string scalar | character vector

MediaStorageSOPClassUID attribute of the DICOM file, stored as a character vector.

Data Types: string | char

SOPClassUID — SOPClassUID attribute of DICOM file

string scalar | character vector

SOPClassUID attribute of the DICOM file, stored as a character vector.

Data Types: string | char

SOPInstanceUID — SOPInstanceUID attribute of DICOM file

string scalar | character vector

SOPInstanceUID attribute of the DICOM file, stored as a character vector.

Data Types: string | char

FileMetaInformationVersion — FileMetaInformationVersion attribute of DICOM file

two-element numeric vector

FileMetaInformationVersion attribute of the DICOM file, stored as a two-element numeric vector.

Data Types: uint8

MediaStorageSOPInstanceUID — MediaStorageSOPInstanceUID attribute of DICOM file

string scalar | character vector

MediaStorageSOPInstanceUID attribute of the DICOM file, stored as a character vector.

Data Types: string | char

ImplementationClassUID — ImplementationClassUID attribute of DICOM file

string scalar | character vector

ImplementationClassUID attribute of the DICOM file, stored as a character vector.

Data Types: string | char

ImplementationVersionName — ImplementationVersionName attribute of DICOM file

string scalar | character vector

ImplementationVersionName attribute of the DICOM file, stored as a character vector.

Data Types: string | char

SamplesPerPixel — SamplesPerPixel attribute of DICOM file

numeric scalar

SamplesPerPixel attribute of the DICOM file, stored as a numeric scalar.

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

PhotometricInterpretation — PhotometricInterpretation attribute of DICOM file

string scalar | character vector

PhotometricInterpretation attribute of the DICOM file, stored as a character vector.

Data Types: string | char

Rows — Rows attribute of DICOM file

numeric scalar

Rows attribute of the DICOM file, stored as a numeric scalar.

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

Columns — Columns attribute of DICOM file

numeric scalar

Columns attribute of the DICOM file, stored as a numeric scalar.

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

BitsAllocated — BitsAllocated attribute of DICOM file

numeric scalar

BitsAllocated attribute of the DICOM file, stored as a numeric scalar.

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

BitsStored — BitsStored attribute of DICOM file

numeric scalar

BitsStored attribute of the DICOM file, stored as a numeric scalar.

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

HighBit — HighBit attribute of DICOM file

numeric scalar

HighBit attribute of the DICOM file, stored as a numeric scalar.

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

PixelRepresentation — PixelRepresentation attribute of DICOM file

numeric scalar

PixelRepresentation attribute of the DICOM file, stored as a numeric scalar.

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

SmallestImagePixelValue — SmallestImagePixelValue attribute of DICOM file

numeric scalar

SmallestImagePixelValue attribute of the DICOM file, stored as a numeric scalar.

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

LargestImagePixelValue — LargestImagePixelValue attribute of DICOM file

numeric scalar

LargestImagePixelValue attribute of the DICOM file, stored as a numeric scalar.

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

Object Functions

isAttribute	Check if specified attribute is present in DICOM file
getAttribute	Get value of specified top level DICOM attribute
findAttribute	Find location and value of specified DICOM attribute
updateAttribute	Update value of specified DICOM attribute
getPixelData	Get pixel data of DICOM file
write	Create selectively modified copy of DICOM file

Examples

Create Denoised Image DICOM File from Ultrasound DICOM File

Load and Inspect Ultrasound DICOM File

Import an ultrasound sequence DICOM file into the workspace.

dFile = dicomFile("heartUltrasoundSequenceVideo.dcm");

Get the pixel data of the ultrasound sequence. Visualize and inspect the pixel data.

pixelData = getPixelData(dFile);
figure
implay(pixelData)

Verify that the ultrasound sequence DICOM file has 600 rows and 800 columns.

getAttribute(dFile,"Rows")

ans = uint16

600

getAttribute(dFile,"Columns")

ans = uint16

800

Modify Pixel Data and Metadata of Ultrasound Sequence

Crop the pixel data to reduce its size.

cropPixelData = pixelData(51:end,51:end,:,:);

Find the locations and current values of the attributes RegionLocationMinX0 and RegionLocationMinY0, which specify the coordinates of the upper-left corner of the region of interest, of the ultrasound sequence DICOM file.

minX0 = findAttribute(dFile,"RegionLocationMinX0")

minX0=1×2 table
                            Location                            Value 
    ________________________________________________________    ______

    "SequenceOfUltrasoundRegions.Item_1.RegionLocationMinX0"    {[65]}

minY0 = findAttribute(dFile,"RegionLocationMinY0")

minY0=1×2 table
                            Location                            Value 
    ________________________________________________________    ______

    "SequenceOfUltrasoundRegions.Item_1.RegionLocationMinY0"    {[77]}

Because you have cropped the first 50 rows and columns from the pixel data, reduce the values in the Value columns of minX0 and minY0 by 50, respectively. Update the RegionLocationMinX0 and RegionLocationMinY0 attributes of the DICOM file with the new values of minX0 and minY0, respectively.

minX0.Value{1} = minX0.Value{1} - 50;
minY0.Value{1} = minY0.Value{1} - 50;
attributeInfo = [minX0 ; minY0]

attributeInfo=2×2 table
                            Location                            Value 
    ________________________________________________________    ______

    "SequenceOfUltrasoundRegions.Item_1.RegionLocationMinX0"    {[15]}
    "SequenceOfUltrasoundRegions.Item_1.RegionLocationMinY0"    {[27]}

dFile = updateAttribute(dFile,attributeInfo);

Check that the values of the attributes RegionLocationMinX0 and RegionLocationMinY0 have been updated.

minX0 = findAttribute(dFile,"RegionLocationMinX0")

minX0=1×2 table
                            Location                            Value 
    ________________________________________________________    ______

    "SequenceOfUltrasoundRegions.Item_1.RegionLocationMinX0"    {[15]}

minY0 = findAttribute(dFile,"RegionLocationMinY0")

minY0=1×2 table
                            Location                            Value 
    ________________________________________________________    ______

    "SequenceOfUltrasoundRegions.Item_1.RegionLocationMinY0"    {[27]}

Denoise the cropped pixel data using a speckle filter. For denoising, convert each frame to the HSV color space, denoise the value (V) channel of the frame, and then convert the denoised HSV image back to the RGB color space. Visualize and inspect the denoised pixel data.

[h,w,c,d] = size(cropPixelData);
denoisedPixelData = zeros(h,w,c,d);
for i = 1:d
    [H,S,V] = rgb2hsv(cropPixelData(:,:,:,i));
    denoisedV = specklefilt(V);
    denoisedPixelData(:,:,:,i) = hsv2rgb(H,S,denoisedV);
end
figure
implay(denoisedPixelData)

Check if StudyDescription is an attribute of the ultrasound sequence DICOM file.

isAttribute(dFile,"StudyDescription")

ans = logical
   1

Get the value of the StudyDescription attribute of the ultrasound sequence DICOM file.

studyDescription = getAttribute(dFile,"StudyDescription")

studyDescription = 
'ADULT ECHO TTE'

Create a study description for a new DICOM file, based on studyDescription. Then, create a structure named metadata with a StudyDescription field that contains your new study description.

denoisedStudyDescription = [studyDescription ' DENOISED'];
metadata = struct("StudyDescription",denoisedStudyDescription)

metadata = struct with fields:
    StudyDescription: 'ADULT ECHO TTE DENOISED'

Write Modified Pixel Data and Metadata to New DICOM File

Create a modified copy of the ultrasound sequence DICOM file, replacing its pixel data with the denoised pixel data and its metadata with the structure containing your new study description.

write(dFile,"heartUltrasoundSequenceVideo_denoised.dcm",denoisedPixelData,metadata)

Verify New DICOM File

To check whether the new DICOM file contains the denoised pixel data and the updated metadata, import it into the workspace.

dFileDenoised = dicomFile("heartUltrasoundSequenceVideo_denoised.dcm");

Get the study description, to verify that it matches your updated study description.

getAttribute(dFileDenoised,"StudyDescription")

ans = 
'ADULT ECHO TTE DENOISED'

Get the pixel data of the new DICOM file. Visualize the pixel data to verify that it matches the denoised pixel data of the ultrasound sequence.

pixelDataDenoised = getPixelData(dFileDenoised);
figure
implay(pixelDataDenoised)

Check that the rows and columns of the new DICOM file have automatically updated to reflect the size of the cropped image.

getAttribute(dFileDenoised,"Rows")

ans = uint16

550

getAttribute(dFileDenoised,"Columns")

ans = uint16

750

Limitations

Noncompliant DICOM files that switch value representation (VR) modes incorrectly cannot be read using the dicomFile object.

Version History

Introduced in R2023a

R2023b: Find and update attributes of DICOM files

Use the new object functions of the dicomFile object, findAttribute and updateAttribute, to find and update attributes, respectively, in the metadata of DICOM files.