cvw

Namespaces

Name
cvw::detail Internal validation helpers used by algorithm implementations.
cvw::pipe_ops Namespace containing operator
cvw::steps Namespace containing step factory functions for pipeline composition.

Classes

	Name
class	cvw::bad_expected_access Exception thrown when accessing the value of an expected that contains an error.
class	cvw::bad_expected_access<void> Specialization of bad_expected_access for void error type.
class	cvw::expected A wrapper that contains either a value or an error.
class	cvw::expected<void, E> Specialization of expected for void value type.
class	cvw::Image Owning, type-safe image container parameterized by pixel format.
class	cvw::ImageBuilder Factory class for loading images from disk in a specific format.
class	cvw::ImageMutView Mutable, non-owning view over image pixel data.
class	cvw::ImageView Read-only, non-owning view over image pixel data.
struct	cvw::unexpect_t Tag type for constructing expected in error state.
class	cvw::unexpected Wrapper type for constructing expected objects in error state.
struct	cvw::YUYV Blue-Green-Red, 8-bit per channel. 3 channels.

Types

	Name
enum class uint8_t	AlgorithmError { EmptyInput, InvalidParameter, InternalError, SaveFailed, LoadFailed} Error codes returned by image processing algorithms.
enum class uint8_t	ConversionalError { InternalError} Error codes returned by Image format conversion operations.
enum class uint8_t	LoadError { FileOpenFailed, UnsupportedConversion} Error codes returned by image loading operations.
enum class uint8_t	ConvertionalError { InternalError, UnsupportedFormat} Error codes for Qt/OpenCV conversion operations.
enum class uint8_t	ConvertionalMethod { Copy, Shared} Memory management strategy for conversion operations.

Functions

	Name
expected< Image<Gray>, AlgorithmError >	to_gray(Image<BGR> img) Converts a BGR image to 8-bit grayscale.
expected< Image<Gray>, AlgorithmError >	to_gray(Image<RGB> img) Converts an RGB image to 8-bit grayscale.
expected< Image<Gray>, AlgorithmError >	to_gray(ImageView<BGR> view) Converts a BGR view to 8-bit grayscale.
expected< Image<BGR>, AlgorithmError >	to_bgr(Image<Gray> img) Converts a grayscale image to BGR.
expected< Image<Gray>, AlgorithmError >	yuyv_to_gray(ImageView<YUYV> view) Extracts luminance from a YUYV packed view.
expected< Image<Gray>, AlgorithmError >	canny(Image<Gray> img, double threshold_lo, double threshold_hi, int aperture_size =3) Applies Canny edge detection to a grayscale image.
expected< Image<Float1>, AlgorithmError >	sobel(Image<Gray> img, int dx, int dy, int kernel_size =3) Computes Sobel derivatives on a grayscale image.
template <is_pixel_format F> expected< Image<F>, AlgorithmError >	gaussian_blur(Image<F> img, int kernel_size, double sigma =0.0) Applies Gaussian blur to an image.
template <is_pixel_format F> expected< Image<F>, AlgorithmError >	median_blur(Image<F> img, int kernel_size) Applies median blur to a single-channel image.
template <is_pixel_format F> expected< Image<F>, AlgorithmError >	resize(Image<F> img, int width, int height, int interpolation =cv::INTER_LINEAR) Resizes an image to the specified dimensions.
template <is_pixel_format F> expected< Image<F>, AlgorithmError >	flip(Image<F> img, int axis) Flips an image along the specified axis.
template <is_pixel_format F> expected< Image<F>, AlgorithmError >	rotate(Image<F> img, double angle, bool expand =false) Rotates an image around its center.
template <is_pixel_format F =BGR> expected< Image<F>, AlgorithmError >	load(std::string_view path) Loads an image from disk in the specified pixel format.
template <is_pixel_format F> expected<void, AlgorithmError>	save(const Image<F> & img, std::string_view path) Saves an image to disk.
expected< Image<Float1>, AlgorithmError >	normalize(Image<Gray> img, float min_val =0.0f, float max_val =1.0f) Normalizes a grayscale image to a Float1 range.
expected< Image<Gray>, AlgorithmError >	threshold(Image<Gray> img, double thresh, double max_val, int type =cv::THRESH_BINARY) Applies a fixed-level threshold to a grayscale image.
expected< Image<Gray>, AlgorithmError >	adaptive_threshold(Image<Gray> img, int block_size, double C, int method =cv::ADAPTIVE_THRESH_GAUSSIAN_C) Applies adaptive thresholding to a grayscale image.
template <typename... Steps> auto	make_pipeline(Steps &&... steps) Creates a reusable pipeline from multiple step callables.
template <ConvertionalMethod Method> cvw::expected<QImage, ConvertionalError>	from_cv(const cv::Mat & mat) Converts a cv::Mat to a QImage.
template <ConvertionalMethod Method> cvw::expected<cv::Mat, ConvertionalError>	to_cv(const QImage & image) Converts a QImage to a cv::Mat.
template <is_pixel_format F> cvw::expected<QImage, ConvertionalError>	to_qimage_view(const Image<F> & img) Converts an Image to a QImage via shared memory.
template <is_pixel_format F> cvw::expected<QImage, ConvertionalError>	to_qimage_copy(const Image<F> & img) Converts an Image to a QImage via deep copy.

