Struct InMemDicomObject

pub struct InMemDicomObject<D = StandardDataDictionary> { /* private fields */ }

A DICOM object that is fully contained in memory.

See the module-level documentation for more details.

Implementations

impl InMemDicomObject<StandardDataDictionary>

pub fn new_empty() -> Self

Create a new empty DICOM object.

pub fn from_element_source<I>(iter: I) -> Result<Self, AccessError>

where I: IntoIterator<Item = Result<InMemElement<StandardDataDictionary>, AccessError>>,

Construct a DICOM object from a fallible source of structured elements.

pub fn from_element_iter<I>(iter: I) -> Self

where I: IntoIterator<Item = InMemElement<StandardDataDictionary>>,

Construct a DICOM object from a non-fallible source of structured elements.

pub fn command_from_element_iter<I>(iter: I) -> Self

where I: IntoIterator<Item = InMemElement<StandardDataDictionary>>,

Construct a DICOM object representing a command set, from a non-fallible iterator of structured elements.

This method will automatically insert a Command Group Length (0000,0000) element based on the command elements found in the sequence.

pub fn read_dataset<S>(decoder: S) -> Result<Self, ReadError>

where S: StatefulDecode,

Read an object from a source using the given decoder.

Note: read_dataset_with_ts and read_dataset_with_ts_cs may be easier to use.

pub fn read_dataset_with_ts_cs<S>( from: S, ts: &TransferSyntax, cs: SpecificCharacterSet, ) -> Result<Self, ReadError>

where S: Read,

Read an object from a source, using the given transfer syntax and default character set.

If the attribute Specific Character Set is found in the encoded data, this will override the given character set.

pub fn read_dataset_with_ts<S>( from: S, ts: &TransferSyntax, ) -> Result<Self, ReadError>

where S: Read,

Read an object from a source, using the given transfer syntax.

The default character set is assumed until Specific Character Set is found in the encoded data, after which the text decoder will be overridden accordingly.

impl<D> InMemDicomObject<D>

where D: DataDictionary + Clone,

pub fn new_empty_with_dict(dict: D) -> Self

Create a new empty object, using the given dictionary for name lookup.

pub fn from_element_source_with_dict<I>( iter: I, dict: D, ) -> Result<Self, AccessError>

where I: IntoIterator<Item = Result<InMemElement<D>, AccessError>>,

Construct a DICOM object from an iterator of structured elements.

pub fn from_iter_with_dict<I>(iter: I, dict: D) -> Self

where I: IntoIterator<Item = InMemElement<D>>,

Construct a DICOM object from a non-fallible iterator of structured elements.

pub fn command_from_iter_with_dict<I>(iter: I, dict: D) -> Self

where I: IntoIterator<Item = InMemElement<D>>,

Construct a DICOM object representing a command set, from a non-fallible iterator of structured elements.

This method will automatically insert a Command Group Length (0000,0000) element based on the command elements found in the sequence.

pub fn read_dataset_with_dict<S>(decoder: S, dict: D) -> Result<Self, ReadError>

where S: StatefulDecode, D: DataDictionary,

Read an object from a source, using the given decoder and the given dictionary for name lookup.

pub fn read_dataset_with_dict_ts<S>( from: S, dict: D, ts: &TransferSyntax, ) -> Result<Self, ReadError>

where S: Read, D: DataDictionary,

Read an object from a source, using the given data dictionary and transfer syntax.

pub fn read_dataset_with_dict_ts_cs<S>( from: S, dict: D, ts: &TransferSyntax, cs: SpecificCharacterSet, ) -> Result<Self, ReadError>

where S: Read, D: DataDictionary,

Read an object from a source, using the given data dictionary, transfer syntax, and the given character set to assume by default.

If the attribute Specific Character Set is found in the encoded data, this will override the given character set.

pub fn element(&self, tag: Tag) -> Result<&InMemElement<D>, AccessError>

Retrieve a particular DICOM element by its tag.

An error is returned if the element does not exist. For an alternative to this behavior, see element_opt.

pub fn element_by_name( &self, name: &str, ) -> Result<&InMemElement<D>, AccessByNameError>

Retrieve a particular DICOM element by its name.

This method translates the given attribute name into its tag before retrieving the element. If the attribute is known in advance, using element with a tag constant is preferred.

An error is returned if the element does not exist. For an alternative to this behavior, see element_by_name_opt.

pub fn element_opt( &self, tag: Tag, ) -> Result<Option<&InMemElement<D>>, AccessError>

