cvw::Image

Owning, type-safe image container parameterized by pixel format. More...

#include <image.hpp>

Public Types

	Name
using typename format_type::value_type	value_type Scalar element type derived from the pixel format.

Public Functions

	Name
	Image() =default Default-constructs an empty image.
	Image(int width, int height) Constructs an uninitialized image of the given dimensions.
	Image(int width, int height, value_type fill_value) Constructs an image filled with a uniform value.
	Image(cv::Mat image) Takes ownership of an existing cv::Mat.
cv::Mat &	mat() Returns a mutable reference to the underlying cv::Mat.
const cv::Mat &	mat() const Returns a const reference to the underlying cv::Mat.
int	width() const Returns the image width in pixels.
int	height() const Returns the image height in pixels.
constexpr int	channels() Returns the number of channels determined by the format.
size_t	size_bytes() const Returns the total number of bytes occupied by pixel data.
size_t	stride() const Returns the row stride in bytes.
bool	empty() const Checks whether the image contains no data.
value_type *	data() Returns a typed pointer to the beginning of pixel data.
const value_type *	data() const Returns a const typed pointer to the beginning of pixel data.
value_type &	at(int row, int col, int ch =0) Accesses a specific pixel channel by coordinates.
ImageView<format_type>	view() const Creates a read-only view over the image data.
ImageMutView<format_type>	mutable_view() const Creates a mutable view over the image data.
ImageView<const format_type>	const_view() const Creates a const view over the image data.
template <is_pixel_format target_format> expected< Image<target_format>, ConversionalError >	convert_to() const Converts the image to a different pixel format.
	Image(Image && ) =default Move-constructs from another Image.
Image &	operator=(Image && ) =default Move-assigns from another Image.
	Image(const Image & ) =delete Copy disabled.
Image &	operator=(const Image & ) =delete Copy disabled.
Image	clone() const Creates a deep copy of the image.

Detailed Description

cpp

template <is_pixel_format format_type>
class cvw::Image;

Owning, type-safe image container parameterized by pixel format.

Template Parameters:

format_type Pixel format tag satisfying is_pixel_format.

Since: 1.0.0

Note: Not thread-safe unless externally synchronized.

Manages pixel data through a cv::Mat backend. Supports move semantics only — copy is deleted to enforce single ownership. Provides zero-copy views, pixel access, and compile-time color conversion.

cpp

cvw::Image<cvw::BGR> img(640, 480);
auto gray = img.convert_to<cvw::Gray>();

Public Types Documentation

using value_type

cpp

using cvw::Image<format_type>::value_type =  typename format_type::value_type;

Scalar element type derived from the pixel format.

Public Functions Documentation

function Image

cpp

Image() =default

Default-constructs an empty image.

Since: 1.0.0

The image holds no data until assigned.

function Image

cpp

Image(
    int width,
    int height
)

Constructs an uninitialized image of the given dimensions.

Parameters:

width Image width in pixels. Must be positive.
height Image height in pixels. Must be positive.

Since: 1.0.0

function Image

cpp

Image(
    int width,
    int height,
    value_type fill_value
)

Constructs an image filled with a uniform value.

Parameters:

width Image width in pixels. Must be positive.
height Image height in pixels. Must be positive.
fill_value Value to fill every channel of every pixel.

Since: 1.0.0

function Image

cpp

explicit Image(
    cv::Mat image
)

Takes ownership of an existing cv::Mat.

Parameters:

image Source cv::Mat to transfer from.

Since: 1.0.0

The Mat is moved in; no pixel data is copied.

function mat

cpp

cv::Mat & mat()

Returns a mutable reference to the underlying cv::Mat.

Return: Reference to the internal cv::Mat.

Since: 1.0.0

function mat

cpp

const cv::Mat & mat() const

Returns a const reference to the underlying cv::Mat.

Return: Const reference to the internal cv::Mat.

Since: 1.0.0

function width

cpp

int width() const

Returns the image width in pixels.

Return: Width in pixels.

Since: 1.0.0

function height

cpp

int height() const

Returns the image height in pixels.

