findAttribute

Find location and value of specified DICOM attribute

Since R2023b

Syntax

attributeInfo = findAttribute(dFile,attributeName)

attributeInfo = findAttribute(dFile,group,element)

Description

attributeInfo = findAttribute(dFile,attributeName) finds the location and value of the specified attribute attributeName from the DICOM file specified by the dicomFile object dFile. The table attributeInfo contains the locations and values of all instances of the attribute, including where it is a nested attribute.

attributeInfo = findAttribute(dFile,group,element) specifies the attribute to find as a DICOM group number group and element number element.

Examples

Find Nested Attribute of DICOM File

Import a DICOM file into the workspace.

dFile = dicomFile("RTSTRUCT-VS-SEG-001.dcm");

Find the values of the ROINumber attribute of the DICOM file. The file contains multiple instances of the ROINumber attribute nested in different higher level attributes.

roiNumber = findAttribute(dFile,"ROINumber")

roiNumber=4×2 table
                     Location                     Value
    __________________________________________    _____

    "StructureSetROISequence.Item_1.ROINumber"    {[1]}
    "StructureSetROISequence.Item_2.ROINumber"    {[2]}
    "StructureSetROISequence.Item_3.ROINumber"    {[3]}
    "StructureSetROISequence.Item_4.ROINumber"    {[4]}

Use the group and element numbers of the ROINumber attribute, in decimal form, to find its locations and values in the DICOM file.

roiNumber = findAttribute(dFile,12294,34)

roiNumber=4×2 table
                     Location                     Value
    __________________________________________    _____

    "StructureSetROISequence.Item_1.ROINumber"    {[1]}
    "StructureSetROISequence.Item_2.ROINumber"    {[2]}
    "StructureSetROISequence.Item_3.ROINumber"    {[3]}
    "StructureSetROISequence.Item_4.ROINumber"    {[4]}

Use the group and element numbers of the ROINumber attribute, in hexadecimal form, to find its locations and values in the DICOM file.

roiNumber = findAttribute(dFile,"3006","0022")

roiNumber=4×2 table
                     Location                     Value
    __________________________________________    _____

    "StructureSetROISequence.Item_1.ROINumber"    {[1]}
    "StructureSetROISequence.Item_2.ROINumber"    {[2]}
    "StructureSetROISequence.Item_3.ROINumber"    {[3]}
    "StructureSetROISequence.Item_4.ROINumber"    {[4]}

Input Arguments

dFile — DICOM file

dicomFile object

DICOM file from which to retrieve the attribute location and value, specified as a dicomFile object.

attributeName — Name of attribute

string scalar | character vector

Name of the attribute, specified as a string scalar or character vector. This argument is case sensitive and must exactly match the DICOM attribute name. For a list of attributes present in the DICOM file, check the AttributeNames property of the dicomFile object dFile.

Data Types: char | string

group — Group number of attribute

numeric scalar | string scalar | character vector

Group number of the attribute, specified as a numeric scalar, string scalar, or character vector. Use a numeric scalar to specify the group number as a decimal value, and a string scalar or character vector to specify the group number as a hexadecimal value. You can find the group number of an attribute by using the dicomlookup function. For more information on the group numbers of DICOM attributes, see Registry of DICOM Data Elements.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | char | string

element — Element number of attribute

numeric scalar | string scalar | character vector

Element number of the attribute, specified as a numeric scalar, string scalar, or character vector. Use a numeric scalar to specify the element number as a decimal value, and a string scalar or character vector to specify the element number as a hexadecimal value. You can find the element number of an attribute by using the dicomlookup function. For more information on the element numbers of DICOM attributes, see Registry of DICOM Data Elements.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | char | string

Output Arguments

attributeInfo — Location and value of DICOM attribute

table

Location and value of the DICOM attribute, returned as a table with two columns, Location and Value. Each element in the Location column uses dot notation to provide the position of that instance of the attribute within the nested DICOM metadata structure. Each element of the Value column is the assigned value for the corresponding instance of the attribute within the DICOM metadata structure.

Version History

Introduced in R2023b