Pixel encapsulation

[dougyau]

Add the function to encapsulate a vector of frames. The function will return a PixelSequence which can be used with DataElement::new() to add the tag to the dataset.

let mut frames: Vec<Vec<u8>> = ...

let encapsulated_pixels = dicom::pixeldata::encaspulation::encapsulate(&mut frames, 1)?;
dcm.put(DataElement::new(dicom::dictionary_std::tags::PIXEL_DATA, dicom::core::VR::OB, encapsulated_pixels);

[dougyau]

I have done a refactor, to allow different kind of scenarios.

In the first scenario, you could use the simplest call. The bad part of this is that at some point, the input frames and the output frames are allocated.

let frames: Vec<Vec<u8>> = ...

let encapsulated_pixels = dicom::pixeldata::encapsulation::encapsulate(&mut frames, 1);
dcm.put(DataElement::new(dicom::dictionary_std::tags::PIXEL_DATA, dicom::core::VR::OB, encapsulated_pixels);

Now if memory is an issue (mostly when dealing with multiframe images) the frames can be processed individually.

let frames: Vec<Vec<u8>> = ...
let encapsulated_pixels = frames.
    .into_iter()
    .map(|frame| ...do some encoding)
    .for_each(|encoded_frame| encapsulated_pixels.add_frame(encoded_frame));

dcm.put(DataElement::new(dicom::dictionary_std::tags::PIXEL_DATA, dicom::core::VR::OB, encapsulated_pixels);

And the last way is useful when using rayon

let frames: Vec<Vec<u8>> = ...
let fragments = frames.
    .into_par_iter()
    .map(|frame| ...do some encoding)
    .flat_map(|encoded_frame| dicom::pixeldata::encapsulation::fragment_frame(encoded_frame, 1))
    .collect::<Vec<Vec<u8>>>;
let encapsulated_pixels = dicom::pixeldata::encapsulation::EncapsulatedPixels::from(fragments);

dcm.put(DataElement::new(dicom::dictionary_std::tags::PIXEL_DATA, dicom::core::VR::OB, encapsulated_pixels);

[dougyau]

@Enet4 I have improved the code based on the suggestions. Please let me know if you see more things that can be improved.

[dougyau]

@Enet4 I have updated the tests and the doc blocks on the PR.

[dougyau]

The changes have been implemented.