Return: Height in pixels.

Since: 1.0.0

function channels

cpp

inline constexprint channels()

Returns the number of channels determined by the format.

Return: Channel count (compile-time constant).

Since: 1.0.0

function size_bytes

cpp

size_t size_bytes() const

Returns the total number of bytes occupied by pixel data.

Return: Size in bytes.

Since: 1.0.0

function stride

cpp

size_t stride() const

Returns the row stride in bytes.

Return: Stride in bytes.

Since: 1.0.0

function empty

cpp

bool empty() const

Checks whether the image contains no data.

Return: True if the image is empty.

Since: 1.0.0

function data

cpp

value_type * data()

Returns a typed pointer to the beginning of pixel data.

Return: Mutable pointer to the first pixel element.

Since: 1.0.0

function data

cpp

constvalue_type * data() const

Returns a const typed pointer to the beginning of pixel data.

Return: Const pointer to the first pixel element.

Since: 1.0.0

function at

cpp

value_type & at(
    int row,
    int col,
    int ch =0
)

Accesses a specific pixel channel by coordinates.

Parameters:

row Row index. Unit: pixels. Valid range: [0, height).
col Column index. Unit: pixels. Valid range: [0, width).
ch Channel index. Default: 0. Valid range: [0, channels).

Exceptions:

None (bounds checking not performed).

Return: Mutable reference to the channel value.

Since: 1.0.0

Warning: No bounds checking; undefined behavior for out-of-range indices.

function view

cpp

ImageView<format_type> view() const

Creates a read-only view over the image data.

Return: An ImageView pointing to the same pixel buffer.

Since: 1.0.0

The view does not own the data; the source Image must outlive it.

function mutable_view

cpp

ImageMutView<format_type> mutable_view() const

Creates a mutable view over the image data.

Return: An ImageMutView pointing to the same pixel buffer.

Since: 1.0.0

The view does not own the data; the source Image must outlive it.

function const_view

cpp

ImageView<constformat_type> const_view() const

Creates a const view over the image data.

Return: An ImageView with const-qualified format tag.

Since: 1.0.0

function convert_to

cpp

template <is_pixel_format target_format>
expected< Image<target_format>, ConversionalError > convert_to() const

Converts the image to a different pixel format.

Exceptions:

None.

Template Parameters:

target_format Desired output pixel format.

Return: Expected containing the converted Image or a ConversionalError.

Since: 1.0.0

Note: Supported conversions are determined at compile time.

Performs color space conversion and/or type scaling at compile time. Returns an error if the conversion is not supported or the image is empty.

function Image

cpp

Image(
    Image && 
) =default

Move-constructs from another Image.

function operator=

cpp

Image & operator=(
    Image && 
) =default

Move-assigns from another Image.

function Image

cpp

Image(
    constImage & 
) =delete

Copy disabled.

function operator=

cpp

Image & operator=(
    constImage & 
) =delete

Copy disabled.

function clone

cpp

Image clone() const

Creates a deep copy of the image.

Return: An independent Image with identical contents.

Since: 1.0.0

Allocates new storage and copies all pixel data.

Updated on 2026-05-17 at 13:22:38 +0000

cvw::Image ​

Public Types ​

Public Functions ​

Detailed Description ​

Public Types Documentation ​

using value_type ​

Public Functions Documentation ​

function Image ​

function Image ​

function Image ​

function Image ​

function mat ​

function mat ​

function width ​

function height ​

function channels ​

function size_bytes ​

function stride ​

function empty ​

function data ​

function data ​

function at ​

function view ​

function mutable_view ​

function const_view ​

function convert_to ​

function Image ​

function operator= ​

function Image ​

function operator= ​

function clone ​

cvw::Image

Public Types

Public Functions

Detailed Description

Public Types Documentation

using value_type

Public Functions Documentation

function Image

function Image

function Image

function Image

function mat

function mat

function width

function height

function channels

function size_bytes

function stride

function empty

function data

function data

function at

function view

function mutable_view

function const_view

function convert_to

function Image

function operator=

function Image

function operator=

function clone