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.

Loading a DICOM file can be done with ease via the function open_file. For additional file reading options, use OpenFileOptions. New DICOM instances can be built from scratch using InMemDicomObject (see the [mem] module for more details).

Examples

Read an object and fetch 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")?;

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()?;

Note: if you need to decode the pixel data first, see the dicom-pixeldata crate.

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::new_empty();
let patient_name = DataElement::new(
    Tag(0x0010, 0x0010),
    VR::PN,
    "Doe^John",
);
obj.put(patient_name);

// 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!(!serialized.is_empty());

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.