DICOM Anonymization

DICOM Anonymization

Aspose.Medical.Dicom.Anonymization applies confidentiality rules to DICOM dataset attributes. Anonymize returns an anonymized copy; AnonymizeInPlace alters the supplied file or dataset. A default Anonymizer uses BasicProfile.

Attribute anonymization is one part of de-identification and does not by itself establish regulatory compliance. It does not detect identifying text burned into image pixels. Review pixel data and other identifying content for the intended sharing workflow, as described in DICOM PS3.15 Annex E. Evaluation mode retains Patient Name and Patient ID; apply the appropriate license before relying on their anonymization.

Anonymizing a DICOM File (Basic Usage)

You can anonymize DICOM files in a few simple steps. The Aspose.Medical.Dicom.Anonymization.Anonymizer.Anonymize method removes or redacts sensitive patient and study information while preserving the structure of the DICOM dataset. To anonymize a DICOM file, please follow the steps below:

  1. Load an existing DICOM file using DicomFile.Open.
  2. Create an anonymizer instance (Aspose.Medical.Dicom.Anonymization.Anonymizer) with default settings.
  3. Use anonymizer.Anonymize(dicomFile) to remove sensitive attributes.
  4. Save the anonymized file for further use.
// Load a DICOM file
Aspose.Medical.Dicom.DicomFile dicomFile = DicomFile.Open("input.dcm");

// Create an anonymizer with the default profile
Aspose.Medical.Dicom.Anonymization.Anonymizer anonymizer = new();

// Anonymize the DICOM file
Aspose.Medical.Dicom.DicomFile anonymizedFile = anonymizer.Anonymize(dicomFile);

// Save the anonymized file
anonymizedFile.Save("anonymized_output.dcm");

Anonymization Profiles

Anonymization profiles allow customized redaction of DICOM metadata based on predefined rules. Profiles define how specific metadata fields should be handled. A confidentiality profile helps control what information gets anonymized or retained. The library supports loading profiles from various formats (CSV, JSON, XML).

To anonymize a DICOM file using a predefined specific Confidential Profile, please follow the steps below:

  1. Create a profile with ConfidentialityProfile.CreateDefault, selecting BasicProfile and the required options.
  2. Create an anonymizer instance (Aspose.Medical.Dicom.Anonymization.Anonymizer) with these options.
  3. Use anonymizer.Anonymize(dicomFile) to remove sensitive attributes.
  4. Save the anonymized file for further use.
// Create a default confidentiality profile with basic anonymization rules
Aspose.Medical.Dicom.Anonymization.ConfidentialityProfile profile =
    ConfidentialityProfile.CreateDefault(
        ConfidentialityProfileOptions.BasicProfile |
        ConfidentialityProfileOptions.CleanGraph);

// Create anonymizer using this profile
Aspose.Medical.Dicom.Anonymization.Anonymizer anonymizer = new(profile);

// Load a DICOM dataset
Aspose.Medical.Dicom.DicomFile dicomFile = DicomFile.Open("input.dcm");

// Anonymize the dataset using the profile
Aspose.Medical.Dicom.DicomFile anonymizedFile = anonymizer.Anonymize(dicomFile);

// Save result
anonymizedFile.Save("anonymized_output.dcm");

Confidentiality profile options are described in DICOM PS3.15 Table E.1-1. The relation between Aspose.Medical profiles and the ones defined in DICOM PS3.15:

  • BasicProfile - Basic Profile. XML/JSON column name is basic_profile.
  • RetainSafePrivate - Retain Safe Private Option Profile. XML/JSON column name is rtn_safe_priv_opt.
  • RetainUIDs - Retain UIDs Option Profile. XML/JSON column name is rtn_uids_opt.
  • RetainDeviceIdent - Retain Device Ident Option Profile. XML/JSON column name is rtn_dev_id_opt.
  • RetainInstitutionIdent - Retain Institution Ident Option Profile. XML/JSON column name is rtn_inst_id_opt.
  • RetainPatientChars - Retain Patient Chars Option Profile. XML/JSON column name is rtn_pat_chars_opt.
  • RetainLongFullDates - Retain Long Full Dates Option Profile. XML/JSON column name is rtn_long_full_dates_opt.
  • RetainLongModifDates - Retain Long Modif Dates Option Profile. XML/JSON column name is rtn_long_modif_dates_opt.
  • CleanDesc - Clean Desc Option Profile. XML/JSON column name is clean_desc_opt.
  • CleanStructdCont - Clean Structd Cont Option Profile. XML/JSON column name is clean_struct_cont_opt.
  • CleanGraph - Clean Graph Option Profile. XML/JSON column name is clean_graph_opt.

All selects all listed options; it is not a synonym for maximum removal. Select only the options required by the workflow. CreateDefault combines the selected rule sets. When multiple action flags apply to one rule, the current API selects the first in D, Z, X, K, C, U order rather than evaluating IOD-specific alternatives.

Confidentiality actions determine how sensitive data is processed.

  • D - Replace the value with a value compatible with its VR, such as a dummy value.
  • Z - Replace the value with an empty or blank value compatible with its VR.
  • X - Remove the attribute.
  • K - Keep a non-sequence attribute; apply the profile recursively to retained sequence items.
  • C - Clean the value. The current implementation uses the same VR-based replacement as D; it does not preserve the meaning of free text.
  • U - Replace a UID consistently. Reuse the same Anonymizer instance for related files so that repeated source UIDs receive the same replacement.

