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.

lib.rs:

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 easily via the function [open_file]. For additional file reading options, use [OpenFileOptions].

Examples

Read an object and fetch some attributes by their standard alias:

use dicom_object::open_file;
# fn foo() -> Result<(), Box<dyn std::error::Error>> {
let obj = open_file("0001.dcm")?;
let patient_name = obj.element_by_name("PatientName")?.to_str()?;
let modality = obj.element_by_name("Modality")?.to_str()?;
# Ok(())
# }

The current default implementation places the full DICOM object in 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")?;
# Result::<(), dicom_object::Error>::Ok(())

Elements can also be fetched by tag. Methods are available for converting the element's DICOM value into something more usable in Rust.

# use dicom_object::{DefaultDicomObject, Tag};
# fn something(obj: DefaultDicomObject) -> Result<(), Box<dyn std::error::Error>> {
let patient_date = obj.element(Tag(0x0010, 0x0030))?.to_date()?;
let pixel_data_bytes = obj.element(Tag(0x7FE0, 0x0010))?.to_bytes()?;
# Ok(())
# }

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.

# use dicom_object::{DefaultDicomObject, Tag};
# fn something(obj: DefaultDicomObject) -> Result<(), Box<dyn std::error::Error>> {
obj.write_to_file("0001_new.dcm")?;
# Ok(())
# }

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_object::{InMemDicomObject, FileMetaTableBuilder};
# fn something(obj: InMemDicomObject) -> Result<(), Box<dyn std::error::Error>> {
let file_obj = obj.with_meta(
    FileMetaTableBuilder::new()
        // Implicit VR Little Endian
        .transfer_syntax("1.2.840.10008.1.2")
        // 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")?;
# Ok(())
# }

In order to write a plain DICOM data set, use one of the various write_dataset methods.

# use dicom_object::InMemDicomObject;
# use dicom_core::{DataElement, Tag, VR, dicom_value};
# fn run() -> Result<(), Box<dyn std::error::Error>> {
// build your object
let mut obj = InMemDicomObject::new_empty();
let patient_name = DataElement::new(
    Tag(0x0010, 0x0010),
    VR::PN,
    dicom_value!(Str, "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());
# Ok(())
# }
# run().unwrap();