LibraryLink Utilities  3.0.1
Modern C++ wrapper over LibraryLink and WSTP
LLU::Image< T > Class Template Reference

Description

template<typename T>
class LLU::Image< T >

This is a class template, where template parameter T is the type of data elements. Image is derived from MArray.

Image<> classes automate creation and deletion of MImages. They are strongly typed (no void* to underlying memory) and almost all functions from <algorithms> can be used on Image.

Template Parameters
T- type of underlying data
+ Inheritance diagram for LLU::Image< T >:
+ Collaboration diagram for LLU::Image< T >:

#include <Image.h>

Public Types

using value_type = T
 Type of elements stored. More...
 
using iterator = value_type *
 Iterator type. More...
 
using const_iterator = const value_type *
 Constant iterator type. More...
 
using reverse_iterator = std::reverse_iterator< iterator >
 Reverse iterator type. More...
 
using const_reverse_iterator = std::reverse_iterator< const_iterator >
 Constant reverse iterator type. More...
 
using reference = value_type &
 Reference type. More...
 
using const_reference = const value_type &
 Constant reference type. More...
 
using Container = Argument::CType< Type >
 The type of underlying LibraryLink structure (e.g. MTensor, MImage, etc.) will be called "Container". More...
 

Public Member Functions

 Image (mint w, mint h, mint channels, colorspace_t cs, bool interleavingQ)
 Constructs new 2D Image. More...
 
 Image (mint nFrames, mint w, mint h, mint channels, colorspace_t cs, bool interleavingQ)
 Constructs new 3D Image. More...
 
 Image (GenericImage im)
 Create new Image from a GenericImage. More...
 
 Image (MImage mi, Ownership owner)
 Constructs Image based on MImage. More...
 
 Image ()=default
 Default constructor - creates an empty wrapper. More...
 
Image clone () const
 Clone this Image, performing a deep copy of the underlying MImage. More...
 
template<typename U >
Image< U > convert (bool interleaved) const
 Copy this image with type conversion and explicitly specified interleaving. More...
 
template<typename U >
Image< U > convert () const
 Copy this image with type conversion and other properties (dimensions, interleaving, color space, etc.) untouched. More...
 
get (mint row, mint col, mint channel) const
 Get channel value at specified position in 2D image. More...
 
get (mint slice, mint row, mint col, mint channel) const
 Get channel value at specified position in 3D image. More...
 
void set (mint row, mint col, mint channel, T newValue)
 Set channel value at specified position in 2D image. More...
 
void set (mint slice, mint row, mint col, mint channel, T newValue)
 Set channel value at specified position in 3D image. More...
 
mint rank () const noexcept
 Get container rank. More...
 
bool empty () const noexcept
 Check whether container is empty. More...
 
mint dimension (mint index) const
 Get dimension value at position index. More...
 
const MArrayDimensionsdimensions () const
 Get a const reference to dimensions object. More...
 
T & operator[] (const std::vector< mint > &indices)
 Get a reference to the data element at given position in a multidimensional container. More...
 
const T & operator[] (const std::vector< mint > &indices) const
 Get a constant reference to the data element at given position in a multidimensional container. More...
 
reference operator[] (mint index)
 Get a reference to the data element at given position. More...
 
const_reference operator[] (mint index) const
 Get a constant reference to the data element at given position. More...
 
T & at (mint index)
 Get a reference to the data element at given position with bound checking. More...
 
const T & at (mint index) const
 Get a constant reference to the data element at given position with bound checking. More...
 
T & at (const std::vector< mint > &indices)
 Get a reference to the data element at given position in a multidimensional container. More...
 
const T & at (const std::vector< mint > &indices) const
 Get a constant reference to the data element at given position in a multidimensional container. More...
 
value_typedata () noexcept
 Get raw pointer to underlying data. More...
 
const value_typedata () const noexcept
 Get raw pointer to const underlying data. More...
 
mint size () const noexcept
 Get total number of elements in the container. More...
 
iterator begin () noexcept
 Get iterator at the beginning of underlying data. More...
 
const_iterator begin () const noexcept
 Get constant iterator at the beginning of underlying data. More...
 
const_iterator cbegin () const noexcept
 Get constant iterator at the beginning of underlying data. More...
 
