#include "diplib.h"
dip::Image::View class

A view represents a subset of samples in an image. It can be assigned to to change those samples.

Contents

Objects of this class are meant as an interface for indexing into images. These objects reference a subset of pixels or samples within the image, and when assigned to, change those values. All indexing operators, by returning a view rather than a new image, thus allow also subscripted assignment, assignment of new values to a subset of pixels. For example:

dip::Image img = ...;
dip::Image mask = img < 0;
img.At( mask ) = -img.At( mask );

In the code above, img.At( mask ) returns a View object. Manipulating this object yields a new image with modified values. This image is then assigned into another View object, changing the values of the image img.

A dip::Image::View behaves just like a dip::Image, except for the assignment operator. It can be indexed using the At method in most of the same ways as a dip::Image, yielding a new View or a dip::Image::Pixel. It implicitly casts to a dip::Image, so it can be used as an input image to all functions. However, it cannot be used as an output image in function calls. Also, methods to dip::Image cannot be called on a View, cast the object to dip::Image first!

Note that when an irregular view (i.e. generated by a coordinate array or a mask image) is cast to a dip::Image, a 1D image is generated which does not share data with the original image. That is, the sample values are copied to the new image. When the view is regular (i.e. generated by a range per dimension), then the view is cast to an image that shares the data with the original image, and no data is copied.

See Indexing for more information.

Compound assignment operators are defined, but they currently do not do the computation in-place.

Constructors, destructors, assignment and conversion operators

auto operator=(dip::Image::View&& source) -> dip::Image::View&
Move assignment doesn’t move, this behaves in the same way as the copy assignment.
auto operator=(dip::Image::View const& source) -> dip::Image::View&
Assigning an image source to a view causes the pixels from source to be copied to the view. See dip::Image::View::Copy.
auto operator=(dip::Image const& source) -> dip::Image::View&
Assigning an image source to a view causes the pixels from source to be copied to the view. See dip::Image::View::Copy.
auto operator=(dip::Image::Pixel const& pixel) -> dip::Image::View&
Assigning a pixel to a view causes all pixels in the view to be set to the same value. See dip::Image::View::Fill.
auto operator=(dip::Image::Sample const& sample) -> dip::Image::View&
Assigning a sample to a view causes all samples in the view to be set to the same value. See dip::Image::View::Fill.

Classes

class Iterator
View iterator, similar in functionality to dip::GenericImageIterator.

Functions

void Copy(dip::Image::View const& source)
Copy the pixels from source to the view.
void Copy(dip::Image const& source)
Copy the pixels from source to the view.
auto Copy() const -> dip::Image
Creates a copy of the view as a new image. The output will not share data with the view.
void Fill(dip::Image::Pixel const& pixel)
Sets all pixels in the view to the value pixel.
void Fill(dip::Image::Sample const& sample)
Sets all samples in the view to the value sample.
auto At(dip::UnsignedArray const& coords) const -> dip::Image::Pixel
Extracts the pixel at the given coordinates.
template<typename T>
auto At(dip::UnsignedArray const& coords) const -> dip::Image::CastPixel
Same as above, but returns a type that implicitly casts to T.
auto At(dip::uint index) const -> dip::Image::Pixel
Extracts the pixel at the given linear index (inefficient if view is not 1D!).
template<typename T>
auto At(dip::uint index) const -> dip::Image::CastPixel
Same as above, but returns a type that implicitly casts to T.
auto At(dip::uint x_index, dip::uint y_index) const -> dip::Image::Pixel
Extracts the pixel at the given coordinates from a 2D view.
template<typename T>
auto At(dip::uint x_index, dip::uint y_index) const -> dip::Image::CastPixel
Same as above, but returns a type that implicitly casts to T.
auto At(dip::uint x_index, dip::uint y_index, dip::uint z_index) const -> dip::Image::Pixel
Extracts the pixel at the given coordinates from a 3D view.
template<typename T>
auto At(dip::uint x_index, dip::uint y_index, dip::uint z_index) const -> dip::Image::CastPixel
Same as above, but returns a type that implicitly casts to T.
auto At(dip::Range x_range) const -> dip::Image::View
Extracts a subset of pixels from a 1D view.
auto At(dip::Range x_range, dip::Range y_range) const -> dip::Image::View
Extracts a subset of pixels from a 2D view.
auto At(dip::Range x_range, dip::Range y_range, dip::Range z_range) const -> dip::Image::View
Extracts a subset of pixels from a 3D view.
auto At(dip::RangeArray ranges) const -> dip::Image::View
Extracts a subset of pixels from a view.
auto Dimensionality() const -> dip::uint
Returns the dimensionality of the view. Non-regular views (created by indexing using a mask image or a coordinate array) are always 1D.
auto TensorElements() const -> dip::uint
Returns the number of tensor elements of the view.
auto begin() const -> dip::Image::View::Iterator
Returns an iterator to the first pixel in the view.
auto end() const -> dip::Image::View::Iterator
Returns an iterator to one past the last pixel in the view.
auto IsRegular() const -> bool
Returns true if the view was obtained by regular indexing. If true, Mask and Offset will be empty.
auto Reference() const -> dip::Image const&
Returns the image being referenced.
auto Mask() const -> dip::Image const&
Returns the view’s mask image. Will only be forged if the view was created with a mask image.
auto Offsets() const -> dip::IntegerArray const&
Returns the view’s offsets into the referenced image. Will be empty if the view was not created using offsets.

Operators

auto operator[](dip::UnsignedArray const& indices) const -> dip::Image::View
Extract a tensor element, indices must have one or two elements.
auto operator[](dip::uint index) const -> dip::Image::View
Extract a tensor element using linear indexing.
auto operator[](dip::Range range) const -> dip::Image::View
Extract tensor elements using linear indexing.

Function documentation

void Copy(dip::Image::View const& source)

Copy the pixels from source to the view.

source must have the same number of tensor elements as this. If both source and this are a regular view, they must have identical sizes, except that trailing singleton dimensions are ignored. If either is a non-regular view, both views must have the same number of pixels, shapes are ignored. source pixel values are cast in the usual way to the type of this.

void Copy(dip::Image const& source)

Copy the pixels from source to the view.

source must have the same number of tensor elements as this, and be forged. For the case of a regular view, the view and source must have identical sizes, except that trailing singleton dimensions are ignored. For non-regular views, source must have the same number of pixels as the view, its shape is ignored. source pixel values are cast in the usual way to the type of this.

void Fill(dip::Image::Pixel const& pixel)

Sets all pixels in the view to the value pixel.

pixel must have the same number of tensor elements as the image, or be a scalar. Its values will be clipped to the target range and/or truncated, as applicable.

void Fill(dip::Image::Sample const& sample)

Sets all samples in the view to the value sample.

The value will be clipped to the target range and/or truncated, as applicable.

dip::Image const& Reference() const

Returns the image being referenced.

If IsRegular is true, the image contains only the referenced set of pixels, it is a subset of the image referenced. In this case, the returned image will be the same as that obtained from casting the view to an image.