Aspose.Medical DICOM to Text Converter for .NET

Aspose.Medical DICOM to Text Converter for .NET is a powerful API focused on converting DICOM data to human-readable and machine-parsable formats. It serializes DICOM datasets to JSON and XML formats, enabling integration with web services, REST APIs, and modern healthcare systems. Built for interoperability, it provides standards-compliant serialization following DICOM Web Services (PS3.18) specifications.

Installation and Setup

1. Install the NuGet package Aspose.Medical (core API powering conversion).
2. Apply metered licensing at startup to avoid evaluation limits: see Metered Licensing .
3. Review framework requirements in the Installation Guide .

Supported Platforms

• OS: Windows, Linux, macOS
• Frameworks: .NET 8.0+
• Architectures: x64, ARM64 (macOS)

Quick Start

1) DICOM to JSON

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

DicomFile dcm = DicomFile.Open("patient_scan.dcm");
string json = DicomJsonSerializer.Serialize(dcm);

2) DICOM to JSON with Pretty Print

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

DicomFile dcm = DicomFile.Open("patient_scan.dcm");
string formattedJson = DicomJsonSerializer.Serialize(dcm, writeIndented: true);
Console.WriteLine(formattedJson);

3) DICOM Dataset to JSON

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

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

4) Multiple DICOM Files to JSON Array

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

DicomFile dcm1 = DicomFile.Open("scan1.dcm");
DicomFile dcm2 = DicomFile.Open("scan2.dcm");
Dataset[] datasets = [dcm1.Dataset, dcm2.Dataset];
string json = DicomJsonSerializer.Serialize(datasets, writeIndented: true);

5) Serialize to Stream (Memory Efficient)

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

DicomFile dcm = DicomFile.Open("patient_scan.dcm");
using MemoryStream stream = new();
DicomJsonSerializer.Serialize(stream, dcm.Dataset);

6) Save as JSON File

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

DicomFile dcm = DicomFile.Open("patient_scan.dcm");
using FileStream output = File.Create("output.json");
DicomJsonSerializer.Serialize(output, dcm.Dataset, writeIndented: true);

JSON Deserialization

Deserialize JSON String to Dataset

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

string jsonText = File.ReadAllText("dicom_data.json");
Dataset? dataset = DicomJsonSerializer.Deserialize(jsonText);

Deserialize JSON Stream to Dataset

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

using FileStream stream = File.OpenRead("dicom_data.json");
Dataset? dataset = DicomJsonSerializer.Deserialize(stream);

Deserialize JSON to DicomFile

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

string jsonText = File.ReadAllText("dicom_file.json");
DicomFile? dicomFile = DicomJsonSerializer.DeserializeFile(jsonText);

Deserialize JSON Array to Multiple Datasets

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

string jsonText = File.ReadAllText("dicom_array.json");
Dataset[]? datasets = DicomJsonSerializer.DeserializeList(jsonText);

XML Serialization

DICOM to XML

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

DicomFile dcm = DicomFile.Open("patient_scan.dcm");
string xml = DicomXmlSerializer.Serialize(dcm.Dataset);

XML to DICOM Dataset

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

string xmlText = File.ReadAllText("dicom_data.xml");
Dataset? dataset = DicomXmlSerializer.Deserialize(xmlText);

Async API

For asynchronous operations in web applications and services:

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

// Async deserialization from stream
using FileStream stream = File.OpenRead("dicom_data.json");
Dataset? dataset = await DicomJsonSerializer.DeserializeAsync(stream);

// Async serialization to stream
using FileStream output = File.Create("output.json");
await DicomJsonSerializer.SerializeAsync(output, dataset);

Available Async Methods:

• DeserializeAsync - Deserialize UTF-8 JSON stream to Dataset
• DeserializeFileAsync - Deserialize UTF-8 JSON stream to DicomFile
• DeserializeListAsync - Deserialize UTF-8 JSON stream to Dataset array
• SerializeAsync - Serialize Dataset, DicomFile, or Dataset array to UTF-8 JSON stream

Features and Functionality

DICOM Web Services Compliance

The converter adheres to DICOM PS3.18 (Web Services) standard, ensuring compatibility with:

• RESTful DICOM web APIs
• Cloud-based PACS systems
• Modern healthcare interoperability platforms
• FHIR-compatible systems

Serialization Options

Customize serialization behavior with DicomJsonSerializerOptions:

DicomJsonSerializerOptions options = new()
{
    UseKeywordsAsJsonKeys = false,  // Use tags instead of keywords
    WriteKeyword = true,            // Include keyword as separate attribute
    WriteName = true,               // Include tag name as separate attribute
    NumberHandling = JsonNumberHandling.AsNumber  // Number format
};

string json = DicomJsonSerializer.Serialize(dataset, options);

System.Text.Json Integration

Use converters with standard .NET JSON serialization:

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

JsonSerializerOptions options = new();
options.Converters.Add(new DicomFileJsonConverter());
options.Converters.Add(new DatasetJsonConverter());

// Now use with JsonSerializer
string json = JsonSerializer.Serialize(dicomFile, options);

Supported Types

Data Preservation

The serialization accurately preserves:

• All DICOM tags and values
• Value Representations (VR)
• Nested sequences
• Private tags
• Bulk data references
• Special float values (NaN, Infinity)

Common Use Cases

• Web Viewers: Serve DICOM metadata to browser-based medical image viewers.
• REST APIs: Build healthcare APIs that exchange DICOM data in JSON format.
• Data Analytics: Export DICOM metadata for analysis in data processing pipelines.
• Integration: Connect legacy PACS with modern cloud-based healthcare platforms.
• Debugging: Create human-readable representations of DICOM data for troubleshooting.
• Archiving: Store DICOM metadata in document databases like MongoDB or Elasticsearch.

Best Practices

• License first: Initialize metered licensing before any conversion to avoid evaluation limitations.
• Use streams: For large files or web services, use stream-based methods for memory efficiency.
• Async operations: Use async methods in web applications to avoid blocking threads.
• Validate round-trips: Test serialization/deserialization cycles to ensure data integrity.
• Standard compliance: Use default options for DICOM PS3.18 compliance; non-standard options may break third-party parsers.
• UTF-8 encoding: Stream methods use UTF-8 encoding, ideal for web APIs and file operations.

Operation Summary

FAQ

Does it require third-party libraries? No. It is a standalone API using only .NET built-in JSON/XML support.

Is the JSON output DICOM Web Services compliant? Yes. The default output follows DICOM PS3.18 specifications.

Can I customize the JSON key format? Yes. Use DicomJsonSerializerOptions to control tag vs. keyword keys and additional attributes.

Are nested sequences preserved? Yes. The serializer maintains full DICOM structure including nested sequences.

How do I handle large DICOM files? Use stream-based methods (Serialize(stream, ...) and DeserializeAsync) for memory-efficient processing.

Is round-trip conversion lossless? Yes. Serialization preserves all DICOM data for accurate deserialization back to Dataset or DicomFile objects.