Struct DeepImage

pub struct DeepImage(/* private fields */);

An in-memory data structure that can hold an arbitrary OpenEXR image with one or multiple resolution levels, and with an arbitrary set of channels.

An image is a container for a set of image levels, and an image level is a container for a set of image channels. An image channel contains an array of pixel values of type f16, f32 or u32.

For example:

    image ──┬── level 0 ──┬── channel "R" ─── pixel data
            │             │
            │             ├── channel "G" ─── pixel data
            │             │
            │             └── channel "B" ─── pixel data
            │
            ├── level 1 ──┬── channel "R" ─── pixel data
            │             │
            │             ├── channel "G" ─── pixel data
            │             │
            │             └── channel "B" ─── pixel data
            │
            └── level 2 ──┬── channel "R" ─── pixel data
                          │
                          ├── channel "G" ─── pixel data
                          │
                          └── channel "B" ─── pixel data

An image has a level mode, which can be LevelMode::OneLevel, LevelMode::MipmapLevels or LevelMode::RipmapLevels, and a level rounding mode, which can be LevelRoundingMode::RoundUp or LevelRoundingMode::RoundDown. Together, the level mode and the level rounding mode determine how many levels an image contains, and how large the data window for each level is. All levels in an image have the same set of channels.

An image channel has a name (e.g. “R”, “Z”, or “xVelocity”), a type (CHANNEL_HALF, CHANNEL_FLOAT or CHANNEL_UINT) and x and y sampling rates. A channel stores samples for a pixel if the pixel is inside the data window of the level to which the channel belongs, and the x and y coordinates of the pixel are divisible by the x and y sampling rates of the channel.

In a flat image each channel in each level stores at most one value per pixel.

Implementations

impl DeepImage

pub fn new<B: Bound2<i32>>( data_window: B, level_mode: LevelMode, level_rounding_mode: LevelRoundingMode, ) -> Result<DeepImage, Error>

Constructs a new DeepImage with the given data_window, level_mode and level_rounding_mode

Errors

• Error::Base - if any error occurs

pub fn level_mode(&self) -> LevelMode

Get the level mode

pub fn level_rounding_mode(&self) -> LevelRoundingMode

Get the level rounding mode

pub fn num_levels(&self) -> Result<i32, Error>

Get the number of levels in the image.

This is a convenience function for use with mipmaps, in which case this function is equivalent to num_x_levels().

If this image’s level mode is LevelMode::RipmapLevels, you must call num_x_levels() or num_y_levels instead.

Errors

• Error::LogicError - if this image’s level mode is LevelMode::RipmapLevels

pub fn num_x_levels(&self) -> i32

Returns the image’s number of levels in the x direction.

Returns

• 1 if level_mode() is LevelMode::OneLevel
• rfunc(log(max(w, h)) / log(2)) + 1 if level_mode() is LevelMode::MipmapLevels
• rfunc(log(w) / log(2)) + 1 if level_mode() is LevelMode::RipmapLevels

Where:

• w is the width of the image’s data window, max.x - min.x + 1,
• h is the height of the image’s data window, max.y - min.y + 1,
• and rfunc is either floor() or ceil() depending on whether level_rounding_mode() is LevelRoundingMode::RoundUp or LevelRoundingMode::RoundDown

pub fn num_y_levels(&self) -> i32

Returns the image’s number of levels in the y direction.

Returns

• Same as num_x_levels() if level_mode() is LevelMode::OneLevel or LevelMode::MipmapLevels
• rfunc(log(h) / log(2)) + 1 if level_mode() is LevelMode::RipmapLevels

Where:

• h is the height of the image’s data window, max.y - min.y + 1,
• and rfunc is either floor() or ceil() depending on whether level_rounding_mode() is LevelRoundingMode::RoundUp or LevelRoundingMode::RoundDown

pub fn data_window<B: Bound2<i32>>(&self) -> &B

Returns the data window for the whole image.

Equivalent to data_window_for_level(0, 0).

