Crate dicom_object

Expand description

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

Re-exports§

pub use crate::collector::DicomCollector;
pub use crate::collector::DicomCollectorOptions;
pub use crate::file::from_reader;
pub use crate::file::open_file;
pub use crate::file::OpenFileOptions;
pub use crate::mem::InMemDicomObject;
pub use crate::meta::FileMetaTable;
pub use crate::meta::FileMetaTableBuilder;

Modules§

collector: DICOM collector API: high-level construct for reading DICOM data sets in controlled chunks.
file
mem: This module contains the implementation for an in-memory DICOM object.
meta: Module containing data structures and readers of DICOM file meta information tables.
ops: Baseline attribute operation implementations.
tokens: Conversion of DICOM objects into tokens.

Structs§

FileDicomObject: A root DICOM object retrieved from a standard DICOM file, containing additional information from the file meta group in a separate table value.
StandardDataDictionary: A data element dictionary which consults the library’s global DICOM attribute registry.
Tag: The data type for DICOM data element tags.

Enums§

AccessByNameError: An error which may occur when looking up a DICOM object’s attributes by a keyword (or alias) instead of by tag.
AccessError: An error which may occur when looking up a DICOM object’s attributes.
AtAccessError: An error which may occur when looking up a DICOM object’s attributes at an arbitrary depth, such as through value_at.
AttributeError: An error which occurs when fetching a value
PrivateElementError: An error which may occur during private element look-up or insertion
ReadError: An error which may occur when loading a DICOM object
WithMetaError
WriteError: An error which may occur when writing a DICOM object

Constants§

IMPLEMENTATION_CLASS_UID: The current implementation class UID generically referring to DICOM-rs.
IMPLEMENTATION_VERSION_NAME: The current implementation version name generically referring to DICOM-rs.

Traits§

DicomAttribute: Interface type for access to a DICOM object’ attribute in a DICOM object.
DicomObject: Trait type for a generalized interpretation of a DICOM object.

Type Aliases§

DefaultDicomObject: The default implementation of a root DICOM object.