updateAttribute

Update value of specified DICOM attribute

Since R2023b

Syntax

dFileNew = updateAttribute(dFile,attributeName,updateValue)

dFileNew = updateAttribute(dFile,group,element,updateValue)

dFileNew = updateAttribute(dFile,attributeInfo)

dFileNew = updateAttribute(dFile,info)

Description

dFileNew = updateAttribute(dFile,attributeName,updateValue) updates the top-level attribute attributeName in the DICOM file specified by the dicomFile object dFile with the value updateValue.

dFileNew = updateAttribute(dFile,group,element,updateValue) specifies the top-level attribute to update as a DICOM group number group and element number element.

dFileNew = updateAttribute(dFile,attributeInfo) specifies the attributes to update and their new values as a table attributeInfo. The attributeInfo table can contain a location and new value for any attribute, including nested attributes.

dFileNew = updateAttribute(dFile,info) specifies the top-level attributes to update and their new values as a structure info.

Examples

Update Attributes of DICOM File

Import a DICOM file into the workspace.

dFile = dicomFile("rtstruct.dcm");

Find the locations and current values of all instances of the ROINumber attribute nested in the metadata of the DICOM file.

roiNumber = findAttribute(dFile,"ROINumber")

roiNumber=2×2 table
                     Location                     Value
    __________________________________________    _____

    "StructureSetROISequence.Item_1.ROINumber"    {[1]}
    "StructureSetROISequence.Item_2.ROINumber"    {[2]}

Update the value of the second instance of the ROINumber attribute in the table roiNumber.

roiNumber.Value{2} = 4

roiNumber=2×2 table
                     Location                     Value
    __________________________________________    _____

    "StructureSetROISequence.Item_1.ROINumber"    {[1]}
    "StructureSetROISequence.Item_2.ROINumber"    {[4]}

Update the dicomFile object with the new values for the ROINumber attribute.

dFile = updateAttribute(dFile,roiNumber);

Check whether the attribute has been updated in the dicomFile object.

roiNumber = findAttribute(dFile,"ROINumber")

roiNumber=2×2 table
                     Location                     Value
    __________________________________________    _____

    "StructureSetROISequence.Item_1.ROINumber"    {[1]}
    "StructureSetROISequence.Item_2.ROINumber"    {[4]}

Find the location and current value of the Modality attribute of the DICOM file.

modality = findAttribute(dFile,"Modality")

modality=1×2 table
     Location        Value    
    __________    ____________

    "Modality"    {'RTSTRUCT'}

Update the dicomFile object with a new value for the Modality attribute.

dFile = updateAttribute(dFile,"Modality",'rtstruct');

Check whether the attribute has been updated in the dicomFile object.

modality = findAttribute(dFile,"Modality")

modality=1×2 table
     Location        Value    
    __________    ____________

    "Modality"    {'rtstruct'}

Find the location and current value of the AcquisitionDateTime attribute of the DICOM file. The attribute does not exist in the DICOM file, so the function returns an empty table.

acquisitionDateTime = findAttribute(dFile,"AcquisitionDateTime")

acquisitionDateTime =

  0x2 empty table

    Location    Value
    ________    _____

Add the AcquisitionDateTime attribute to the dicomFile object using the decimal group and element numbers of the attribute.

dFile = updateAttribute(dFile,8,42,'2023-01-01 00:00:00');

Check whether the attribute exists in the updated dicomFile object.

acquisitionDateTime = findAttribute(dFile,"AcquisitionDateTime")

acquisitionDateTime=1×2 table
          Location                    Value         
    _____________________    _______________________

    "AcquisitionDateTime"    {'2023-01-01 00:00:00'}

Find the location and current value of the ImplementationVersionName attribute of the DICOM file.

implementationVersionName = findAttribute(dFile,"ImplementationVersionName")

implementationVersionName=1×2 table
             Location                    Value       
    ___________________________    __________________

    "ImplementationVersionName"    {'MATLAB IPT 9.4'}

Erase the value of ImplementationVersionName attribute in the dicomFile object using the structure info.

info = struct;
info.ImplementationVersionName = ''

info = struct with fields:
    ImplementationVersionName: ''

dFile = updateAttribute(dFile,info);

Check whether the attribute has been updated in the dicomFile object.

implementationVersionName = findAttribute(dFile,"ImplementationVersionName")

implementationVersionName=1×2 table
             Location                Value   
    ___________________________    __________

    "ImplementationVersionName"    {0x0 char}

Input Arguments

dFile — DICOM file

dicomFile object

DICOM file to update, 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

updateValue — New value of attribute

string scalar | character vector | numeric scalar | numeric vector | structure

New value of the attribute, specified as a string scalar, character vector, numeric scalar, numeric vector, or structure, depending upon the value representation (VR) of the specified DICOM attribute.

attributeInfo — Location and new value of attribute

table

Location and new value of the attribute, specified as a table with two columns, Location and Value. Each element of the Location column must use dot notation to provide the position of instance of the attribute within the nested DICOM metadata structure. Each element of the Value column is the new value to assign to the corresponding instance of the attribute within the DICOM metadata structure.

Data Types: table

info — New metadata of updated DICOM file

structure

New metadata of the updated DICOM file, specified as a structure. The name of each field of the structure must match the name of an attribute, and contain the new value of that attribute using the associated value representation.

Data Types: struct

Output Arguments

dFileNew — Updated DICOM file

dicomFile object

Updated DICOM file, returned as a dicomFile object.

Version History

Introduced in R2023b