Vuresoft.Dicom.Sqlite 0.4.3

Vuresoft.Dicom.Sqlite

** BETA VERSION **

A .NET library for storing DICOM medical images in SQLite databases. Each DICOM study is stored in its own SQLite database file, containing all instances with their complete image data.

Features

• Store complete DICOM studies in single SQLite database files
• One database per study for easy management and portability
• Retrieve DICOM data by Study, Series, and Instance UIDs
• Memory-efficient streaming APIs for large datasets
• Bulk import from directories or file lists

Installation

Add reference to Vuresoft.Dicom.Sqlite project or NuGet package (when available).

Basic Usage

Create a database from a directory of DICOM files

using Vuresoft.Dicom.Sqlite;

// Create a new database from a folder containing DICOM files
var db = await SqliteDicomStudyDb.CreateFromDirectoryAsync(
    sourceDirectory: @"C:\DicomFiles\Study123",
    databasePath: @"C:\Studies\study123.db"
);

Add DICOM files to an existing database

using var db = new SqliteDicomStudyDb(@"C:\Studies\study123.db");

// Add a single file
await db.AddInstanceFromFileAsync(@"C:\DicomFiles\image.dcm");

// Import multiple files
var files = new[] { "file1.dcm", "file2.dcm", "file3.dcm" };
await db.ImportFilesAsync(files);

// Import entire directory
await db.ImportDirectoryAsync(@"C:\DicomFiles\Study123");

Retrieve DICOM data

using var db = new SqliteDicomStudyDb(@"C:\Studies\study123.db");

// Get a single instance as DicomDataset
var dataset = await db.GetInstanceAsync(studyUid, seriesUid, sopUid);

// Get raw DICOM bytes
var bytes = await db.GetInstanceBytesAsync(studyUid, seriesUid, sopUid);

// Get all instances in a series
var seriesDatasets = await db.GetSeriesAsync(studyUid, seriesUid);

Stream large datasets efficiently

using var db = new SqliteDicomStudyDb(@"C:\Studies\study123.db");

// Stream all DICOM datasets without loading into memory
await foreach (var dataset in db.GetAllInstancesDataSetsStreamAsync())
{
    // Process each dataset as it streams from the database
    var patientName = dataset.GetSingleValue<string>(DicomTag.PatientName);
    Console.WriteLine($"Processing: {patientName}");
}

// Stream raw DICOM bytes for an entire study
await foreach (var imageBytes in db.GetStudyBytesStreamAsync(studyUid))
{
    // Process each DICOM file's raw bytes
    await ProcessDicomBytesAsync(imageBytes);
}

Repair stored metadata

The stored DICOM JSON metadata is built once, at ingest. After a fix to the JSON rules, rebuild it from the stored image bytes; no new upload is needed. Only changed rows are written, so a second run changes nothing.

using var db = new SqliteDicomStudyDb(@"C:\Studies\study123.db");
var result = await db.RebuildJsonMetadataAsync(); // e.g. Instances = 1, Changed = 1

Database Structure

Each SQLite database contains:

• Study table - Study Instance UID
• Series table - Series Instance UIDs linked to studies
• Instance table - SOP Instance UIDs with complete DICOM file data stored as BLOB

Dependencies

• fo-dicom - DICOM file parsing
• Microsoft.EntityFrameworkCore.Sqlite - Database access
• .NET 10.0 or later

Changelog

0.2.10

• Added GetInstanceBlobStream() using SQLite incremental blob I/O (SqliteBlob)
• Updated GetInstanceBytesStreamAsync() to use true streaming without full blob materialization
• Eliminates byte[] allocation at the database layer - data streams directly from SQLite
• Reduces GC pressure for large DICOM files
• Legacy method GetInstanceBytesStreamAsyncLegacy() available for compatibility

0.2.9

• Added streaming APIs for series and study retrieval
• Performance improvements for large datasets