Setting Up DICOMObjects SDK

The DICOMObjects .NET SDK by Medical Connections provides comprehensive DICOM capabilities in a commercial library. This section covers installation and basic usage.

Installation

Installing the DICOMObjects SDK is straightforward using .NET’s package management system. The SDK is distributed through NuGet, allowing seamless integration into both new and existing .NET projects. You should install the SDK before attempting any DICOM operations in your application.

Using NuGet

The package is available through NuGet, making installation straightforward regardless of whether you use Visual Studio, Rider, or the command line. Choose the installation method that matches your development workflow.

# Install via NuGet Package Manager Console
Install-Package DicomObjects.NET

# Or using .NET CLI
dotnet add package DicomObjects.NET

Project Configuration

After installation, you need to import the SDK namespaces into your code files. These using statements provide access to core DICOM functionality and tooling utilities. Add these at the top of any file where you need to work with DICOM data.

using DicomObjects;
using DicomObjects.DicomToolKit;

Basic Configuration

Before using any DICOMObjects functionality, you must initialize the SDK with your license key. The SDK also provides global configuration options that control network behavior and timeout settings. Proper initialization ensures consistent behavior across all DICOM operations in your application. The following code shows the essential initialization steps that should be executed once during application startup, typically in your main entry point or configuration class.

// Initialize licensing (required for DICOMObjects)
DicomEnvironment.InitializeLicense("YOUR_LICENSE_KEY");

// Set up global configuration
DicomEnvironment.MaxPDULength = 65536; // Maximum PDU size
DicomEnvironment.AcceptTimeout = 30;   // Association timeout in seconds
DicomEnvironment.SocketReadTimeout = 30; // Socket read timeout

Configuration Options

Creating a DICOM Object

Creating DICOM objects programmatically is fundamental to building imaging applications. When creating a new DICOM object, you must populate the required attributes following the hierarchical structure: patient, study, series, and instance levels. Each level contains specific tags that identify and describe the imaging data.

Setting Attributes

// Create a new DICOM object
DicomImage dicomImage = new DicomImage();

// Set patient-level attributes
dicomImage.Attributes["00100010"].Value = "Doe^John"; // Patient Name
dicomImage.Attributes["00100020"].Value = "12345678";  // Patient ID
dicomImage.Attributes["00100030"].Value = "19800515";  // Birth Date
dicomImage.Attributes["00100040"].Value = "M";         // Sex

// Set study-level attributes
dicomImage.Attributes["0020000D"].Value = "1.2.840.113619.2.1.1.0";  // Study Instance UID
dicomImage.Attributes["00080020"].Value = "20240115";                 // Study Date
dicomImage.Attributes["00080030"].Value = "090000";                   // Study Time
dicomImage.Attributes["00080050"].Value = "ACC123456";                // Accession Number
dicomImage.Attributes["00081030"].Value = "CHEST CT";                 // Study Description

// Set series-level attributes
dicomImage.Attributes["0020000E"].Value = "1.2.840.113619.2.1.2.0"; // Series Instance UID
dicomImage.Attributes["00080060"].Value = "CT";                      // Modality
dicomImage.Attributes["00200011"].Value = "1";                       // Series Number

// Set instance-level attributes
dicomImage.Attributes["00080018"].Value = "1.2.840.113619.2.1.3.0"; // SOP Instance UID
dicomImage.Attributes["00200013"].Value = "1";                       // Instance Number

Understanding Tag Format

DICOM Tag Structure
===================

Tag: (0010,0010) = Patient Name

Format: GGGGEEEE
  GGGG = Group Number (0010)
  EEEE = Element Number (0010)

In code: "00100010" (8 hex digits, no separator)

Reading DICOM Files

Reading existing DICOM files is essential for viewing, processing, or migrating imaging data. The SDK handles parsing the binary DICOM format automatically, including decompression of pixel data when needed. Always use proper resource management with the using statement to ensure files are released after processing.

Basic File Reading

// Read a DICOM file from disk
using (DicomImage image = new DicomImage(@"C:\DICOM\CT_Image.dcm"))
{
    // Access patient information
    string patientName = image.Attributes["00100010"].Value.ToString();
    string patientID = image.Attributes["00100020"].Value.ToString();

    // Access image dimensions
    int rows = Convert.ToInt32(image.Attributes["00280010"].Value);    // Rows
    int columns = Convert.ToInt32(image.Attributes["00280011"].Value); // Columns

    // Access pixel data
    byte[] pixelData = image.PixelData;

    Console.WriteLine($"Patient: {patientName}");
    Console.WriteLine($"Image Size: {columns}x{rows}");
    Console.WriteLine($"Pixel Data Size: {pixelData.Length} bytes");
}

Common Attribute Access Patterns

When accessing DICOM attributes, you should always account for missing or null values to prevent runtime errors. Production applications typically wrap attribute access in helper methods that provide default values for missing data. This defensive approach handles real-world DICOM files that may have incomplete or inconsistent metadata.

