Main Content

updateAttribute

Update value of specified DICOM attribute

Since R2023b

collapse all in page

    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.

    example

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

    example

    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.

    example

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

    example

    Examples

    collapse all

    Open Live Script

    Import a DICOM file into the workspace.

    dFile = dicomFile("RTSTRUCT-VS-SEG-001.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=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]}

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

    roiNumber.Value{2} = 4
    roiNumber=4×2 table
                     Location                     Value
    __________________________________________    _____

    "StructureSetROISequence.Item_1.ROINumber"    {[1]}
    "StructureSetROISequence.Item_2.ROINumber"    {[4]}
    "StructureSetROISequence.Item_3.ROINumber"    {[3]}
    "StructureSetROISequence.Item_4.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=4×2 table
                     Location                     Value
    __________________________________________    _____

    "StructureSetROISequence.Item_1.ROINumber"    {[1]}
    "StructureSetROISequence.Item_2.ROINumber"    {[4]}
    "StructureSetROISequence.Item_3.ROINumber"    {[3]}
    "StructureSetROISequence.Item_4.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",'RTSTRUCTURE');

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

    modality = findAttribute(dFile,"Modality")
    modality=1×2 table
     Location          Value     
    __________    _______________

    "Modality"    {'RTSTRUCTURE'}

    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');

    Check whether the attribute exists in the updated dicomFile object.

    acquisitionDateTime = findAttribute(dFile,"AcquisitionDateTime")
    acquisitionDateTime=1×2 table
          Location               Value     
    _____________________    ______________

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

    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"    {'0.5'}

    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

    collapse all

    DICOM file to update, specified as a dicomFile object.

    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 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 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

    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.

    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

    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

    collapse all

    Updated DICOM file, returned as a dicomFile object.

    Version History

    Introduced in R2023b

    See Also

    | | | | | |

    External Websites