Crate dicom_object

source ·
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.

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

Re-exports§

Modules§

  • 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
    Convertion 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.
  • 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§

Traits§

  • DicomObject
    Trait type for a DICOM object. This is a high-level abstraction where an object is accessed and manipulated as dictionary of entries indexed by tags, which in turn may contain a DICOM object.

Type Aliases§