Aspose.Medical DICOM to Text Converter for .NET Knowledge Base
How to Customize DICOM JSON Output with DicomJsonSerializerOptions

How to Customize DICOM JSON Output with DicomJsonSerializerOptions

This tutorial demonstrates how to customize DICOM JSON serialization output using DicomJsonSerializerOptions in C#. Customization allows you to control JSON key formats, include additional metadata, and handle numeric values according to your integration requirements.

Why Customize JSON Output?

Different systems may require different JSON formats. Customization enables:

  • Using human-readable keywords instead of tag numbers
  • Including tag names for documentation
  • Controlling how numeric values are represented
  • Meeting specific third-party system requirements

Prerequisites: Preparing the Environment

  1. Set up Visual Studio or any compatible .NET IDE.
  2. Create a new .NET 8 console application project.
  3. Install Aspose.Medical from the NuGet Package Manager.

Available Serialization Options

OptionDescriptionImpact
UseKeywordsAsJsonKeysUse DICOM keywords instead of tag numbers as JSON keys"PatientName" vs "00100010"
WriteKeywordInclude keyword field in each tag objectAdds "keyword": "PatientName"
WriteNameInclude name field in each tag objectAdds "name": "Patient's Name"
NumberHandlingControl numeric value representationNumbers as strings or actual JSON numbers

Step-by-Step Guide to Customize JSON Output

Step 1: Install Aspose.Medical

Add the Aspose.Medical library to your project using NuGet.

Install-Package Aspose.Medical

Step 2: Include Necessary Namespaces

Add references to the required namespaces in your code.

using Aspose.Medical.Dicom;
using Aspose.Medical.Dicom.Serialization;
using System.Text.Json.Serialization;

Step 3: Create Options Instance

Create a DicomJsonSerializerOptions instance to configure settings.

DicomJsonSerializerOptions options = new DicomJsonSerializerOptions();

Step 4: Configure Options

Set the desired options for your JSON output.

options.UseKeywordsAsJsonKeys = true;
options.WriteKeyword = true;
options.WriteName = true;
options.NumberHandling = JsonNumberHandling.WriteAsString;

Step 5: Serialize with Options

Pass the options to the Serialize method.

DicomFile dcm = DicomFile.Open("patient_scan.dcm");
string json = DicomJsonSerializer.Serialize(dcm, options, writeIndented: true);

Step 6: Save the Customized Output

Save or use the customized JSON.

File.WriteAllText("customized_output.json", json);
Console.WriteLine("Customized JSON output saved!");

Complete Code Example with All Options

Here is a complete example showing all customization options:

using Aspose.Medical.Dicom;
using Aspose.Medical.Dicom.Serialization;
using System.Text.Json.Serialization;

// Load DICOM file
DicomFile dcm = DicomFile.Open("patient_scan.dcm");

// Configure serialization options
DicomJsonSerializerOptions options = new DicomJsonSerializerOptions
{
    UseKeywordsAsJsonKeys = true,
    WriteKeyword = true,
    WriteName = true,
    NumberHandling = JsonNumberHandling.WriteAsString
};

// Serialize with custom options
string json = DicomJsonSerializer.Serialize(dcm, options, writeIndented: true);

// Save output
File.WriteAllText("fully_customized.json", json);

Console.WriteLine("DICOM serialized with all custom options!");
Console.WriteLine(json);

Comparing Output Formats

Default Output (Standard PS3.18 Format) 

{
  "00100010": {
    "vr": "PN",
    "Value": [{ "Alphabetic": "DOE^JOHN" }]
  },
  "00100020": {
    "vr": "LO",
    "Value": ["12345"]
  }
}

With UseKeywordsAsJsonKeys = true 

{
  "PatientName": {
    "vr": "PN",
    "Value": [{ "Alphabetic": "DOE^JOHN" }]
  },
  "PatientID": {
    "vr": "LO",
    "Value": ["12345"]
  }
}