Attributes

	Name
constexpr unexpect_t	unexpect Global unexpect tag instance.
constexpr size_t	bytes_size Computes the number of bytes occupied by one pixel of the given format at compile time.

Types Documentation

enum AlgorithmError

Enumerator	Value	Description
EmptyInput		Input image or view contains no data.
InvalidParameter		A numeric parameter is out of valid range.
InternalError		An unrecoverable internal error occurred.
SaveFailed		Writing the output file failed.
LoadFailed		Reading the input file failed.

Error codes returned by image processing algorithms.

Since: 1.0.0

enum ConversionalError

Enumerator	Value	Description
InternalError		Conversion failed due to an internal error.

Error codes returned by Image format conversion operations.

Since: 1.0.0

enum LoadError

Enumerator	Value	Description
FileOpenFailed		File could not be opened or does not exist.
UnsupportedConversion		No conversion path to the target format.

Error codes returned by image loading operations.

Since: 1.0.0

enum ConvertionalError

Enumerator	Value	Description
InternalError		Source data is empty or null.
UnsupportedFormat		Pixel format has no conversion path.

Error codes for Qt/OpenCV conversion operations.

Since: 1.0.0

enum ConvertionalMethod

Enumerator	Value	Description
Copy		Deep copy; result owns its pixel data.
Shared		Shared memory; result references the source buffer.

Memory management strategy for conversion operations.

Since: 1.0.0

Functions Documentation

function to_gray

cpp

inline expected< Image<Gray>, AlgorithmError > to_gray(
    Image<BGR> img
)

Converts a BGR image to 8-bit grayscale.

Parameters:

img Source BGR image. Must not be empty.

Exceptions:

None.

Return: Expected containing Image<Gray> or AlgorithmError.

Since: 1.0.0

function to_gray

cpp

inline expected< Image<Gray>, AlgorithmError > to_gray(
    Image<RGB> img
)

Converts an RGB image to 8-bit grayscale.

Parameters:

img Source RGB image. Must not be empty.

Exceptions:

None.

Return: Expected containing Image<Gray> or AlgorithmError.

Since: 1.0.0

function to_gray

cpp

inline expected< Image<Gray>, AlgorithmError > to_gray(
    ImageView<BGR> view
)

Converts a BGR view to 8-bit grayscale.

Parameters:

view Source BGR view. Must not be empty.

Exceptions:

None.

Return: Expected containing Image<Gray> or AlgorithmError.

Since: 1.0.0

Note: The view data is not modified.

Creates a temporary cv::Mat header from the view data and performs the conversion without copying the input.

function to_bgr

cpp

inline expected< Image<BGR>, AlgorithmError > to_bgr(
    Image<Gray> img
)

Converts a grayscale image to BGR.

Parameters:

img Source grayscale image. Must not be empty.