iterator end () noexcept
 Get iterator after the end of underlying data. More...
 
const_iterator end () const noexcept
 Get constant iterator after the end of underlying data. More...
 
const_iterator cend () const noexcept
 Get constant iterator after the end of underlying data. More...
 
reverse_iterator rbegin () noexcept
 Get iterator at the beginning of underlying data. More...
 
const_reverse_iterator rbegin () const noexcept
 Get constant iterator at the beginning of underlying data. More...
 
const_reverse_iterator crbegin () const noexcept
 Get constant iterator at the beginning of underlying data. More...
 
reverse_iterator rend () noexcept
 Get iterator after the end of underlying data. More...
 
const_reverse_iterator rend () const noexcept
 Get constant iterator after the end of underlying data. More...
 
const_reverse_iterator crend () const noexcept
 Get constant iterator after the end of underlying data. More...
 
reference front ()
 Get reference to the first element. More...
 
const_reference front () const
 Get constant reference to the first element. More...
 
reference back ()
 Get reference to the last element. More...
 
const_reference back () const
 Get constant reference to the last element. More...
 
std::vector< value_typeasVector () const
 Copy contents of the data to a std::vector of matching type. More...
 
GenericImage convert (imagedata_t t, mbool interleavingQ) const
 Convert this object to a new GenericImage of given datatype, optionally changing interleaving. More...
 
GenericImage convert (imagedata_t t) const
 Convert this object to a new GenericImage of given datatype. More...
 
colorspace_t colorspace () const override
 Get colorspace which describes how colors are represented as numbers. More...
 
mint rows () const override
 Get number of rows. More...
 
mint columns () const override
 Get number of columns. More...
 
mint slices () const override
 Get number of slices. More...
 
mint channels () const override
 Get number of channels. More...
 
bool alphaChannelQ () const override
 Check if there is an alpha channel in the image. More...
 
bool interleavedQ () const override
 Check if the image is interleaved. More...
 
bool is3D () const override
 Check if the image is 3D. More...
 
mint getRank () const override
 Get rank. More...
 
mint getFlattenedLength () const override
 Get the total number of pixels in the image. More...
 
imagedata_t type () const override
 Get the data type of the image. More...
 
void * rawData () const override
 Get access to raw image data. More...
 
Container getContainer () const noexcept
 Get internal container. More...
 
Container abandonContainer () const noexcept
 Give a handle to internal container and stop owning it. More...
 
mint shareCount () const noexcept
 Return share count of internal container, if present and 0 otherwise. More...
 
void pass (MArgument &res) const
 Pass the internal container as result of a LibraryLink function. More...
 
Ownership getOwner () const noexcept
 Get ownership information. More...
 

Protected Member Functions

Container cloneContainer () const
 Clone the raw container, if it's present. More...
 
void disown () const noexcept
 Disown internal container if present. More...
 
void free () const noexcept
 Free internal container if present. More...
 
void reset (Container newCont, Ownership newOwnerMode=Ownership::Library) noexcept
 Set a new internal container safely disposing of the old one. More...
 

Type aliases documentation

◆ const_iterator

template<typename T >
using LLU::IterableContainer< T >::const_iterator = const value_type*
inherited

Constant iterator type.

◆ const_reference

template<typename T >
using LLU::IterableContainer< T >::const_reference = const value_type&
inherited

Constant reference type.

◆ const_reverse_iterator

template<typename T >
using LLU::IterableContainer< T >::const_reverse_iterator = std::reverse_iterator<const_iterator>
inherited

Constant reverse iterator type.

◆ Container

using LLU::MContainerBase< Type >::Container = Argument::CType<Type>
inherited

The type of underlying LibraryLink structure (e.g. MTensor, MImage, etc.) will be called "Container".

◆ iterator

template<typename T >
using LLU::IterableContainer< T >::iterator = value_type*
inherited

Iterator type.

◆ reference

template<typename T >
using LLU::IterableContainer< T >::reference = value_type&
inherited

Reference type.

◆ reverse_iterator

template<typename T >
using LLU::IterableContainer< T >::reverse_iterator = std::reverse_iterator<iterator>
inherited

Reverse iterator type.

◆ value_type

template<typename T >
using LLU::IterableContainer< T >::value_type = T
inherited

