Aspose.Medical for .NET is a comprehensive API for processing DICOM and other medical imaging formats. This cross-platform library enables .NET developers to create, edit, read, and convert medical images without requiring third-party applications or dependencies. Version 26.3 introduces a pure C# High-Throughput JPEG 2000 (HTJ2K) codec implementation for platform-independent support of the HTJ2K transfer syntax.
Aspose.Medical for .NET is a cross-platform API that helps in developing applications with the ability to create, manipulate, inspect, or convert DICOM files and other medical imaging formats without any dependency.
Without having to install specialized medical imaging software or any 3rd party component, you can use Aspose.Medical to build different types of .NET applications, e.g., Windows Forms Apps, Windows Web Apps, as well as to deploy Web Services for medical image processing and analysis.
Medical Imaging Processing Features
Intuitive DICOM Data Model: Aspose.Medical's object model gives complete control over DICOM elements, datasets, and pixel data. Developers can use this model to create complex medical imaging applications that can dynamically generate, load, modify, and analyze DICOM files.
DICOM Data Manipulation: Access, modify, add, and remove data elements from DICOM files with comprehensive support for standard and private DICOM tags (including loading custom private tag dictionaries) and data types.
High-Performance I/O with System.IO.Pipelines: Leverage modern async I/O patterns with comprehensive support for System.IO.Pipelines. Read and write DICOM files using Pipe, PipeReader, and PipeWriter for zero-allocation scenarios, producer/consumer patterns, and optimal async/await performance with fine-grained buffer control.
Optimized Memory Usage: Efficiently read large DICOM files using memory-optimized strategies. Choose to load all data at once, defer loading of large tags until they are accessed, or skip them entirely to minimize memory footprint. Configure buffer sizes and read thresholds for optimal performance.
Flexible Licensing: Support for both traditional and metered licensing models. Metered licensing provides consumption tracking, credit monitoring, and flexible billing options for cloud-based and scalable applications.
DICOM to/from JSON Conversion: Convert DICOM datasets to and from JSON format according to the PS3.18 standard. This facilitates integration with web services, data analysis pipelines, and systems that prefer JSON for data interchange.
DICOM to/from XML Conversion: Serialize DICOM datasets to XML and deserialize XML back into DICOM objects, complying with the PS3.18 standard for web services and data interchange.
Image Rendering & Processing: Render DICOM images to standard formats, access pixel data, and work with multi-frame files.
Anonymization: Protect patient privacy with built-in confidentiality profiles for DICOM file anonymization in compliance with HIPAA and GDPR regulations.
Transcoding: Convert between different DICOM transfer syntaxes including uncompressed, JPEG, JPEG-LS, JPEG 2000, RLE, and also includes support for deflatable datasets.
Read & Write Medical Files
DICOM: DCM files, DICOMDIR
Platform Independence
Aspose.Medical for .NET can be used to build any type of .NET 8.0 application including ASP.NET, WCF & WinForms. The package provides assemblies to be used with .NET 8.0 on various flavors of Windows and Linux.
Current Development Status
Aspose.Medical for .NET is actively under development with new features being added in each release. Version 26.3 introduces a pure C# High-Throughput JPEG 2000 (HTJ2K) codec implementation, adding platform-independent support for the HTJ2K transfer syntax.
Currently, there are some limitations regarding codec support:
JPEG Codecs: All JPEG codecs are implemented in pure C# and are platform-independent. JPEG Lossless support is currently limited to 8-bit images only.
JPEG 2000: Supports 8-bit and 16-bit reading, but only 8-bit writing.
HTJ2K: Implemented in pure C# and is platform-independent.
Unsupported Codecs: JPEG Extended (Process 2 & 4) and JPEG XL are not currently supported.
We are continuously improving the library based on user feedback and industry needs. Future releases will add support for additional transfer syntaxes and enhance existing codec functionality. If you have specific requirements or encounter any issues, please share your feedback through our support forum to help us prioritize development efforts.
Get Started
Execute Install-Package Aspose.Medical -Version 26.3 from Package Manager Console in Visual Studio to fetch the NuGet package. If you already have Aspose.Medical for .NET and want to upgrade the version, please execute Update-Package Aspose.Medical to get the latest version.
Open a DICOM File with Memory Optimization
You can control memory usage when opening large DICOM files using different reading strategies and buffer tuning options.
// Configure file read options with buffer tuning
var options = new Aspose.Medical.Dicom.Readers.ReadDicomFileOptions
{
FallbackEncoding = System.Text.Encoding.UTF8,
BufferTuningOptions = new Aspose.Medical.Dicom.Readers.ReadBufferTuningOptions
{
BufferSize = 64 * 1024, // 64 KiB buffer
MinimumReadSize = 32 * 1024 // 32 KiB read size
}
};
// Strategy 1: Read all tags immediately (default behavior)
var dicomFileAll = Aspose.Medical.Dicom.DicomFile.Open("large_file.dcm",
options, Aspose.Medical.Dicom.Readers.TagDataReadingStrategies.ReadAll());
// Strategy 2: Defer loading of large tags (e.g., > 128 KB) until they are accessed
var dicomFileOnDemand = Aspose.Medical.Dicom.DicomFile.Open("large_file.dcm",
options, Aspose.Medical.Dicom.Readers.TagDataReadingStrategies.ReadLargeOnDemand(128));
// Large tags are loaded only when you access them, for example:
// var pixelData = dicomFileOnDemand.Dataset.GetValues<byte>(Aspose.Medical.Dicom.Tags.Tag.PixelData);
// Strategy 3: Skip large tags entirely to save memory
var dicomFileSkipLarge = Aspose.Medical.Dicom.DicomFile.Open("large_file.dcm",
options, Aspose.Medical.Dicom.Readers.TagDataReadingStrategies.SkipLargeTags(128));
Create a DICOM File from Scratch with C# Code
// Create an empty DICOM file
var dicomFile = new Aspose.Medical.Dicom.DicomFile();
// Add data to the newly created DICOM file
dicomFile.Dataset.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PatientName, "John Doe");
dicomFile.Dataset.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PatientID, "12345");
dicomFile.Dataset.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PatientBirthDate, new DateOnly(1980, 1, 1));
dicomFile.Dataset.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.StudyDate, new DateOnly(2025, 3, 25));
dicomFile.Dataset.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.XAAcquisitionFrameRate, 17.95);
// Save the DICOM file
dicomFile.Save("output.dcm");
Convert DICOM to XML and Vice-Versa
// Load a DICOM file
var dcmFile = Aspose.Medical.Dicom.DicomFile.Open("sample.dcm");
var dataset = dcmFile.Dataset;
// Serialize dataset to XML
// Ensure the Aspose.Medical.Dicom.Serialization namespace is imported
string xmlString = Aspose.Medical.Dicom.Serialization.DicomXmlSerializer.Serialize(dataset);
System.Console.WriteLine("DICOM as XML:\n" + xmlString);
// Deserialize XML back to Dataset
var deserializedDatasetFromXml = Aspose.Medical.Dicom.Serialization.DicomXmlSerializer.Deserialize(xmlString);
if (deserializedDatasetFromXml != null && deserializedDatasetFromXml.Contains(Aspose.Medical.Dicom.Tags.Tag.PatientName))
{
System.Console.WriteLine("Deserialized Patient Name from XML: " + deserializedDatasetFromXml.GetSingleValue<string>(Aspose.Medical.Dicom.Tags.Tag.PatientName));
}
Convert DICOM to JSON and Vice-Versa
// Load a DICOM file
var dcmFile = Aspose.Medical.Dicom.DicomFile.Open("sample.dcm");
var dataset = dcmFile.Dataset;
// Serialize dataset to JSON
// Ensure the Aspose.Medical.Dicom.Serialization namespace is imported
string? jsonString = Aspose.Medical.Dicom.Serialization.DicomJsonSerializer.Serialize(dataset, writeIndented: true);
System.Console.WriteLine("DICOM as JSON:\n" + jsonString);
// Deserialize JSON back to Dataset
var deserializedDataset = Aspose.Medical.Dicom.Serialization.DicomJsonSerializer.Deserialize(jsonString);
if (deserializedDataset != null && deserializedDataset.Contains(Aspose.Medical.Dicom.Tags.Tag.PatientName))
{
System.Console.WriteLine("Deserialized Patient Name: " + deserializedDataset.GetSingleValue<string>(Aspose.Medical.Dicom.Tags.Tag.PatientName));
}
Render DICOM Images
// Load a DICOM file
var dicomFile = Aspose.Medical.Dicom.DicomFile.Open("input.dcm");
// Get the total number of frames
int frameCount = dicomFile.NumberOfFrames;
Console.WriteLine($"Total Frames: {frameCount}");
// Render the first frame
var rawImage = dicomFile.RenderImage(0);
// Display image properties
Console.WriteLine($"Image Dimensions: {rawImage.Width} x {rawImage.Height}");
// Access pixel values if needed
var pixelColor = rawImage[10, 10];
Console.WriteLine($"Pixel at (10,10): R={pixelColor.R}, G={pixelColor.G}, B={pixelColor.B}");
Anonymize a DICOM File
// Load a DICOM file
var dicomFile = Aspose.Medical.Dicom.DicomFile.Open("input.dcm");
// Create an anonymizer with the default profile
var anonymizer = new Aspose.Medical.Dicom.Anonymization.Anonymizer();
// Anonymize the DICOM file
var anonymizedFile = anonymizer.Anonymize(dicomFile);
// Save the anonymized file
anonymizedFile.Save("anonymized_output.dcm");
Transcode a DICOM File to Different Transfer Syntax
// Load existing file
var dcm = Aspose.Medical.Dicom.DicomFile.Open("input.dcm");
// Transcode the loaded file to JPEG 2000 Lossless Transfer Syntax
var transcodedDcm = dcm.Transcode(Aspose.Medical.Dicom.TransferSyntax.Jpeg2000Lossless);
// Save the transcoded file
transcodedDcm.Save("transcoded_output.dcm");
High-Performance I/O with System.IO.Pipelines
// Read DICOM from PipeReader for async producer/consumer scenarios
var pipeOptions = new Aspose.Medical.Dicom.Readers.ReadDicomPipeOptions
{
FallbackEncoding = System.Text.Encoding.UTF8
};
System.IO.Pipelines.Pipe pipe = new System.IO.Pipelines.Pipe();
var dcm = Aspose.Medical.Dicom.DicomFile.Open(pipe, pipeOptions,
Aspose.Medical.Dicom.Readers.TagDataReadingStrategies.ReadAll());
// Save DICOM to PipeWriter with buffer tuning
var saveOptions = new Aspose.Medical.Dicom.Writers.SaveDicomToStreamOptions
{
BufferTuningOptions = new Aspose.Medical.Dicom.Writers.WriteBufferTuningOptions
{
MinimumSegmentSizeBytes = 64 * 1024,
ProducerFlushThresholdBytes = 256 * 1024
}
};
using var stream = new System.IO.MemoryStream();
dcm.Save(stream, saveOptions);
Metered Licensing
// Set up metered license
var metered = new Aspose.Medical.Metered();
metered.SetMeteredKey("your-public-key", "your-private-key");
// Verify license status
bool isLicensed = metered.IsMeteredLicensed();
// Get consumption metrics
decimal consumedQuantity = metered.GetConsumptionQuantity();
decimal consumedCredit = metered.GetConsumptionCredit();