Exceptions:

None.

Return: Expected containing Image<BGR> or AlgorithmError.

Since: 1.0.0

Replicates the single channel across B, G, R.

function yuyv_to_gray

cpp

inline expected< Image<Gray>, AlgorithmError > yuyv_to_gray(
    ImageView<YUYV> view
)

Extracts luminance from a YUYV packed view.

Parameters:

view Source YUYV view. Must not be empty.

Exceptions:

None.

Return: Expected containing Image<Gray> or AlgorithmError.

Since: 1.0.0

Samples the Y component from each pixel pair, producing a single-channel 8-bit grayscale image.

function canny

cpp

inline expected< Image<Gray>, AlgorithmError > canny(
    Image<Gray> img,
    double threshold_lo,
    double threshold_hi,
    int aperture_size =3
)

Applies Canny edge detection to a grayscale image.

Parameters:

img Source grayscale image. Must not be empty.
threshold_lo Lower hysteresis threshold.
threshold_hi Upper hysteresis threshold.
aperture_size Aperture size for Sobel operator. Default: 3.

Exceptions:

None.

Return: Expected containing Image<Gray> with edges or AlgorithmError.

Since: 1.0.0

function sobel

cpp

inline expected< Image<Float1>, AlgorithmError > sobel(
    Image<Gray> img,
    int dx,
    int dy,
    int kernel_size =3
)

Computes Sobel derivatives on a grayscale image.

Parameters:

img Source grayscale image. Must not be empty.
dx Order of the x-derivative.
dy Order of the y-derivative.
kernel_size Aperture size. Default: 3.

Exceptions:

None.

Return: Expected containing Image<Float1> with derivatives or AlgorithmError.

Since: 1.0.0

Note: Output is 32-bit float regardless of input depth.

function gaussian_blur

cpp

template <is_pixel_format F>
inline expected< Image<F>, AlgorithmError > gaussian_blur(
    Image<F> img,
    int kernel_size,
    double sigma =0.0
)

Applies Gaussian blur to an image.

Parameters:

img Source image. Must not be empty.
kernel_size Side length of the square kernel. Must be odd and positive. Unit: pixels.
sigma Standard deviation. 0.0 means computed from kernel size. Default: 0.0.

Exceptions:

None.

Template Parameters:

F Pixel format tag.

Return: Expected containing the blurred Image or AlgorithmError.

Since: 1.0.0

function median_blur

cpp

template <is_pixel_format F>
inline expected< Image<F>, AlgorithmError > median_blur(
    Image<F> img,
    int kernel_size
)

Applies median blur to a single-channel image.

Parameters:

img Source image. Must not be empty.
kernel_size Side length of the square kernel. Must be odd. Unit: pixels.

Exceptions:

None.

Template Parameters:

F Pixel format with exactly 1 channel.

Return: Expected containing the filtered Image or AlgorithmError.

Since: 1.0.0

Concept-constrained to single-channel formats only.

function resize

cpp

template <is_pixel_format F>
inline expected< Image<F>, AlgorithmError > resize(
    Image<F> img,
    int width,
    int height,
    int interpolation =cv::INTER_LINEAR
)

Resizes an image to the specified dimensions.

Parameters:

img Source image. Must not be empty.
width Target width in pixels. Must be positive.
height Target height in pixels. Must be positive.
interpolation OpenCV interpolation flag. Default: LINEAR.

Exceptions:

None.

Template Parameters:

F Pixel format tag.

Return: Expected containing the resized Image or AlgorithmError.

Since: 1.0.0

function flip

cpp

template <is_pixel_format F>
inline expected< Image<F>, AlgorithmError > flip(
    Image<F> img,
    int axis
)

Flips an image along the specified axis.

Parameters:

img Source image. Must not be empty.
axis 0 = vertical, 1 = horizontal, -1 = both axes.

Exceptions:

None.

Template Parameters:

F Pixel format tag.

Return: Expected containing the flipped Image or AlgorithmError.

Since: 1.0.0

Note: Operates in-place; the input image buffer is reused.

function rotate

cpp