Type of elements stored.

Constructor & Destructor Documentation

◆ Image() [1/5]

template<typename T >
LLU::Image< T >::Image ( mint  w,
mint  h,
mint  channels,
colorspace_t  cs,
bool  interleavingQ 
)

Constructs new 2D Image.

Parameters
[in]w- Image width (number of columns)
[in]h- Image height (number of rows)
[in]channels- number of channels
[in]cs- color space
[in]interleavingQ- whether Image data should be interleaved

◆ Image() [2/5]

template<typename T >
LLU::Image< T >::Image ( mint  nFrames,
mint  w,
mint  h,
mint  channels,
colorspace_t  cs,
bool  interleavingQ 
)

Constructs new 3D Image.

Parameters
[in]nFrames- number of 2D frames/slices
[in]w- Image width (number of columns)
[in]h- Image height (number of rows)
[in]channels- number of channels
[in]cs- color space
[in]interleavingQ- whether Image data should be interleaved
Exceptions
ErrorName::ImageNewError- if internal MImage creation failed

◆ Image() [3/5]

template<typename T >
LLU::Image< T >::Image ( GenericImage< T >  im)
explicit

Create new Image from a GenericImage.

Parameters
[in]im- generic image to be wrapped into Image class
Exceptions
ErrorName::ImageTypeError- if the Image template type T does not match the actual data type of the generic image

◆ Image() [4/5]

template<typename T >
LLU::Image< T >::Image ( MImage< T >  mi,
Ownership  owner 
)
inline

Constructs Image based on MImage.

Parameters
[in]mi- LibraryLink structure to be wrapped
[in]owner- who manages the memory the raw MImage
Exceptions
ErrorName::ImageTypeError- if template parameter T does not match MImage data type
ErrorName::ImageSizeError- if constructor failed to calculate image dimensions properly

◆ Image() [5/5]

template<typename T >
LLU::Image< T >::Image ( )
default

Default constructor - creates an empty wrapper.

Member Function Documentation

◆ abandonContainer()

Container LLU::MContainerBase< Type >::abandonContainer
inlinenoexceptinherited

Give a handle to internal container and stop owning it.

Should be used with caution as it may potentially result with resource leak.

Returns
a handle to the internal container

◆ alphaChannelQ()

bool LLU::MContainer< MArgumentType::Image >::alphaChannelQ ( ) const
inlineoverridevirtualinherited

Check if there is an alpha channel in the image.

See also
http://reference.wolfram.com/language/LibraryLink/ref/callback/MImage_alphaChannelQ.html

Implements LLU::ImageInterface.

◆ asVector()

template<typename T >
std::vector<value_type> LLU::IterableContainer< T >::asVector ( ) const
inlineinherited

Copy contents of the data to a std::vector of matching type.

Returns
std::vector with the copy of the data

◆ at() [1/4]

template<typename T >
T & LLU::MArray< T >::at ( const std::vector< mint > &  indices)
inherited

Get a reference to the data element at given position in a multidimensional container.

Parameters
[in]indices- vector with coordinates of desired data element
Exceptions
indexError()- if indices are out-of-bounds

◆ at() [2/4]

template<typename T >
const T & LLU::MArray< T >::at ( const std::vector< mint > &  indices) const
inherited

Get a constant reference to the data element at given position in a multidimensional container.

Parameters
[in]indices- vector with coordinates of desired data element
Exceptions
indexError()- if indices are out-of-bounds

◆ at() [3/4]

template<typename T >
T & LLU::MArray< T >::at ( mint  index)
inherited

Get a reference to the data element at given position with bound checking.

Parameters
[in]index- position of desired data element
Exceptions
indexError()- if index is out-of-bounds

◆ at() [4/4]

template<typename T >
const T & LLU::MArray< T >::at ( mint  index) const
inherited

Get a constant reference to the data element at given position with bound checking.

Parameters
[in]index- position of desired data element
Exceptions
indexError()- if index is out-of-bounds

◆ back() [1/2]

template<typename T >
reference LLU::IterableContainer< T >::back ( )
inlineinherited

Get reference to the last element.

Note
For empty container the behavior is undefined.

◆ back() [2/2]

