Main Content

dicomFile

Process DICOM file

Since R2023a

expand all in page

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.

example

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

expand all

This property is read-only.

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

Data Types: char | string

This property is read-only.

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

Data Types: string

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 attribute of the DICOM file, stored as a character vector.

Data Types: string | char

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

Data Types: string | char

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

Data Types: string | char

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

Data Types: string | char

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

Data Types: string | char

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

Data Types: uint8

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

Data Types: string | char

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

Data Types: string | char

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

Data Types: string | char

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

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

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

Data Types: string | char

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Object Functions

isAttributeCheck if specified attribute is present in DICOM file
getAttributeGet value of specified top level DICOM attribute
findAttributeFind location and value of specified DICOM attribute
updateAttributeUpdate value of specified DICOM attribute
getPixelDataGet pixel data of DICOM file
writeCreate selectively modified copy of DICOM file

Examples

collapse all

Open Live Script

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)

Figure Movie Player contains an axes object and other objects of type uiflowcontainer, uimenu, uitoolbar. The hidden axes object contains an object of type image.

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)

Figure Movie Player contains an axes object and other objects of type uiflowcontainer, uimenu, uitoolbar. The hidden axes object contains an object of type image.

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)

Figure Movie Player contains an axes object and other objects of type uiflowcontainer, uimenu, uitoolbar. The hidden axes object contains an object of type image.

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

expand all

See Also

| | | | |

Topics

External Websites