template <is_pixel_format F>
inline expected< Image<F>, AlgorithmError > rotate(
    Image<F> img,
    double angle,
    bool expand =false
)

Rotates an image around its center.

Parameters:

img Source image. Must not be empty.
angle Rotation angle in degrees. Positive is counter-clockwise.
expand Whether to expand the output canvas to fit the full rotated image. Default: false.

Exceptions:

None.

Template Parameters:

F Pixel format tag.

Return: Expected containing the rotated Image or AlgorithmError.

Since: 1.0.0

function load

cpp

template <is_pixel_format F =BGR>
inline expected< Image<F>, AlgorithmError > load(
    std::string_view path
)

Loads an image from disk in the specified pixel format.

Parameters:

path Filesystem path to the image file.

Exceptions:

None.

Template Parameters:

F Desired pixel format. Default: BGR.

Return: Expected containing the loaded Image or AlgorithmError.

Since: 1.0.0

Delegates to ImageBuilder for the actual loading and conversion.

function save

cpp

template <is_pixel_format F>
inline expected<void, AlgorithmError> save(
    constImage<F> & img,
    std::string_view path
)

Saves an image to disk.

Parameters:

img Source image. Must not be empty.
path Output file path. Extension determines the format.

Exceptions:

None.

Template Parameters:

F Pixel format of the image.

Return: Expected void on success, or AlgorithmError.

Since: 1.0.0

function normalize

cpp

inline expected< Image<Float1>, AlgorithmError > normalize(
    Image<Gray> img,
    float min_val =0.0f,
    float max_val =1.0f
)

Normalizes a grayscale image to a Float1 range.

Parameters:

img Source grayscale image. Must not be empty.
min_val Lower bound of the output range. Default: 0.0f.
max_val Upper bound of the output range. Default: 1.0f.

Exceptions:

None.

Return: Expected containing Image<Float1> or AlgorithmError.

Since: 1.0.0

Scales pixel values so that they fall within [min_val, max_val] using min-max normalization.

function threshold

cpp

inline expected< Image<Gray>, AlgorithmError > threshold(
    Image<Gray> img,
    double thresh,
    double max_val,
    int type =cv::THRESH_BINARY
)

Applies a fixed-level threshold to a grayscale image.

Parameters:

img Source grayscale image. Must not be empty.
thresh Threshold value.
max_val Maximum value for THRESH_BINARY. Default: 0.
type OpenCV threshold type. Default: THRESH_BINARY.

Exceptions:

None.

Return: Expected containing the thresholded Image<Gray> or AlgorithmError.

Since: 1.0.0

function adaptive_threshold

cpp

inline expected< Image<Gray>, AlgorithmError > adaptive_threshold(
    Image<Gray> img,
    int block_size,
    double C,
    int method =cv::ADAPTIVE_THRESH_GAUSSIAN_C
)

Applies adaptive thresholding to a grayscale image.

Parameters:

img Source grayscale image. Must not be empty.
block_size Size of the local neighborhood. Must be odd and >= 3. Unit: pixels.
C Constant subtracted from the mean. May be negative.
method Adaptive method. Default: ADAPTIVE_THRESH_GAUSSIAN_C.

Exceptions:

None.

Return: Expected containing the thresholded Image<Gray> or AlgorithmError.

Since: 1.0.0

function make_pipeline

cpp

template <typename... Steps>
auto make_pipeline(
    Steps &&... steps
)

Creates a reusable pipeline from multiple step callables.

Parameters:

steps Step callables to compose.

Template Parameters:

Steps Types of step callables.

Return: A callable pipeline object.

Since: 1.0.0

Composes all steps into a single callable that applies them in order, short-circuiting on the first error.

cpp

auto pipe = cvw::make_pipeline(
    cvw::steps::to_gray(),
    cvw::steps::gaussian_blur(5),
    cvw::steps::canny(50, 150)
);
auto result = pipe(some_bgr_image);

function from_cv

cpp

template <ConvertionalMethod Method>
inline cvw::expected<QImage, ConvertionalError> from_cv(
    const cv::Mat & mat
)

