Aspose.Medical 26.10.0

DICOM and Medical Imaging API for .NET

Product Page | Docs | API Reference | Blog | Releases | Free Support | Temporary License

Aspose.Medical for .NET is a fully managed .NET 10 library for working with DICOM: read, create, edit, render, anonymize, and transcode DICOM files, and exchange them with other systems over DIMSE and DICOMweb. It has no native dependencies and does not require any medical imaging software to be installed. It runs on Windows and Linux in any kind of .NET application, from console tools to ASP.NET Core services.

Key Features

• DICOM data model: Full access to files, datasets, elements, sequences, and pixel data, with standard and private tags, including custom private tag dictionaries.
• Efficient I/O: Read and write files, streams, and System.IO.Pipelines, synchronously or asynchronously. Load large elements such as pixel data only when they are accessed, or skip them entirely.
• Rendering: Render single-frame and multi-frame images to 32-bit pixel buffers.
• Transcoding: Convert between uncompressed and compressed transfer syntaxes (see below).
• Anonymization: De-identify datasets with the DICOM PS3.15 confidentiality profiles and their options, or with your own profile loaded from CSV, JSON, or XML.
• JSON and XML: Convert datasets to and from the DICOM JSON Model (PS3.18) and the Native DICOM Model XML (PS3.19).
• DIMSE networking: Build SCU and SCP applications with C-ECHO, C-STORE, C-FIND, C-MOVE, C-GET, and the N-services, with optional TLS.
• DICOMweb: Search, retrieve, and store over the standard RESTful services (QIDO-RS, WADO-RS, STOW-RS, and others) with a client built on HttpClient.
• Licensing: Traditional license files and metered (pay-per-use) licensing.

What's New

Version 26.10 introduces DICOMweb support, enabling RESTful access to medical imaging services for storing, retrieving, and querying DICOM data over standard web protocols.

Supported Transfer Syntaxes

• Uncompressed (Implicit and Explicit VR Little Endian, Explicit VR Big Endian) and Deflated Explicit VR Little Endian: read and write.
• RLE Lossless: read and write.
• JPEG Baseline (Process 1): read and write (8-bit).
• JPEG Lossless (Process 14 and Process 14 SV1): read.
• JPEG-LS Lossless and Near-Lossless: read and write.
• JPEG 2000 Lossless and Lossy: read and write 8-bit and 16-bit monochrome and 8-bit RGB images.
• HTJ2K (all three transfer syntaxes): read and write.
• JPEG XL Lossless and JPEG XL: read and write. JPEG XL JPEG Recompression: read.

JPEG Extended (Process 2 and 4) and the video transfer syntaxes (MPEG-2, MPEG-4, HEVC) are not supported. All codecs are implemented in managed C#. If you need a transfer syntax or a bit depth that is not listed, tell us on the support forum.

Get Started

dotnet add package Aspose.Medical

Open, Edit, and Save a DICOM File

using Aspose.Medical.Dicom;
using Aspose.Medical.Dicom.Tags;

DicomFile file = DicomFile.Open("input.dcm");

string patientName = file.Dataset.GetSingleValue<string>(Tag.PatientName);
Console.WriteLine($"Patient: {patientName}, frames: {file.NumberOfFrames}");

file.Dataset.AddOrUpdate(Tag.PatientID, "12345");
file.Dataset.AddOrUpdate(Tag.StudyDate, new DateOnly(2026, 10, 1));
file.Save("output.dcm");

To create a new file, start with new DicomFile() and fill its Dataset the same way. For large files, pass TagDataReadingStrategies.ReadLargeOnDemand() or TagDataReadingStrategies.SkipLargeTags() to DicomFile.Open to keep pixel data out of memory until you need it.

Render a Frame

using Aspose.Medical.Dicom;

DicomFile file = DicomFile.Open("input.dcm");

// Render the first frame to 32-bit BGRA pixels
var image = file.RenderImage(frameIndex: 0);
byte[] bgra = new byte[image.Width * image.Height * 4];
image.CopyPixelsTo(bgra);

// Hand the buffer to an imaging library of your choice to save it as PNG or JPEG
Console.WriteLine($"Rendered {image.Width} x {image.Height}");

Anonymize a DICOM File

using Aspose.Medical.Dicom;
using Aspose.Medical.Dicom.Anonymization;

// The default anonymizer applies the Basic Application Level Confidentiality Profile
var anonymizer = new Anonymizer();