template<typename T >
const_reference LLU::IterableContainer< T >::back ( ) const
inlineinherited

Get constant reference to the last element.

Note
For empty container the behavior is undefined.

◆ begin() [1/2]

template<typename T >
const_iterator LLU::IterableContainer< T >::begin ( ) const
inlinenoexceptinherited

Get constant iterator at the beginning of underlying data.

◆ begin() [2/2]

template<typename T >
iterator LLU::IterableContainer< T >::begin ( )
inlinenoexceptinherited

Get iterator at the beginning of underlying data.

◆ cbegin()

template<typename T >
const_iterator LLU::IterableContainer< T >::cbegin ( ) const
inlinenoexceptinherited

Get constant iterator at the beginning of underlying data.

◆ cend()

template<typename T >
const_iterator LLU::IterableContainer< T >::cend ( ) const
inlinenoexceptinherited

Get constant iterator after the end of underlying data.

◆ channels()

mint LLU::MContainer< MArgumentType::Image >::channels ( ) const
inlineoverridevirtualinherited

◆ clone()

template<typename T >
Image< T > LLU::Image< T >::clone

Clone this Image, performing a deep copy of the underlying MImage.

Note
The cloned MImage always belongs to the library (Ownership::Library) because LibraryLink has no idea of its existence.
Returns
new Image

◆ cloneContainer()

Container LLU::MContainerBase< Type >::cloneContainer
inlineprotectedinherited

Clone the raw container, if it's present.

Returns
cloned container or nullptr if there is no internal container

◆ colorspace()

colorspace_t LLU::MContainer< MArgumentType::Image >::colorspace ( ) const
inlineoverridevirtualinherited

Get colorspace which describes how colors are represented as numbers.

See also
http://reference.wolfram.com/language/LibraryLink/ref/callback/MImage_getColorSpace.html

Implements LLU::ImageInterface.

◆ columns()

mint LLU::MContainer< MArgumentType::Image >::columns ( ) const
inlineoverridevirtualinherited

◆ convert() [1/4]

template<typename T >
template<typename U >
Image< U > LLU::Image< T >::convert

Copy this image with type conversion and other properties (dimensions, interleaving, color space, etc.) untouched.

Template Parameters
U- any type that Image supports
Returns
newly created Image of type U

◆ convert() [2/4]

template<typename T >
template<typename U >
Image< U > LLU::Image< T >::convert ( bool  interleaved) const

Copy this image with type conversion and explicitly specified interleaving.

Template Parameters
U- any type that Image supports
Parameters
[in]interleaved- whether the newly created Image should be interleaved
Returns
newly created Image of type U and specified interleaving

◆ convert() [3/4]

GenericImage LLU::MContainer< MArgumentType::Image >::convert ( imagedata_t  t) const
inlineinherited

Convert this object to a new GenericImage of given datatype.

Parameters
t- destination data type
Returns
converted GenericImage owned by the Library
See also
http://reference.wolfram.com/language/LibraryLink/ref/callback/MImage_convertType.html

◆ convert() [4/4]

GenericImage LLU::GenericImage::convert ( imagedata_t  t,
mbool  interleavingQ 
) const
inherited

Convert this object to a new GenericImage of given datatype, optionally changing interleaving.

Parameters
t- destination data type
interleavingQ- whether the converted GenericImage should be interleaved or not
Returns
converted GenericImage owned by the Library
See also
http://reference.wolfram.com/language/LibraryLink/ref/callback/MImage_convertType.html

◆ crbegin()

template<typename T >
const_reverse_iterator LLU::IterableContainer< T >::crbegin ( ) const
inlinenoexceptinherited

Get constant iterator at the beginning of underlying data.

◆ crend()

template<typename T >
const_reverse_iterator LLU::IterableContainer< T >::crend ( ) const
inlinenoexceptinherited

Get constant iterator after the end of underlying data.

◆ data() [1/2]

template<typename T >
const value_type* LLU::IterableContainer< T >::data ( ) const
inlinenoexceptinherited

Get raw pointer to const underlying data.

◆ data() [2/2]

template<typename T >
value_type* LLU::IterableContainer< T >::data ( )
inlinenoexceptinherited

Get raw pointer to underlying data.

◆ dimension()

