Modern healthcare applications increasingly rely on web-based interfaces for viewing and managing medical imaging data. Converting DICOM files to JSON enables seamless integration with JavaScript frameworks, REST APIs, and cloud platforms. This guide shows you how to convert DICOM to JSON in C# using Aspose.Medical for .NET.

Why Convert DICOM to JSON?

DICOM (Digital Imaging and Communications in Medicine) is the standard format for medical imaging, but its binary structure makes it challenging to work with in web applications. JSON offers several advantages for web development:

  • JavaScript compatibility: JSON is native to web browsers and frontend frameworks like React, Vue, and Angular
  • REST API integration: JSON is the de facto standard for modern web APIs
  • Database storage: NoSQL databases like MongoDB store JSON documents natively
  • Human readability: JSON is easy to inspect and debug compared to binary DICOM

The DICOM PS3.18 standard defines a JSON representation for DICOM data, ensuring interoperability across healthcare systems.

Setting Up Your .NET Project

First, install Aspose.Medical for .NET and configure metered licensing:

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

// Activate metered license
Metered metered = new Metered();
metered.SetMeteredKey("your-public-key", "your-private-key");

Basic DICOM to JSON Conversion

The simplest way to convert a DICOM file to JSON:

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

public class DicomJsonConverter
{
    public string ConvertToJson(string dicomFilePath)
    {
        // Load the DICOM file
        DicomFile dicomFile = DicomFile.Open(dicomFilePath);
        
        // Serialize dataset to JSON string
        string json = DicomJsonSerializer.Serialize(dicomFile.Dataset);
        
        return json;
    }
}

Pretty-Print JSON for Debugging

During development, formatted JSON is easier to read and debug:

public string ConvertToFormattedJson(string dicomFilePath)
{
    DicomFile dicomFile = DicomFile.Open(dicomFilePath);
    
    // Configure serialization options
    var options = new DicomJsonSerializerOptions
    {
        WriteIndented = true  // Enable pretty-print
    };
    
    string json = DicomJsonSerializer.Serialize(dicomFile.Dataset, options);
    
    return json;
}

Using Tag Keywords Instead of Hex Codes

By default, DICOM JSON uses hexadecimal tag codes. For more readable output, use keyword names:

public string ConvertWithKeywords(string dicomFilePath)
{
    DicomFile dicomFile = DicomFile.Open(dicomFilePath);
    
    var options = new DicomJsonSerializerOptions
    {
        WriteIndented = true,
        UseKeywordsAsJsonKeys = true,  // Use "PatientName" instead of "00100010"
        WriteKeyword = true,           // Include keyword in output
        WriteName = true               // Include human-readable name
    };
    
    string json = DicomJsonSerializer.Serialize(dicomFile.Dataset, options);
    
    return json;
}

Building a REST API Endpoint

Here’s how to create an ASP.NET Core endpoint that converts uploaded DICOM files to JSON:

using Microsoft.AspNetCore.Mvc;
using Aspose.Medical.Dicom;
using Aspose.Medical.Dicom.Serialization;

[ApiController]
[Route("api/[controller]")]
public class DicomController : ControllerBase
{
    [HttpPost("to-json")]
    public async Task<IActionResult> ConvertToJson(IFormFile file)
    {
        if (file == null || file.Length == 0)
        {
            return BadRequest("No DICOM file provided");
        }

        try
        {
            // Save uploaded file temporarily
            var tempPath = Path.GetTempFileName();
            using (var stream = new FileStream(tempPath, FileMode.Create))
            {
                await file.CopyToAsync(stream);
            }

            // Convert to JSON
            DicomFile dicomFile = DicomFile.Open(tempPath);
            
            var options = new DicomJsonSerializerOptions
            {
                WriteIndented = true,
                UseKeywordsAsJsonKeys = true
            };
            
            string json = DicomJsonSerializer.Serialize(dicomFile.Dataset, options);

            // Clean up temp file
            System.IO.File.Delete(tempPath);

            return Content(json, "application/json");
        }
        catch (Exception ex)
        {
            return StatusCode(500, $"Conversion failed: {ex.Message}");
        }
    }
    