Converts a cv::Mat to a QImage.

Parameters:

mat Source cv::Mat. Must not be empty.

Exceptions:

None.

Template Parameters:

Method Copy or Shared memory mode.

Return: Expected containing a QImage or ConvertionalError.

Since: 1.0.0

Warning: In Shared mode, the source cv::Mat must outlive the returned QImage.

Supports 8-bit grayscale (CV_8UC1), RGB888 (CV_8UC3), and RGBA8888 (CV_8UC4) formats. Note: OpenCV uses BGR channel order; convert before calling if correct color ordering is required.

function to_cv

cpp

template <ConvertionalMethod Method>
inline cvw::expected<cv::Mat, ConvertionalError> to_cv(
    constQImage & image
)

Converts a QImage to a cv::Mat.

Parameters:

image Source QImage. Must not be null.

Exceptions:

None.

Template Parameters:

Method Copy or Shared memory mode.

Return: Expected containing a cv::Mat or ConvertionalError.

Since: 1.0.0

Warning: In Shared mode, the source QImage must outlive the returned cv::Mat.

Supports Grayscale8, RGB888, RGBA8888, and ARGB32 formats.

function to_qimage_view

cpp

template <is_pixel_format F>
inline cvw::expected<QImage, ConvertionalError> to_qimage_view(
    constImage<F> & img
)

Converts an Image to a QImage via shared memory.

Parameters:

img Source Image.

Exceptions:

None.

Template Parameters:

F Pixel format tag.

Return: Expected containing a QImage or ConvertionalError.

Since: 1.0.0

Warning: Shared memory: the source Image must outlive the result.

The returned QImage references the Image's internal buffer; the Image must outlive the QImage.

function to_qimage_copy

cpp

template <is_pixel_format F>
inline cvw::expected<QImage, ConvertionalError> to_qimage_copy(
    constImage<F> & img
)

Converts an Image to a QImage via deep copy.

Parameters:

img Source Image.

Exceptions:

None.

Template Parameters:

F Pixel format tag.

Return: Expected containing a QImage or ConvertionalError.

Since: 1.0.0

The returned QImage owns its pixel data independently.

Attributes Documentation

variable unexpect

cpp

constexprunexpect_t unexpect {};

Global unexpect tag instance.

variable bytes_size

cpp

constexprsize_t bytes_size =
    pixel_format::channels * sizeof(typename pixel_format::value_type);

Computes the number of bytes occupied by one pixel of the given format at compile time.

Template Parameters:

pixel_format A type satisfying is_pixel_format.

Return: Number of bytes per pixel.

Since: 1.0.0

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

cvw ​

Namespaces ​

Classes ​

Types ​

Functions ​

Attributes ​

Types Documentation ​

enum AlgorithmError ​

enum ConversionalError ​

enum LoadError ​

enum ConvertionalError ​

enum ConvertionalMethod ​

Functions Documentation ​

function to_gray ​

function to_gray ​

function to_gray ​

function to_bgr ​

function yuyv_to_gray ​

function canny ​

function sobel ​

function gaussian_blur ​

function median_blur ​

function resize ​

function flip ​

function rotate ​

function load ​

function save ​

function normalize ​

function threshold ​

function adaptive_threshold ​

function make_pipeline ​

function from_cv ​

function to_cv ​

function to_qimage_view ​

function to_qimage_copy ​

Attributes Documentation ​

variable unexpect ​

variable bytes_size ​

cvw

Namespaces

Classes

Types

Functions

Attributes

Types Documentation

enum AlgorithmError

enum ConversionalError

enum LoadError

enum ConvertionalError

enum ConvertionalMethod

Functions Documentation

function to_gray

function to_gray

function to_gray

function to_bgr

function yuyv_to_gray

function canny

function sobel

function gaussian_blur

function median_blur

function resize

function flip

function rotate

function load

function save

function normalize

function threshold

function adaptive_threshold

function make_pipeline

function from_cv

function to_cv

function to_qimage_view

function to_qimage_copy

Attributes Documentation

variable unexpect

variable bytes_size