Retrieve a particular DICOM element that might not exist by its tag.

If the element does not exist, None is returned.

pub fn get(&self, tag: Tag) -> Option<&InMemElement<D>>

Get a particular DICOM attribute from this object by tag.

If the element does not exist, None is returned.

pub fn element_by_name_opt( &self, name: &str, ) -> Result<Option<&InMemElement<D>>, AccessByNameError>

Retrieve a particular DICOM element that might not exist by its name.

If the element does not exist, None is returned.

This method translates the given attribute name into its tag before retrieving the element. If the attribute is known in advance, using element_opt with a tag constant is preferred.

pub fn private_element( &self, group: GroupNumber, creator: &str, element: u8, ) -> Result<&InMemElement<D>, PrivateElementError>

Get a private element from the dataset using the group number, creator and element number.

An error is raised when the group number is not odd, the private creator is not found in the group, or the private element is not found.

For more info, see the DICOM standard section on private elements.

Example

let mut ds = InMemDicomObject::from_element_iter([
    DataElement::new(
        Tag(0x0009, 0x0010),
        VR::LO,
        PrimitiveValue::from("CREATOR 1"),
    ),
    DataElement::new(Tag(0x0009, 0x01001), VR::DS, "1.0"),
]);
assert_eq!(
    ds.private_element(0x0009, "CREATOR 1", 0x01)?
        .value()
        .to_str()?,
    "1.0"
);

pub fn put(&mut self, elt: InMemElement<D>) -> Option<InMemElement<D>>

Insert a data element to the object, replacing (and returning) any previous element of the same attribute. This might invalidate all sequence and item lengths if the charset of the element changes.

pub fn put_element(&mut self, elt: InMemElement<D>) -> Option<InMemElement<D>>

Insert a data element to the object, replacing (and returning) any previous element of the same attribute. This might invalidate all sequence and item lengths if the charset of the element changes.

pub fn put_private_element( &mut self, group: GroupNumber, creator: &str, element: u8, vr: VR, value: PrimitiveValue, ) -> Result<Option<InMemElement<D>>, PrivateElementError>

Insert a private element into the dataset, replacing (and returning) any previous element of the same attribute.

This function will find the next available private element block in the given group. If the creator already exists, the element will be added to the block already reserved for that creator. If it does not exist, then a new block will be reserved for the creator in the specified group. An error is returned if there is no space left in the group.

For more info, see the DICOM standard section on private elements.

Example

let mut ds = InMemDicomObject::new_empty();
ds.put_private_element(
    0x0009,
    "CREATOR 1",
    0x02,
    VR::DS,
    PrimitiveValue::from("1.0"),
)?;
assert_eq!(
    ds.private_element(0x0009, "CREATOR 1", 0x02)?
        .value()
        .to_str()?,
    "1.0"
);
assert_eq!(
    ds.private_element(0x0009, "CREATOR 1", 0x02)?
        .header()
        .tag(),
    Tag(0x0009, 0x0102)
);

pub fn put_str( &mut self, tag: Tag, vr: VR, string: impl Into<String>, ) -> Option<InMemElement<D>>

Insert a new element with a string value to the object, replacing (and returning) any previous element of the same attribute.

pub fn remove_element(&mut self, tag: Tag) -> bool

Remove a DICOM element by its tag, reporting whether it was present.

pub fn remove_element_by_name( &mut self, name: &str, ) -> Result<bool, AccessByNameError>

Remove a DICOM element by its keyword, reporting whether it was present.

pub fn take_element(&mut self, tag: Tag) -> Result<InMemElement<D>, AccessError>

Remove and return a particular DICOM element by its tag.

pub fn take(&mut self, tag: Tag) -> Option<InMemElement<D>>

Remove and return a particular DICOM element by its tag, if it is present, returns None otherwise.

pub fn take_element_by_name( &mut self, name: &str, ) -> Result<InMemElement<D>, AccessByNameError>

Remove and return a particular DICOM element by its name.

pub fn retain(&mut self, f: impl FnMut(&InMemElement<D>) -> bool)

Modify the object by retaining only the DICOM data elements specified by the predicate.

The elements are visited in ascending tag order, and those for which f(&element) returns false are removed.

pub fn update_value( &mut self, tag: Tag, f: impl FnMut(&mut Value<InMemDicomObject<D>, InMemFragment>), ) -> bool

Obtain a temporary mutable reference to a DICOM value by tag, so that mutations can be applied within.