    [HttpGet("metadata/{fileName}")]
    public IActionResult GetMetadata(string fileName)
    {
        var filePath = Path.Combine("DicomFiles", fileName);
        
        if (!System.IO.File.Exists(filePath))
        {
            return NotFound("DICOM file not found");
        }

        DicomFile dicomFile = DicomFile.Open(filePath);
        
        // Extract specific metadata fields
        var metadata = new
        {
            PatientName = dicomFile.Dataset.GetString(DicomTag.PatientName),
            PatientID = dicomFile.Dataset.GetString(DicomTag.PatientID),
            StudyDate = dicomFile.Dataset.GetString(DicomTag.StudyDate),
            Modality = dicomFile.Dataset.GetString(DicomTag.Modality),
            StudyDescription = dicomFile.Dataset.GetString(DicomTag.StudyDescription)
        };

        return Ok(metadata);
    }
}

Stream-Based Serialization for Large Files

For large DICOM files, use stream-based serialization to reduce memory usage:

public async Task ConvertToJsonStreamAsync(string dicomFilePath, string outputPath)
{
    DicomFile dicomFile = DicomFile.Open(dicomFilePath);
    
    var options = new DicomJsonSerializerOptions
    {
        WriteIndented = true
    };
    
    using (var fileStream = new FileStream(outputPath, FileMode.Create))
    {
        await DicomJsonSerializer.SerializeAsync(
            fileStream, 
            dicomFile.Dataset, 
            options);
    }
}

Batch Conversion for Multiple Files

Process entire directories of DICOM files:

public class BatchDicomConverter
{
    public async Task ConvertDirectoryAsync(string inputDir, string outputDir)
    {
        Directory.CreateDirectory(outputDir);
        
        var dicomFiles = Directory.GetFiles(inputDir, "*.dcm");
        
        var options = new DicomJsonSerializerOptions
        {
            WriteIndented = true,
            UseKeywordsAsJsonKeys = true
        };

        foreach (var filePath in dicomFiles)
        {
            try
            {
                DicomFile dicomFile = DicomFile.Open(filePath);
                
                string fileName = Path.GetFileNameWithoutExtension(filePath);
                string outputPath = Path.Combine(outputDir, $"{fileName}.json");
                
                using (var stream = new FileStream(outputPath, FileMode.Create))
                {
                    await DicomJsonSerializer.SerializeAsync(
                        stream, 
                        dicomFile.Dataset, 
                        options);
                }
                
                Console.WriteLine($"Converted: {fileName}");
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Failed to convert {filePath}: {ex.Message}");
            }
        }
    }
}

Integrating with React Frontend

Once your API returns JSON, consuming it in React is straightforward:

// React component to display DICOM metadata
import React, { useState } from 'react';

function DicomViewer() {
    const [metadata, setMetadata] = useState(null);
    
    const handleFileUpload = async (event) => {
        const file = event.target.files[0];
        const formData = new FormData();
        formData.append('file', file);
        
        const response = await fetch('/api/dicom/to-json', {
            method: 'POST',
            body: formData
        });
        
        const json = await response.json();
        setMetadata(json);
    };
    
    return (
        <div>
            <input type="file" onChange={handleFileUpload} accept=".dcm" />
            {metadata && (
                <pre>{JSON.stringify(metadata, null, 2)}</pre>
            )}
        </div>
    );
}

Best Practices

When converting DICOM to JSON for web applications, keep these tips in mind:

  1. Anonymize before converting: Always remove patient identifiable information before exposing DICOM data through web APIs
  2. Use async methods: For web applications, use asynchronous serialization to avoid blocking threads
  3. Cache converted data: If the same DICOM files are requested frequently, cache the JSON output
  4. Validate input files: Check that uploaded files are valid DICOM before processing
  5. Handle binary data carefully: Large pixel data should be handled separately or excluded from JSON responses

Conclusion

Converting DICOM files to JSON opens up medical imaging data for modern web development. With Aspose.Medical for .NET, you can easily serialize DICOM datasets to PS3.18-compliant JSON, build REST APIs, and integrate with JavaScript frameworks. The examples in this guide provide a foundation for building web-based DICOM viewers, patient portals, and healthcare data platforms.

For more information about DICOM JSON serialization options, visit the Aspose.Medical documentation.

More in this category