// Safe attribute access with null checking
public string GetAttributeSafe(DicomImage image, string tag)
{
    if (image.Attributes.Contains(tag))
    {
        var value = image.Attributes[tag].Value;
        return value?.ToString() ?? string.Empty;
    }
    return string.Empty;
}

// Usage
string patientName = GetAttributeSafe(image, "00100010");
string modality = GetAttributeSafe(image, "00080060");

Writing DICOM Files

Creating new DICOM files requires careful attention to required attributes and proper UID generation. Every DICOM file must have valid Study, Series, and SOP Instance UIDs to maintain data integrity across PACS systems. When setting image parameters, ensure consistency between dimensions, bit depth, and actual pixel data size.

Creating and Saving

// Create and save a DICOM file
DicomImage newImage = new DicomImage();

// Set required attributes (Patient, Study, Series, Instance)
newImage.Attributes["00100010"].Value = "Test^Patient";
newImage.Attributes["00100020"].Value = "TEST001";
newImage.Attributes["0020000D"].Value = DicomUID.Generate(); // Study Instance UID
newImage.Attributes["0020000E"].Value = DicomUID.Generate(); // Series Instance UID
newImage.Attributes["00080018"].Value = DicomUID.Generate(); // SOP Instance UID

// Set image parameters
newImage.Attributes["00080060"].Value = "CT";
newImage.Attributes["00280010"].Value = 512;  // Rows
newImage.Attributes["00280011"].Value = 512;  // Columns
newImage.Attributes["00280100"].Value = 16;   // Bits Allocated
newImage.Attributes["00280101"].Value = 16;   // Bits Stored
newImage.Attributes["00280102"].Value = 15;   // High Bit
newImage.Attributes["00280103"].Value = 0;    // Pixel Representation (unsigned)

// Create simple pixel data (black image)
byte[] pixels = new byte[512 * 512 * 2]; // 16-bit pixels
newImage.PixelData = pixels;

// Save to file
newImage.Save(@"C:\DICOM\Output\test_image.dcm");

Handling Sequences

Sequences are nested data structures in DICOM that represent complex relationships between data elements. They are commonly used for referenced images, procedure codes, and structured content. Understanding how to read and create sequences is essential for working with advanced DICOM features like Structured Reports and Presentation States.

Reading Sequences

When reading sequences, you iterate through the items collection where each item contains its own set of DICOM attributes. Sequences can be nested multiple levels deep, so recursive handling may be necessary for complex DICOM objects.

// Read a DICOM file with sequences
using (DicomImage image = new DicomImage(@"C:\DICOM\CT_Image.dcm"))
{
    // Access a sequence (e.g., Referenced Image Sequence)
    DicomSequence refImageSeq = image.Attributes["00081140"] as DicomSequence;

    if (refImageSeq != null && refImageSeq.Items.Count > 0)
    {
        foreach (DicomDataSet item in refImageSeq.Items)
        {
            // Access attributes within the sequence item
            string referencedSOPClass = item["00081150"].Value.ToString();
            string referencedSOPInstance = item["00081155"].Value.ToString();

            Console.WriteLine($"Referenced SOP Class: {referencedSOPClass}");
            Console.WriteLine($"Referenced SOP Instance: {referencedSOPInstance}");
        }
    }
}

Creating Sequences

Creating sequences requires building both the container sequence and its individual items. Each item is essentially a mini-dataset that can contain any valid DICOM attributes. Properly constructed sequences enable interoperability with other DICOM systems expecting standardized nested structures.

// Create a sequence
DicomImage newImage = new DicomImage();
DicomSequence newSeq = new DicomSequence();

// Create sequence item
DicomDataSet item = new DicomDataSet();
item.Add("00081150", "1.2.840.10008.5.1.4.1.1.2"); // Referenced SOP Class UID
item.Add("00081155", DicomUID.Generate());          // Referenced SOP Instance UID

// Add item to sequence and sequence to image
newSeq.Items.Add(item);
newImage.Attributes.Add("00081140", newSeq);

Sequence Structure

UID Generation

Unique Identifiers (UIDs) are essential in DICOM for maintaining data integrity and ensuring global uniqueness across healthcare systems worldwide. UIDs follow the ISO 8824 standard and consist of numeric components separated by dots. Generating proper UIDs prevents data collisions when images from different institutions are merged in a shared archive.

// Generate UIDs using DICOMObjects
string studyUID = DicomUID.Generate();
string seriesUID = DicomUID.Generate();
string instanceUID = DicomUID.Generate();

// Custom UID root (requires registration)
const string MyOrganizationRoot = "1.2.840.99999"; // Example only
string customUID = $"{MyOrganizationRoot}.{DateTime.Now.Ticks}";

UID Best Practices

Summary

Setting up DICOMObjects provides:

1. Easy Installation: NuGet package with simple setup
2. Configuration Flexibility: Customize timeouts and PDU sizes
3. Intuitive API: Dictionary-style attribute access
4. Sequence Support: Handle nested DICOM structures
5. UID Management: Built-in UID generation

With the SDK configured, you’re ready to explore core DICOM concepts in detail.