template<typename T >
mint LLU::MArray< T >::dimension ( mint  index) const
inlineinherited

Get dimension value at position index.

◆ dimensions()

template<typename T >
const MArrayDimensions& LLU::MArray< T >::dimensions ( ) const
inlineinherited

Get a const reference to dimensions object.

◆ disown()

void LLU::MContainerBase< Type >::disown
inlineprotectednoexceptinherited

Disown internal container if present.

◆ empty()

template<typename T >
bool LLU::MArray< T >::empty ( ) const
inlinenoexceptinherited

Check whether container is empty.

◆ end() [1/2]

template<typename T >
const_iterator LLU::IterableContainer< T >::end ( ) const
inlinenoexceptinherited

Get constant iterator after the end of underlying data.

◆ end() [2/2]

template<typename T >
iterator LLU::IterableContainer< T >::end ( )
inlinenoexceptinherited

Get iterator after the end of underlying data.

◆ free()

void LLU::MContainerBase< Type >::free
inlineprotectednoexceptinherited

Free internal container if present.

◆ front() [1/2]

template<typename T >
reference LLU::IterableContainer< T >::front ( )
inlineinherited

Get reference to the first element.

Note
For empty container the behavior is undefined.

◆ front() [2/2]

template<typename T >
const_reference LLU::IterableContainer< T >::front ( ) const
inlineinherited

Get constant reference to the first element.

Note
For empty container the behavior is undefined.

◆ get() [1/2]

template<typename T >
T LLU::TypedImage< T >::get ( mint  row,
mint  col,
mint  channel 
) const
inlineinherited

Get channel value at specified position in 2D image.

Parameters
[in]row- pixel row (in Mathematica-style indexing - starting from 1)
[in]col- pixel column (in Mathematica-style indexing - starting from 1)
[in]channel- desired channel (in Mathematica-style indexing - starting from 1)
Exceptions
ErrorName::ImageIndexError- if the specified coordinates are out-of-bound

◆ get() [2/2]

template<typename T >
T LLU::TypedImage< T >::get ( mint  slice,
mint  row,
mint  col,
mint  channel 
) const
inlineinherited

Get channel value at specified position in 3D image.

Parameters
[in]slice- slice index (in Mathematica-style indexing - starting from 1)
[in]row- pixel row (in Mathematica-style indexing - starting from 1)
[in]col- pixel column (in Mathematica-style indexing - starting from 1)
[in]channel- desired channel (in Mathematica-style indexing - starting from 1)
Exceptions
ErrorName::ImageIndexError- if the specified coordinates are out-of-bound

◆ getContainer()

Container LLU::MContainerBase< Type >::getContainer
inlinenoexceptinherited

Get internal container.

Returns
a handle to the internal container

◆ getFlattenedLength()

mint LLU::MContainer< MArgumentType::Image >::getFlattenedLength ( ) const
inlineoverridevirtualinherited

◆ getOwner()

Ownership LLU::MContainerBase< Type >::getOwner
inlinenoexceptinherited

Get ownership information.

Returns
the owner of the internal container

◆ getRank()

mint LLU::MContainer< MArgumentType::Image >::getRank ( ) const
inlineoverridevirtualinherited

◆ interleavedQ()

bool LLU::MContainer< MArgumentType::Image >::interleavedQ ( ) const
inlineoverridevirtualinherited

◆ is3D()

bool LLU::MContainer< MArgumentType::Image >::is3D ( ) const
inlineoverridevirtualinherited

Check if the image is 3D.

Implements LLU::ImageInterface.

◆ operator[]() [1/4]

template<typename T >
T& LLU::MArray< T >::operator[] ( const std::vector< mint > &  indices)
inlineinherited

Get a reference to the data element at given position in a multidimensional container.

Parameters
[in]indices- vector with coordinates of desired data element

◆ operator[]() [2/4]

template<typename T >
const T& LLU::MArray< T >::operator[] ( const std::vector< mint > &  indices) const
inlineinherited

Get a constant reference to the data element at given position in a multidimensional container.

Parameters
[in]indices- vector with coordinates of desired data element

◆ operator[]() [3/4]

template<typename T >
reference LLU::IterableContainer< T >::operator[] ( mint  index)
inlineinherited

Get a reference to the data element at given position.