pub fn data_window_for_level<B: Bound2<i32>>( &self, lx: i32, ly: i32, ) -> Result<&B, Error>

Returns the data window for the image at level (lx, ly).

That is, the window for which the image level with level number (lx, ly) has allocated pixel storage.

Returns

A reference to a Bound2<i32> with min value (dataWindow().min.x, dataWindow().min.y) and max value (dataWindow().min.x + levelWidth(lx) - 1, dataWindow().min.y + levelHeight(ly) - 1)

Errors

• Error::InvalidArgument - if (lx, ly) does not correspond to a valid image level.

pub fn level_width(&self, lx: i32) -> Result<i32, Error>

Returns the width of a level with level number (lx, *), where * is any number.

Returns

max (1, rfunc (w / pow (2, lx)))

Errors

• Error::InvalidArgument - if lx is not a valid level number

pub fn level_height(&self, ly: i32) -> Result<i32, Error>

Returns the height of a level with level number (*, ly), where * is any number.

Returns

max (1, rfunc (y / pow (2, ly)))

Errors

• Error::InvalidArgument - if ly is not a valid level number

pub fn resize<B: Bound2<i32>>( &mut self, dw: B, lm: LevelMode, lrm: LevelRoundingMode, ) -> Result<(), Error>

Resize the image.

Sets the data window of the image to dw, sets the level mode to lm and the level rounding mode to lrm, and allocates new storage for image levels and image channels. The set of channels in the image does not change.

The contents of the image are lost; pixel data are not preserved across the resize operation. If resizing fails, then the image will be left with an empty data window and no image levels.

Errors

*Error::Base - if any error occurs. The image will be set to empty in this case.

pub fn shift_pixels(&mut self, dx: i32, dy: i32) -> Result<(), Error>

Shift the pixels and the data window of an image.

Shifts the image by dx pixels horizontally and dy pixels vertically.
A pixel at location (x,y) moves to position (x+dx, y+dy). The data window of the image is shifted along with the pixels. No pixel data are lost.

The horizontal and vertical shift distances must be multiples of the x and y sampling rates of all image channels. If they are not, Error::InvalidArgument is returned and this method has no effect.

pub fn insert_channel( &mut self, name: &str, channel: &Channel, ) -> Result<(), Error>

Insert a new channel into the image.

The arguments to this function are the same as for adding a a channel to a Header: channel name, x and y sampling rates, and a “perceptually approximately linear” flag.

If the image already contains a channel with the same name as the new name then the existing channel is deleted before the new channel is added.

Errors

• Error::Base - if any error occurs

pub fn erase_channel(&mut self, name: &str)

Erase the channel name from the image

If no channel called name is in the image, this method has no effect.

pub fn clear_channels(&mut self)

Erase all channels from the image.

pub fn rename_channel( &mut self, old_name: &str, new_name: &str, ) -> Result<(), Error>

Rename the channel old_name to have the name new_name

Errors

Error::InvalidArgument - if a channel called new_name already exists, or if no channel named old_name exists. Error::OutOfMemory - if allocation fails, in which case the channel being renamed is erased.

pub fn level(&self, lx: i32, ly: i32) -> Result<DeepImageLevelRef<'_>, Error>

Access image level with number (lx, ly)

Errors

• Error::InvalidArgument - if (lx, ly) does not refer to a valid image level.

pub fn level_mut( &self, lx: i32, ly: i32, ) -> Result<DeepImageLevelRefMut<'_>, Error>

Access image level with number (lx, ly) as a mutable ref.

Errors

• Error::InvalidArgument - if (lx, ly) does not refer to a valid image level.

Trait Implementations

impl Default for DeepImage

fn default() -> DeepImage

Constructs a DeepImage with an empty data window, LevelMode::OneLevel level and LevelRoundingMode::RoundDown

impl Drop for DeepImage

fn drop(&mut self)

Executes the destructor for this type.

impl OpaquePtr for DeepImage

type SysPointee = Imf_3_0__DeepImage_t

type Pointee = DeepImage