Crate dicom_pixeldata

Expand description

This crate contains the DICOM pixel data handlers and is responsible for decoding various forms of native and compressed pixel data, such as JPEG lossless, and convert it into more usable data structures.

Once the pixel data is decoded, the decoded data can be converted to:

a vector of flat pixel data values;
a multi-dimensional array, using ndarray;
or a dynamic image object, using image.

This conversion includes eventual Modality and value of interest (VOI) transformations, either for further processing or presentation.

§Encoding support

The pixel data encodings supported by dicom-pixeldata are backed by the dicom-transfer-syntax-registry crate. By default, this crate will consider this set of image encoding implementations written in pure Rust:

jpeg for JPEG lossy and lossless encodings via jpeg-decoder and jpeg-encoder;
rle for RLE compressed pixel data;
deflate for deflated data set compression via flate2.

See the dicom-transfer-syntax-registry documentation for an extended list of supported encodings and more details.

Alternatively, this library has an integration with GDCM bindings, which serves as a different backend. This allows for decoding pixel data in transfer syntaxes which are only supported by GDCM. This integration is behind the Cargo feature “gdcm”, which requires CMake and a C++ compiler.

dicom-pixeldata = { version = "0.8", features = ["gdcm"] }

§Usage

§WebAssembly support

This library works in WebAssembly with the following two measures:

Ensure that the “gdcm” feature is disabled. Some Cargo feature referring to encodings which depend on bindings to C or C++ libraries might also need to be disabled.
And either set up wasm-bindgen-rayon or disable the rayon feature.

§Examples

To convert a DICOM object into a dynamic image (requires the image feature):

use dicom_object::open_file;
use dicom_pixeldata::PixelDecoder;
let obj = open_file("dicom.dcm")?;
let image = obj.decode_pixel_data()?;
let dynamic_image = image.to_dynamic_image(0)?;
dynamic_image.save("out.png")?;

To convert a DICOM object into an ndarray (requires the ndarray feature):

use dicom_object::open_file;
use dicom_pixeldata::PixelDecoder;
use ndarray::s;
let obj = open_file("rgb_dicom.dcm")?;
let pixel_data = obj.decode_pixel_data()?;
let ndarray = pixel_data.to_ndarray::<u16>()?;
let red_values = ndarray.slice(s![.., .., .., 0]);

In order to parameterize the conversion, pass a conversion options value to the _with_options variant methods.

use dicom_object::open_file;
use dicom_pixeldata::{ConvertOptions, PixelDecoder, VoiLutOption};
let obj = open_file("dicom.dcm")?;
let image = obj.decode_pixel_data()?;
let options = ConvertOptions::new()
    .with_voi_lut(VoiLutOption::Normalize)
    .force_8bit();
let dynamic_image = image.to_dynamic_image_with_options(0, &options)?;

See ConvertOptions for the options available, including the default behavior for each method.

Re-exports§

pub use image;
pub use ndarray;

Modules§

encapsulation: DICOM Pixel encapsulation

Structs§

ConvertOptions: Option set for converting decoded pixel data into other common data structures, such as a vector, an image, or a multidimensional array.
CreateLutError: The LUT could not be created: entry #{index} was mapped to {y_value}, which could not be cast to the target type.
DecodedPixelData: A blob of decoded pixel data.
Error: Error type for most pixel data related operations.
Lut: A look up table (LUT) for pixel data sample value transformations.
Rescale: Description of a modality rescale function, defined by a rescale slope and rescale intercept.
TranscodeError: An error occurred during the object transcoding process.
WindowLevel: The parameters of a single window level for a VOI LUT transformation, comprising the window center and the window width.
WindowLevelTransform: A full description of a VOI LUT function transformation based on a window level.

Enums§

AttributeName: An enum for a DICOM attribute which can be retrieved for the purposes of decoding pixel data.
BitDepthOption: Output image bit depth specifier.
ModalityLutOption: Modality LUT function specifier.
PhotometricInterpretation: A decoded representation of the DICOM Photometric Interpretation attribute.
PixelRepresentation: A decoded representation of the DICOM Pixel Representation attribute.
PlanarConfiguration: A decoded representation of the DICOM Planar Configuration attribute.
VoiLutFunction: A known DICOM Value of Interest (VOI) LUT function descriptor.
VoiLutOption: VOI LUT function specifier.

Traits§

PixelDecoder: Trait for objects which can be decoded into blobs of easily consumable pixel data.
Transcode: Interface for transcoding a DICOM object’s pixel data to comply with a different transfer syntax. Can be implemented by in-memory DICOM object representations as well as partial or lazy DICOM object readers, so that transcoding can be performed without loading the entire object.

Type Aliases§

Result
TranscodeResult: Alias for the result of transcoding a DICOM object.