Parameters
[in]index- position of desired data element

◆ operator[]() [4/4]

template<typename T >
const_reference LLU::IterableContainer< T >::operator[] ( mint  index) const
inlineinherited

Get a constant reference to the data element at given position.

Parameters
[in]index- position of desired data element

◆ pass()

void LLU::MContainerBase< Type >::pass ( MArgument &  res) const
inlineinherited

Pass the internal container as result of a LibraryLink function.

Parameters
res- MArgument which will hold internal container of this MContainerBase

◆ rank()

template<typename T >
mint LLU::MArray< T >::rank ( ) const
inlinenoexceptinherited

Get container rank.

◆ rawData()

void* LLU::MContainer< MArgumentType::Image >::rawData ( ) const
inlineoverridevirtualinherited

Get access to raw image data.

Use with caution.

Returns
pointer to the raw data
See also
http://reference.wolfram.com/language/LibraryLink/ref/callback/MImage_getRawData.html

Implements LLU::ImageInterface.

◆ rbegin() [1/2]

template<typename T >
const_reverse_iterator LLU::IterableContainer< T >::rbegin ( ) const
inlinenoexceptinherited

Get constant iterator at the beginning of underlying data.

◆ rbegin() [2/2]

template<typename T >
reverse_iterator LLU::IterableContainer< T >::rbegin ( )
inlinenoexceptinherited

Get iterator at the beginning of underlying data.

◆ rend() [1/2]

template<typename T >
const_reverse_iterator LLU::IterableContainer< T >::rend ( ) const
inlinenoexceptinherited

Get constant iterator after the end of underlying data.

◆ rend() [2/2]

template<typename T >
reverse_iterator LLU::IterableContainer< T >::rend ( )
inlinenoexceptinherited

Get iterator after the end of underlying data.

◆ reset()

void LLU::MContainerBase< Type >::reset ( Container  newCont,
Ownership  newOwnerMode = Ownership::Library 
)
inlineprotectednoexceptinherited

Set a new internal container safely disposing of the old one.

Parameters
newCont- new internal container
newOwnerMode- owner of the new container

◆ rows()

mint LLU::MContainer< MArgumentType::Image >::rows ( ) const
inlineoverridevirtualinherited

◆ set() [1/2]

template<typename T >
void LLU::TypedImage< T >::set ( mint  row,
mint  col,
mint  channel,
newValue 
)
inlineinherited

Set channel value at specified position in 2D image.

Parameters
[in]row- pixel row (in Mathematica-style indexing - starting from 1)
[in]col- pixel column (in Mathematica-style indexing - starting from 1)
[in]channel- desired channel (in Mathematica-style indexing - starting from 1)
[in]newValue- new channel value
Exceptions
ErrorName::ImageIndexError- if the specified coordinates are out-of-bound

◆ set() [2/2]

template<typename T >
void LLU::TypedImage< T >::set ( mint  slice,
mint  row,
mint  col,
mint  channel,
newValue 
)
inlineinherited

Set channel value at specified position in 3D image.

Parameters
[in]slice- slice index (in Mathematica-style indexing - starting from 1)
[in]row- pixel row (in Mathematica-style indexing - starting from 1)
[in]col- pixel column (in Mathematica-style indexing - starting from 1)
[in]channel- desired channel (in Mathematica-style indexing - starting from 1)
[in]newValue- new channel value
Exceptions
ErrorName::ImageIndexError- if the specified coordinates are out-of-bound

◆ shareCount()

mint LLU::MContainerBase< Type >::shareCount
inlinenoexceptinherited

Return share count of internal container, if present and 0 otherwise.

◆ size()

template<typename T >
mint LLU::IterableContainer< T >::size ( ) const
inlinenoexceptinherited

Get total number of elements in the container.

◆ slices()

mint LLU::MContainer< MArgumentType::Image >::slices ( ) const
inlineoverridevirtualinherited

◆ type()

imagedata_t LLU::MContainer< MArgumentType::Image >::type ( ) const
inlineoverridevirtualinherited

Get the data type of the image.

Returns
type of elements (see definition of imagedata_t)
See also
http://reference.wolfram.com/language/LibraryLink/ref/callback/MImage_getDataType.html

Implements LLU::ImageInterface.