If found, this method resets all related lengths recorded and returns true. Returns false otherwise.

Example

let mut obj = InMemDicomObject::from_element_iter([
    DataElement::new(tags::LOSSY_IMAGE_COMPRESSION_RATIO, VR::DS, dicom_value!(Strs, ["25"])),
]);

// update lossy image compression ratio
obj.update_value(tags::LOSSY_IMAGE_COMPRESSION_RATIO, |e| {
    e.primitive_mut().unwrap().extend_str(["2.56"]);
});

assert_eq!(
    obj.get(tags::LOSSY_IMAGE_COMPRESSION_RATIO).unwrap().value().to_str().unwrap(),
    "25\\2.56"
);

pub fn update_value_at( &mut self, selector: impl Into<AttributeSelector>, f: impl FnMut(&mut Value<InMemDicomObject<D>, InMemFragment>), ) -> Result<(), AtAccessError>

Obtain a temporary mutable reference to a DICOM value by AttributeSelector, so that mutations can be applied within.

If found, this method resets all related lengths recorded and returns true. Returns false otherwise.

See the documentation of AttributeSelector for more information on how to write attribute selectors.

Note: Consider using apply when possible.

Example

let mut dcm = InMemDicomObject::from_element_iter([
    DataElement::new(
        tags::OTHER_PATIENT_I_DS_SEQUENCE,
        VR::SQ,
        DataSetSequence::from(vec![InMemDicomObject::from_element_iter([
            DataElement::new(
                tags::PATIENT_ID,
                VR::LO,
                dicom_value!(Str, "1234")
            )])
        ])
    ),
]);
let selector = (
    tags::OTHER_PATIENT_I_DS_SEQUENCE,
    0,
    tags::PATIENT_ID
);

// update referenced SOP instance UID for deidentification potentially
dcm.update_value_at(*&selector, |e| {
    let mut v = e.primitive_mut().unwrap();
    *v = dicom_value!(Str, "abcd");
});

assert_eq!(
    dcm.entry_at(*&selector).unwrap().value().to_str().unwrap(),
    "abcd"
);

pub fn value_at( &self, selector: impl Into<AttributeSelector>, ) -> Result<&Value<InMemDicomObject<D>, InMemFragment>, AtAccessError>

Obtain the DICOM value by finding the element that matches the given selector.

Returns an error if the respective element or any of its parents cannot be found.

See the documentation of AttributeSelector for more information on how to write attribute selectors.

Example

let referenced_sop_instance_iod = obj.value_at(
    (
        tags::SHARED_FUNCTIONAL_GROUPS_SEQUENCE,
        tags::REFERENCED_IMAGE_SEQUENCE,
        tags::REFERENCED_SOP_INSTANCE_UID,
    ))?
    .to_str()?;

pub fn convert_to_utf8(&mut self)

Change the ‘specific_character_set’ tag to ISO_IR 192, marking the dataset as UTF-8

pub fn entry_at( &self, selector: impl Into<AttributeSelector>, ) -> Result<&InMemElement<D>, AtAccessError>

Get a DataElement by AttributeSelector

If the element or other intermediate elements do not exist, the method will return an error.

See the documentation of AttributeSelector for more information on how to write attribute selectors.

If you only need the value, use value_at.

pub fn write_dataset<W, E>(&self, to: W, encoder: E) -> Result<(), WriteError>

where W: Write, E: EncodeTo<W>,

Write this object’s data set into the given writer, with the given encoder specifications, without preamble, magic code, nor file meta group.

The text encoding to use will be the default character set until Specific Character Set is found in the data set, in which then that character set will be used.

Note: write_dataset_with_ts and write_dataset_with_ts_cs may be easier to use.

pub fn write_dataset_with_ts_cs<W>( &self, to: W, ts: &TransferSyntax, cs: SpecificCharacterSet, ) -> Result<(), WriteError>

where W: Write,

Write this object’s data set into the given printer, with the specified transfer syntax and character set, without preamble, magic code, nor file meta group.

If the attribute Specific Character Set is found in the data set, the last parameter is overridden accordingly. See also write_dataset_with_ts.

pub fn write_dataset_with_ts<W>( &self, to: W, ts: &TransferSyntax, ) -> Result<(), WriteError>

where W: Write,

Write this object’s data set into the given writer, with the specified transfer syntax, without preamble, magic code, nor file meta group.