With WriteKeyword and WriteName = true 

{
  "00100010": {
    "vr": "PN",
    "keyword": "PatientName",
    "name": "Patient's Name",
    "Value": [{ "Alphabetic": "DOE^JOHN" }]
  }
}

With NumberHandling = WriteAsString 

{
  "00280010": {
    "vr": "US",
    "Value": ["512"]
  }
}

With NumberHandling = AllowReadingFromString | WriteAsNumber 

{
  "00280010": {
    "vr": "US",
    "Value": [512]
  }
}

Use Case Examples

For Human-Readable Documentation 

DicomJsonSerializerOptions docOptions = new DicomJsonSerializerOptions
{
    UseKeywordsAsJsonKeys = true,
    WriteKeyword = true,
    WriteName = true
};

string documentationJson = DicomJsonSerializer.Serialize(dcm, docOptions, writeIndented: true);

For PS3.18 Compliant Web Services 

// Use default options for DICOM PS3.18 compliance
DicomJsonSerializerOptions webOptions = new DicomJsonSerializerOptions
{
    UseKeywordsAsJsonKeys = false,  // Use tag numbers
    WriteKeyword = false,
    WriteName = false,
    NumberHandling = JsonNumberHandling.WriteAsString
};

string ps318Json = DicomJsonSerializer.Serialize(dcm, webOptions);

For JavaScript Frontend Integration 

DicomJsonSerializerOptions jsOptions = new DicomJsonSerializerOptions
{
    UseKeywordsAsJsonKeys = true,  // Easier to work with in JS
    NumberHandling = JsonNumberHandling.AllowReadingFromString  // Native numbers
};

string jsCompatibleJson = DicomJsonSerializer.Serialize(dcm, jsOptions);

For Database Storage 

DicomJsonSerializerOptions dbOptions = new DicomJsonSerializerOptions
{
    UseKeywordsAsJsonKeys = true,  // Better for querying
    WriteKeyword = false,          // Reduce storage size
    WriteName = false
};

string compactJson = DicomJsonSerializer.Serialize(dcm, dbOptions);

Important Considerations

Interoperability Warning

Non-standard options may break compatibility with some DICOM parsers:

// WARNING: This format may not be compatible with all DICOM JSON parsers
DicomJsonSerializerOptions nonStandardOptions = new DicomJsonSerializerOptions
{
    UseKeywordsAsJsonKeys = true  // Not PS3.18 compliant
};

// For maximum compatibility, use defaults:
DicomJsonSerializerOptions standardOptions = new DicomJsonSerializerOptions();

Recommendation for Compliance

When DICOM PS3.18 compliance is required, use default settings:

// PS3.18 compliant serialization
string compliantJson = DicomJsonSerializer.Serialize(dcm);  // No custom options

Stream-Based Serialization with Options

For large files, use stream-based serialization:

using Aspose.Medical.Dicom;
using Aspose.Medical.Dicom.Serialization;

DicomFile dcm = DicomFile.Open("large_scan.dcm");

DicomJsonSerializerOptions options = new DicomJsonSerializerOptions
{
    UseKeywordsAsJsonKeys = true,
    WriteKeyword = true
};

using (FileStream fs = File.Create("large_customized.json"))
{
    DicomJsonSerializer.Serialize(fs, dcm.Dataset, options, writeIndented: true);
}

Additional Information

  • Custom options affect both serialization and deserialization - ensure consistent options when round-tripping data.
  • The WriteName option adds human-readable DICOM tag names which increases JSON size but improves readability.
  • Some third-party systems may require specific JSON formats - consult their documentation before choosing options.

Conclusion

This tutorial has demonstrated how to customize DICOM JSON serialization output in C# using Aspose.Medical. By configuring DicomJsonSerializerOptions, you can tailor the JSON format to meet specific integration requirements while balancing readability, size, and interoperability needs.

 English