#dicom #object #attributes


A high-level API for reading and manipulating DICOM objects

7 releases (4 breaking)

0.5.4 Dec 12, 2022
0.5.3 Oct 23, 2022
0.5.2 Jul 19, 2022
0.5.0-rc.2 Feb 3, 2022
0.1.0 Aug 31, 2019

#232 in Data structures

Download history 492/week @ 2022-11-27 405/week @ 2022-12-04 519/week @ 2022-12-11 457/week @ 2022-12-18 175/week @ 2022-12-25 139/week @ 2023-01-01 345/week @ 2023-01-08 316/week @ 2023-01-15 375/week @ 2023-01-22 715/week @ 2023-01-29 638/week @ 2023-02-05 287/week @ 2023-02-12 474/week @ 2023-02-19 210/week @ 2023-02-26 518/week @ 2023-03-05 306/week @ 2023-03-12

1,535 downloads per month
Used in 17 crates (12 directly)


37K SLoC

DICOM-rs object

CratesIO Documentation

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.


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].


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()
# 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>> {
# 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(
        // Implicit VR Little Endian
        // Computed Radiography image storage
# 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),
    dicom_value!(Str, "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)?;
# Ok(())
# }
# run().unwrap();


~135K SLoC