This crate contains a high-level abstraction for reading and manipulating DICOM objects. At this level, objects are comparable to a dictionary of elements, in which some of them can have DICOM objects themselves. The end user should prefer using this abstraction when dealing with DICOM objects.

Overview

• Most interactions with DICOM objects will involve in-memory representations of the data set, through the type InMemDicomObject. New DICOM instances can also be built from scratch using this type. A wide assortment of methods are available for reading and manipulating the data set. See the [mem] module for more details.
• Loading a DICOM file can be done with ease via the function open_file. For additional file reading options, use OpenFileOptions. These are all available in the [mod@file] module.
• Other implementations of a DICOM object may exist to better serve other use cases. If generic support for any DICOM object implementation is a requirement, you can try using the DicomObject trait.
• Currently, the default file DICOM object implementation loads the complete contents of the file in memory, including pixel data. To read DICOM data sets in smaller portions, you can use the DICOM collector API.

Encodings

By default, dicom-object supports reading and writing DICOM files in any transfer syntax without data set compression. This includes Explicit VR Little Endian (with or without encapsulated pixel data), Implicit VR Little Endian, and Explicit VR Big Endian (retired). To enable support for reading and writing deflated data sets (such as Deflated Explicit VR Little Endian), enable Cargo feature deflated.

When working with imaging data, consider using the dicom-pixeldata crate, which offers methods to convert pixel data from objects into images or multi-dimensional arrays.

Examples

Reading a DICOM file

To read an object from a DICOM file and inspect some attributes:

use dicom_dictionary_std::tags;
use dicom_object::open_file;
let obj = open_file("0001.dcm")?;

let patient_name = obj.element(tags::PATIENT_NAME)?.to_str()?;
let modality = obj.element_by_name("Modality")?.to_str()?;

Elements can be fetched by tag, either by creating a [Tag] or by using one of the readily available constants from the dicom-dictionary-std crate.

By default, the entire data set is fully loaded into memory. The pixel data and following elements can be ignored by using OpenFileOptions:

use dicom_object::OpenFileOptions;

let obj = OpenFileOptions::new()
    .read_until(dicom_dictionary_std::tags::PIXEL_DATA)
    .open_file("0002.dcm")?;

When reading from other data sources without file meta information, you may need to use InMemDicomObject::read_dataset and specify the transfer syntax explicitly.

Fetching data in a DICOM file

Once a data set element is looked up, one will typically wish to inspect the value within. Methods are available for converting the element's DICOM value into something more usable in Rust.

let patient_date = obj.element(tags::PATIENT_BIRTH_DATE)?.to_date()?;
let pixel_data_bytes = obj.element(tags::PIXEL_DATA)?.to_bytes()?;

Writing DICOM

Note: the code above will only work if you are fetching native pixel data. If you are potentially working with encapsulated pixel data, see the dicom-pixeldata crate.

Writing DICOM data

Finally, DICOM objects can be serialized back into DICOM encoded bytes. A method is provided for writing a file DICOM object into a new DICOM file.

obj.write_to_file("0001_new.dcm")?;

This method requires you to write a file meta table first. When creating a new DICOM object from scratch, use a FileMetaTableBuilder to construct the file meta group, then use with_meta or with_exact_meta:

use dicom_dictionary_std::uids;

let file_obj = obj.with_meta(
    FileMetaTableBuilder::new()
        // Implicit VR Little Endian
        .transfer_syntax(uids::IMPLICIT_VR_LITTLE_ENDIAN)
        // Computed Radiography image storage
        .media_storage_sop_class_uid("1.2.840.10008.5.1.4.1.1.1")
)?;
file_obj.write_to_file("0001_new.dcm")?;

In order to write a plain DICOM data set, use one of the various data set writing methods such as write_dataset_with_ts:

// build your object
let mut obj = InMemDicomObject::from_element_iter([
    DataElement::new(
        Tag(0x0010, 0x0010),
        VR::PN,
        "Doe^John",
    ),
]);

// write the object's data set
let mut serialized = Vec::new();
let ts = dicom_transfer_syntax_registry::entries::EXPLICIT_VR_LITTLE_ENDIAN.erased();
obj.write_dataset_with_ts(&mut serialized, &ts)?;
assert_eq!(
    serialized.len(),
    16, // 4 (tag) + 2 (VR) + 2 (length) + 8 (data)
);

DICOM-rs object

This sub-project is directed at users of the DICOM-rs ecosystem. It provides a high-level abstraction to DICOM objects, enabling objects to be retrieved from files or 'readers', and then analysed as a tree of attributes.

This crate is part of the DICOM-rs project and is contained by the parent crate dicom.