Custom Anonymization Profiles

Custom profiles can be loaded from JSON, XML, or CSV files. These loaders return only the rules in the supplied document; they do not automatically add the default profile. The small samples below demonstrate the format and are not complete de-identification profiles. Tag patterns are regular expressions matched against hexadecimal group,element text.

Loading Custom Profiles from CSV

A CSV file can define anonymization rules for specific DICOM tags.

CSV Structure Example:

0010,0010;Z;;;;;;;;;;
0010,0020;X;;;;;;;;;;
0020,000D;U;;;;;;;;;;

CSV input has no header row. The first column is the tag pattern, followed by eleven action columns in ConfidentialityProfileOptions order: BasicProfile, RetainSafePrivate, RetainUIDs, and the remaining options listed above. This sample fills BasicProfile and leaves ten option columns empty. Keep the trailing separators: the loader detects the delimiter from the first row, and a single semicolon can otherwise be confused with the comma in a tag pattern.

// Load confidentiality profile from a CSV file
Aspose.Medical.Dicom.Anonymization.ConfidentialityProfile profile = ConfidentialityProfile.LoadFromCsvFile("profile.csv", ConfidentialityProfileOptions.BasicProfile);

// Create anonymizer with custom profile
Aspose.Medical.Dicom.Anonymization.Anonymizer anonymizer = new(profile);

Loading Custom Profiles from JSON

A JSON file can define anonymization rules for specific DICOM tags.

JSON Structure Example:

[
    { "tag": "0010,0010", "basic_profile": "Z" },
    { "tag": "0010,0020", "basic_profile": "X" },
    { "tag": "0020,000D", "basic_profile": "U" }
]

To load a profile from JSON file, please use the following code snippet:

// Load confidentiality profile from a JSON file
Aspose.Medical.Dicom.Anonymization.ConfidentialityProfile profile = ConfidentialityProfile.LoadFromJsonFile("profile.json", ConfidentialityProfileOptions.BasicProfile);

// Create anonymizer with custom profile
Aspose.Medical.Dicom.Anonymization.Anonymizer anonymizer = new(profile);

Loading Custom Profiles from XML

XML file can define anonymization rules for specific DICOM tags.

XML Structure Example:

<root>
  <item>
    <tag>0010,0010</tag>
    <basic_profile>Z</basic_profile>
  </item>
  <item>
    <tag>0010,0020</tag>
    <basic_profile>X</basic_profile>
  </item>
</root>

To load a profile from XML file, please use the following code snippet:

// Load confidentiality profile from an XML file
Aspose.Medical.Dicom.Anonymization.ConfidentialityProfile profile = ConfidentialityProfile.LoadFromXmlFile("profile.xml", ConfidentialityProfileOptions.BasicProfile);

// Create an anonymizer with the custom profile
Aspose.Medical.Dicom.Anonymization.Anonymizer anonymizer = new(profile);

Advanced Anonymization

Certain scenarios require more control over how sensitive data is altered. You can manually specify how sensitive information (like patient names and IDs) should be replaced. To anonymize a DICOM file using custom settings for PatientName and PatientID tags, please follow the steps below:

  1. Start with the default basic profile and set PatientName and PatientId replacements.
  2. Apply the profile to anonymize attributes and replace existing Patient Name and Patient ID values.
  3. Save the anonymized file for further use.
// Load a DICOM file
Aspose.Medical.Dicom.DicomFile dicomFile = DicomFile.Open("input.dcm");

// Create a confidentiality profile and set custom values
Aspose.Medical.Dicom.Anonymization.ConfidentialityProfile profile =
    ConfidentialityProfile.CreateDefault(
        ConfidentialityProfileOptions.BasicProfile);
profile.PatientName = "ANONYMOUS PATIENT";
profile.PatientId = "00000000";

// Create an anonymizer with this profile
Aspose.Medical.Dicom.Anonymization.Anonymizer anonymizer = new(profile);

// Anonymize the file
Aspose.Medical.Dicom.DicomFile anonymizedFile = anonymizer.Anonymize(dicomFile);

// Save the anonymized file
anonymizedFile.Save("custom_anonymized.dcm");

In-Place Anonymization

Instead of generating a new file, you may want to modify the DICOM file directly.To anonymize a DICOM file without generating a new file, please follow the steps below:

  1. Load an existing DICOM file using Aspose.Medical.Dicom.DicomFile.Open.
  2. Create an anonymizer instance (Aspose.Medical.Dicom.Anonymization.Anonymizer) with default settings.
  3. Use anonymizer.AnonymizeInPlace(dicomFile) to remove sensitive attributes.
  4. Save the anonymized file for further use.
// Load a DICOM file
Aspose.Medical.Dicom.DicomFile dicomFile = DicomFile.Open("input.dcm");

// Create anonymizer
Aspose.Medical.Dicom.Anonymization.Anonymizer anonymizer = new();

// Perform in-place anonymization
anonymizer.AnonymizeInPlace(dicomFile);

// Save the modified file
dicomFile.Save("inplace_anonymized.dcm");
Transcoding DICOM file DICOM Error Handling and Exceptions