Main Content

updateAttribute

Update value of specified DICOM attribute

Since R2023b

    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

    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