DicomFile anonymized = anonymizer.Anonymize(DicomFile.Open("input.dcm"));
anonymized.Save("anonymized.dcm");

// Combine profile options, for example to keep the original UIDs
var keepUids = new Anonymizer(ConfidentialityProfile.CreateDefault(
    ConfidentialityProfileOptions.BasicProfile | ConfidentialityProfileOptions.RetainUIDs));

Transcode to Another Transfer Syntax

using Aspose.Medical.Dicom;

DicomFile file = DicomFile.Open("input.dcm");

DicomFile compressed = file.Transcode(TransferSyntax.Jpeg2000Lossless);
compressed.Save("jpeg2000.dcm");

Convert to DICOM JSON

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

Dataset dataset = DicomFile.Open("input.dcm").Dataset;

string json = DicomJsonSerializer.Serialize(dataset, writeIndented: true);
Dataset? restored = DicomJsonSerializer.Deserialize(json);

DicomXmlSerializer converts to and from the Native DICOM Model XML in the same way.

Query and Store over DICOMweb

using Aspose.Medical.Dicom;
using Aspose.Medical.Dicom.Tags;
using Aspose.Medical.Dicom.Web;

using var http = new HttpClient();
var client = new DicomWebClient(http, new DicomWebClientOptions
{
    BaseUri = new Uri("https://pacs.example.com/dicom-web/")
});

// STOW-RS: store an instance
await client.Studies.StoreAsync(DicomFile.Open("input.dcm"));

// QIDO-RS: find the studies of a patient
await using var studies = await client.Studies.SearchAsync(new DicomWebSearchOptions
{
    MatchingParameters = [new DicomWebQueryParameter("PatientID", "12345")]
});
await foreach (Dataset study in studies)
{
    string studyUid = study.GetSingleValue<string>(Tag.StudyInstanceUID);

    // WADO-RS: retrieve every instance of the study
    await using var instances = await client.Studies.RetrieveStudyAsync(studyUid);
    await foreach (DicomFile instance in instances)
        instance.Save($"{instance.Dataset.GetSingleValue<string>(Tag.SOPInstanceUID)}.dcm");
}

Verify a Connection with C-ECHO

using System.Net;
using Aspose.Medical.Communication.Notifications;
using Aspose.Medical.Dicom;
using Aspose.Medical.Dicom.Network.Client;
using Aspose.Medical.Dicom.Network.Client.Handlers;
using Aspose.Medical.Dicom.Network.Connection;
using Aspose.Medical.Dicom.Network.Messages;
using Aspose.Medical.Dicom.Network.Negotiation;

var association = new AssociationNegotiationOptions()
    .WithPresentationContext(new PresentationContext
    {
        AbstractSyntax = Uid.Verification,
        Role = null,
        TransferSyntaxes = [TransferSyntax.ImplicitVrLittleEndian]
    });

DicomNetworkClient client = DicomNetworkClient
    .CreateBuilder(new DicomNetworkClientOptions
    {
        Called = "PACS",
        Calling = "MY_SCU",
        Connection = new DicomNetworkConnectionOptions { TargetHost = new IPEndPoint(IPAddress.Parse("192.0.2.10"), 104) },
        AssociationNegotiation = association
    })
    .AddSingletonCEchoHandler(new EchoObserver())
    .Build();

client.QueueRequest(new CEchoRequest());
await client.SendAsync();
await client.StopAsync();

sealed class EchoObserver : ICEchoExchangeHandler
{
    public ValueTask Handle(UnaryExchangeNotification<CEchoRequest, CEchoResponse> exchange, CancellationToken cancellationToken)
    {
        Console.WriteLine($"C-ECHO status: 0x{exchange.Response.Status:X4}");
        return ValueTask.CompletedTask;
    }
}

The same client sends C-STORE, C-FIND, C-MOVE, and C-GET requests, and DicomNetworkServer builds SCP applications. See the DICOM networking guide for details.

Licensing

// A license file
new Aspose.Medical.License().SetLicense("Aspose.Medical.lic");

// Or metered licensing
new Aspose.Medical.Metered().SetMeteredKey("public-key", "private-key");
Console.WriteLine($"Consumed credits: {Aspose.Medical.Metered.GetConsumptionCredit()}");

Without a license the library runs in evaluation mode. A temporary license lifts the evaluation limits for 30 days.

Support

Ask questions and report issues on the free support forum. The documentation and the API reference cover the whole API.