#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. more...

Functions

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 begin() const -> dip::Image::View::Iterator
Returns an iterator to the first pixel in the view.
void Copy(dip::Image::View const& source)
Copy the pixels from source to the view. more...
void Copy(dip::Image const& source)
Copy the pixels from source to the view. more...
auto Copy() const -> dip::Image
Creates a copy of the view as a new image. The output will not share data with the 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 end() const -> dip::Image::View::Iterator
Returns an iterator to one past the last pixel in the view.
void Fill(dip::Image::Pixel const& pixel)
Sets all pixels in the view to the value pixel. more...
void Fill(dip::Image::Sample const& sample)
Sets all samples in the view to the value sample. more...
auto IsRegular() const -> bool
Returns true if the view was obtained by regular indexing. If true, Mask and Offset will be empty.
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.
auto Reference() const -> dip::Image const&
Returns the image being referenced. more...
auto TensorElements() const -> dip::uint
Returns the number of tensor elements of the view.

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

dip::Image::View& operator=( dip::Image::View&& source)

Move assignment doesn’t move, this behaves in the same way as the copy assignment.

dip::Image::View& operator=( dip::Image::View const& source)

Assigning an image source to a view causes the pixels from source to be copied to the view. See dip::Image::View::Copy.

dip::Image::View& operator=( dip::Image const& source)

Assigning an image source to a view causes the pixels from source to be copied to the view. See dip::Image::View::Copy.

dip::Image::View& operator=( dip::Image::Pixel const& pixel)

Assigning a pixel to a view causes all pixels in the view to be set to the same value. See dip::Image::View::Fill.

dip::Image::View& operator=( dip::Image::Sample const& sample)

Assigning a sample to a view causes all samples in the view to be set to the same value. See dip::Image::View::Fill.

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.

dip::Image Copy( ) const

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.

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::Pixel At( dip::UnsignedArray const& coords) const

Extracts the pixel at the given coordinates.

template<typename T>
dip::Image::CastPixel At( dip::UnsignedArray const& coords) const

Same as above, but returns a type that implicitly casts to T.

dip::Image::Pixel At( dip::uint index) const

Extracts the pixel at the given linear index (inefficient if view is not 1D!).

template<typename T>
dip::Image::CastPixel At( dip::uint index) const

Same as above, but returns a type that implicitly casts to T.

dip::Image::Pixel At( dip::uint x_index, dip::uint y_index) const

Extracts the pixel at the given coordinates from a 2D view.

template<typename T>
dip::Image::CastPixel At( dip::uint x_index, dip::uint y_index) const

Same as above, but returns a type that implicitly casts to T.

dip::Image::Pixel At( dip::uint x_index, dip::uint y_index, dip::uint z_index) const

Extracts the pixel at the given coordinates from a 3D view.

template<typename T>
dip::Image::CastPixel At( dip::uint x_index, dip::uint y_index, dip::uint z_index) const

Same as above, but returns a type that implicitly casts to T.

dip::Image::View At( dip::Range x_range) const

Extracts a subset of pixels from a 1D view.

dip::Image::View At( dip::Range x_range, dip::Range y_range) const

Extracts a subset of pixels from a 2D view.

dip::Image::View At( dip::Range x_range, dip::Range y_range, dip::Range z_range) const

Extracts a subset of pixels from a 3D view.

dip::Image::View At( dip::RangeArray ranges) const

Extracts a subset of pixels from a view.

dip::uint Dimensionality( ) const

Returns the dimensionality of the view. Non-regular views (created by indexing using a mask image or a coordinate array) are always 1D.

dip::uint TensorElements( ) const

Returns the number of tensor elements of the view.

dip::Image::View::Iterator begin( ) const

Returns an iterator to the first pixel in the view.

dip::Image::View::Iterator end( ) const

Returns an iterator to one past the last pixel in the view.

bool IsRegular( ) const

Returns true if the view was obtained by regular indexing. If true, Mask and Offset will be empty.

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.

dip::Image const& Mask( ) const

Returns the view’s mask image. Will only be forged if the view was created with a mask image.

dip::IntegerArray const& Offsets( ) const

Returns the view’s offsets into the referenced image. Will be empty if the view was not created using offsets.

dip::Image::View operator[]( dip::UnsignedArray const& indices) const

Extract a tensor element, indices must have one or two elements.

dip::Image::View operator[]( dip::uint index) const

Extract a tensor element using linear indexing.

dip::Image::View operator[]( dip::Range range) const

Extract tensor elements using linear indexing.