The default character set is assumed until the Specific Character Set is found in the data set, after which the text encoder is overridden accordingly.

pub fn with_exact_meta(self, meta: FileMetaTable) -> FileDicomObject<Self>

Encapsulate this object to contain a file meta group as described exactly by the given table.

Note: this method will not adjust the file meta group to be semantically valid for the object. Namely, the Media Storage SOP Instance UID and Media Storage SOP Class UID are not updated based on the receiving data set.

pub fn with_meta( self, meta: FileMetaTableBuilder, ) -> Result<FileDicomObject<Self>, WithMetaError>

Encapsulate this object to contain a file meta group, created through the given file meta table builder.

A complete file meta group should provide the Transfer Syntax UID, the Media Storage SOP Instance UID, and the Media Storage SOP Class UID. The last two will be filled with the values of SOP Instance UID and SOP Class UID if they are present in this object.

Example

use dicom_object::{InMemDicomObject, meta::FileMetaTableBuilder};

let obj = InMemDicomObject::from_element_iter([
    DataElement::new(tags::SOP_CLASS_UID, VR::UI, uids::COMPUTED_RADIOGRAPHY_IMAGE_STORAGE),
    DataElement::new(tags::SOP_INSTANCE_UID, VR::UI, "2.25.60156688944589400766024286894543900794"),
    // ...
]);

let obj = obj.with_meta(FileMetaTableBuilder::new()
    .transfer_syntax(uids::EXPLICIT_VR_LITTLE_ENDIAN))?;

// can now save everything to a file
let meta = obj.write_to_file("out.dcm")?;

pub fn iter(&self) -> impl Iterator<Item = &InMemElement<D>> + '_

Obtain an iterator over the elements of this object.

pub fn tags(&self) -> impl Iterator<Item = Tag> + '_

Obtain an iterator over the tags of the object’s elements.

Trait Implementations

impl<D> ApplyOp for InMemDicomObject<D>

where D: DataDictionary + Clone,

type Err = ApplyError

The operation error type

fn apply(&mut self, op: AttributeOp) -> ApplyResult

Apply the given attribute operation on the receiving object.

impl<D: Clone> Clone for InMemDicomObject<D>

fn clone(&self) -> InMemDicomObject<D>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<D: Debug> Debug for InMemDicomObject<D>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'s, D> DicomObject for &'s InMemDicomObject<D>

where D: DataDictionary + Clone + 's,

type Element = &'s DataElement<InMemDicomObject<D>>

fn element(&self, tag: Tag) -> Result<Self::Element, AccessError>

Retrieve a particular DICOM element by its tag.

fn element_by_name( &self, name: &str, ) -> Result<Self::Element, AccessByNameError>

Retrieve a particular DICOM element by its name.

fn meta(&self) -> Option<&FileMetaTable>

Retrieve the processed meta information table, if available.

impl<D> Extend<DataElement<InMemDicomObject<D>>> for InMemDicomObject<D>

fn extend<I>(&mut self, iter: I)

where I: IntoIterator<Item = InMemElement<D>>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<D> HasLength for InMemDicomObject<D>

fn length(&self) -> Length

Retrieve the value data’s length as specified by the data element or item, in bytes.

fn is_empty(&self) -> bool

Check whether the value is empty (0 length).

impl<'a, D> IntoIterator for &'a InMemDicomObject<D>

type Item = &'a DataElement<InMemDicomObject<D>>

The type of the elements being iterated over.

type IntoIter = Values<'a, Tag, DataElement<InMemDicomObject<D>>>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<D> IntoIterator for InMemDicomObject<D>

type Item = DataElement<InMemDicomObject<D>>

The type of the elements being iterated over.

type IntoIter = Iter<D>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, D> IntoTokens for &'a InMemDicomObject<D>

where D: Clone,

type Iter = InMemObjectTokens<Cloned<<&'a InMemDicomObject<D> as IntoIterator>::IntoIter>>

The iterator type through which tokens are obtained.

fn into_tokens(self) -> Self::Iter

fn into_tokens_with_options(self, options: IntoTokensOptions) -> Self::Iter

impl<D> IntoTokens for InMemDicomObject<D>

type Iter = InMemObjectTokens<<InMemDicomObject<D> as IntoIterator>::IntoIter>

The iterator type through which tokens are obtained.

fn into_tokens(self) -> Self::Iter

fn into_tokens_with_options(self, options: IntoTokensOptions) -> Self::Iter

impl<D> PartialEq for InMemDicomObject<D>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.