Image¶

template<IsImagePixel T> struct ImagePixelTraits¶

Type traits for image pixel types.

Provides compile-time information about pixel types including the underlying scalar type and the number of channels.

Template Parameters:: T – The pixel type (must satisfy IsImagePixel concept)

Public Types

using Scalar = T ¶

Public Static Attributes

static constexpr int channels = 1¶

enum class huira::WrapMode¶

Specifies how texture coordinates outside [0,1] are handled during sampling.

Values:

enumerator Clamp¶: Clamp coordinates to [0,1].

enumerator Repeat¶: Repeat texture by wrapping coordinates.

enumerator Mirror¶: Mirror texture at boundaries.

template<IsImagePixel PixelT> class Image¶

A 2D image container with templated pixel types.

The Image class provides a flexible container for 2D image data with support for various pixel types including scalar values, Vec3 for RGB/color data, and SpectralBins for spectral imaging. It offers both checked and unchecked access methods, as well as sampling operations with different wrap modes.

Memory is stored in row-major order, with the origin at the top-left corner. Pixel coordinates (x, y) map to image space where x increases to the right and y increases downward. This layout is fixed: a camera’s PixelConvention only changes how positions on the image are numbered, and file formats with bottom-up rows are flipped as they are read and written.

Template Parameters:: PixelT – The type of pixel stored (must satisfy IsImagePixel concept)

Public Types

using PixelType = PixelT ¶

using Traits = ImagePixelTraits<PixelT>¶

using Scalar = typename Traits::Scalar¶

Public Functions

Image()¶: Default constructor creating an empty image.

Image(Resolution resolution)¶

Constructs an image with the specified resolution.

Pixels are default-initialized.

Parameters:: resolution – The width and height of the image

Image(Resolution resolution, const PixelT &fill_value)¶

Constructs an image with the specified resolution and fill value.

All pixels are initialized to the specified fill value.

Parameters:

resolution – The width and height of the image
fill_value – The value to initialize all pixels with

Image(int width, int height)¶

Constructs an image with the specified width and height.

Pixels are default-initialized.

Parameters:

width – The width of the image in pixels
height – The height of the image in pixels

Image(int width, int height, const PixelT &fill_value)¶

Constructs an image with the specified width, height, and fill value.

All pixels are initialized to the specified fill value.

Parameters:

width – The width of the image in pixels
height – The height of the image in pixels
fill_value – The value to initialize all pixels with

Image(const Image&) = default¶

Image(Image&&) noexcept = default¶

Image &operator=(const Image&) = default¶

Image &operator=(Image&&) noexcept = default¶

~Image() = default¶

bool empty() const noexcept¶

Checks if the image has no pixels.

Returns:: true if the image is empty (zero width or height), false otherwise

explicit operator bool() const noexcept¶

Checks if the image contains any pixels.

Returns:: true if the image is not empty, false otherwise

Resolution resolution() const noexcept¶

Gets the resolution (width and height) of the image.

Returns:: The image resolution

int width() const noexcept¶

Gets the width of the image in pixels.

Returns:: The image width

int height() const noexcept¶

Gets the height of the image in pixels.

Returns:: The image height

std::size_t size() const noexcept¶

Gets the total number of pixels in the image.

Returns:: The number of pixels (width × height)

PixelT &operator[](std::size_t index)¶

Provides unchecked access to a pixel by linear index.

This operator does not perform bounds checking in release builds. In debug builds, an assertion will fail if the index is out of bounds.

Parameters:: index – Linear index into the image data (0 to size()-1)
Returns:: Reference to the pixel at the specified index

const PixelT &operator[](std::size_t index) const¶

Provides unchecked read-only access to a pixel by linear index.

This operator does not perform bounds checking in release builds. In debug builds, an assertion will fail if the index is out of bounds.

Parameters:: index – Linear index into the image data (0 to size()-1)
Returns:: Const reference to the pixel at the specified index

PixelT &operator()(int x, int y)¶

Provides unchecked access to a pixel by 2D coordinates.

This operator does not perform bounds checking in release builds. In debug builds, an assertion will fail if the coordinates are out of bounds.

Parameters:

x – The x-coordinate (column) of the pixel
y – The y-coordinate (row) of the pixel

Returns:

Reference to the pixel at (x, y)

const PixelT &operator()(int x, int y) const¶

Provides unchecked read-only access to a pixel by 2D coordinates.

This operator does not perform bounds checking in release builds. In debug builds, an assertion will fail if the coordinates are out of bounds.

Parameters:

x – The x-coordinate (column) of the pixel
y – The y-coordinate (row) of the pixel

Returns:

Const reference to the pixel at (x, y)

PixelT &operator()(const Pixel &pixel)¶

Provides unchecked access to a pixel by Pixel coordinates.

The Pixel coordinates are converted to integers by truncation. This operator does not perform bounds checking in release builds. In debug builds, an assertion will fail if the coordinates are out of bounds.

Parameters:: pixel – The pixel coordinates (floating point values are truncated)
Returns:: Reference to the pixel at the converted coordinates

const PixelT &operator()(const Pixel &pixel) const¶

Provides unchecked read-only access to a pixel by Pixel coordinates.

Parameters:: pixel – The pixel coordinates (floating point values are truncated)
Returns:: Const reference to the pixel at the converted coordinates

PixelT &at(std::size_t index)¶

Provides bounds-checked access to a pixel by linear index.

Parameters:: index – Linear index into the image data (0 to size()-1)
Throws:: std::runtime_error – if the index is out of bounds
Returns:: Reference to the pixel at the specified index

const PixelT &at(std::size_t index) const¶

Provides bounds-checked read-only access to a pixel by linear index.

Parameters:: index – Linear index into the image data (0 to size()-1)
Throws:: std::runtime_error – if the index is out of bounds
Returns:: Const reference to the pixel at the specified index

PixelT &at(int x, int y)¶

Provides bounds-checked access to a pixel by 2D coordinates.

Parameters:

x – The x-coordinate (column) of the pixel
y – The y-coordinate (row) of the pixel

Throws:

std::runtime_error – if the coordinates are out of bounds

Returns:

Reference to the pixel at (x, y)

const PixelT &at(int x, int y) const¶

Provides bounds-checked read-only access to a pixel by 2D coordinates.

Parameters:

x – The x-coordinate (column) of the pixel
y – The y-coordinate (row) of the pixel

Throws:

std::runtime_error – if the coordinates are out of bounds

Returns:

Const reference to the pixel at (x, y)

PixelT &at(const Pixel &pixel)¶

Provides bounds-checked access to a pixel by Pixel coordinates.

The Pixel coordinates are converted to integers by truncation.

Parameters:: pixel – The pixel coordinates (floating point values are truncated)
Throws:: std::runtime_error – if the coordinates are out of bounds
Returns:: Reference to the pixel at the converted coordinates

const PixelT &at(const Pixel &pixel) const¶

Provides bounds-checked read-only access to a pixel by Pixel coordinates.

The Pixel coordinates are converted to integers by truncation.

Parameters:: pixel – The pixel coordinates (floating point values are truncated)
Throws:: std::runtime_error – if the coordinates are out of bounds
Returns:: Const reference to the pixel at the converted coordinates

template<WrapMode W = WrapMode::Repeat> PixelT sample_nearest_neighbor(float u, float v) const¶

Samples the image using nearest-neighbor interpolation.

UV coordinates are expected in the range [0, 1], where (0, 0) is the top-left corner and (1, 1) is the bottom-right corner. Coordinates outside this range are handled according to the specified wrap mode.

Template Parameters:

W – The wrap mode for handling coordinates outside [0, 1]

Parameters:

u – The horizontal texture coordinate (0 to 1)
v – The vertical texture coordinate (0 to 1)

Returns:

The sampled pixel value, or a default-constructed pixel if the image is empty

template<WrapMode W = WrapMode::Repeat> PixelT sample_bilinear(float u, float v) const¶

Samples the image using bilinear interpolation.

Bilinear interpolation is supported for arithmetic types, Vec3 types, and SpectralBins. For other pixel types, the function falls back to nearest-neighbor sampling.

Template Parameters:

W – The wrap mode for handling coordinates outside [0, 1]

Parameters:

u – The horizontal texture coordinate (0 to 1)
v – The vertical texture coordinate (0 to 1)

Returns:

The interpolated pixel value, or a default-constructed pixel if the image is empty

PixelT *data() noexcept¶

Gets a pointer to the underlying pixel data.

Returns:: Pointer to the first pixel in the image data

const PixelT *data() const noexcept¶

Gets a const pointer to the underlying pixel data.

Returns:: Const pointer to the first pixel in the image data

inline int sensor_bit_depth() const noexcept¶: The bit depth of the sensor whose response this is, or 0 for any other image. A sensor response holds DN / (2^bits - 1); the image writers use this to write DN (see PixelScaling).

void set_sensor_bit_depth(int bits)¶

Set the bit depth of the sensor whose response this is, or 0 for any other image.

Parameters:: bits – From 0 to 63, so that the sensor’s largest DN, 2^bits - 1, fits in the 64-bit integers the image writers count in.
Throws:: std::runtime_error – if it is outside that range.

void convolve(const Image &kernel)¶

void clear()¶

Clears the image, removing all pixel data.

After calling this method, the image will be empty with zero width and height.

void fill(const PixelT &value)¶

Fills all pixels in the image with the specified value.

Parameters:: value – The value to set for all pixels

inline void reset(const PixelT &value = PixelT{0})¶

Image<float> get_channel(std::size_t channel) const¶

Image operator+(const Image &other) const¶

template<IsImagePixel PixelT> struct ImageBundle¶

An image, with what a file holds besides the pixels: an alpha channel, the encoding (color_space, gamma_value), and, for writing, the file’s bit depth per sample and how values are scaled to it.

bit_depth is the file’s (8 or 16 bits per sample, say); the sensor’s bit depth, if the image came from one, is the image’s own (Image::sensor_bit_depth()).

Public Functions

ImageBundle() = default¶

inline ImageBundle(Image<PixelT> img)¶

inline ImageBundle(Image<PixelT> img, Image<float> alpha_copy)¶

template<typename OtherPixelT> inline ImageBundle(const ImageBundle<OtherPixelT> &other_bundle, Image<PixelT> new_image)¶

Public Members

Image<PixelT> image¶

Image<float> alpha = {}¶

ColorSpaceHint color_space = ColorSpaceHint::Linear ¶

float gamma_value = 1.0f¶

int bit_depth = 8¶

PixelScaling scaling = PixelScaling::Counts ¶

enum class huira::ColorSpaceHint¶

How an image’s values are encoded: as linear values (what Huira renders), or encoded with the sRGB curve or a gamma. Readers record the file’s encoding here, and writers label files with it; neither converts anything. linear_to_srgb() and srgb_to_linear() convert, and set it.

Values:

enumerator Linear¶

enumerator sRGB¶

enumerator Gamma¶

enumerator Unknown¶

enum class huira::PixelScaling¶

How an image writer turns the values of an image that has a sensor bit depth (see Image::sensor_bit_depth(), which a sensor readout sets) into the file’s values.

Counts: the file holds the sensor’s digital numbers (DN), as each format’s standard allows (see docs/design_overview/image_output.rst). Where the file has fewer bits than the sensor, the lowest bits are dropped, as a camera with a narrower output would.
FullRange: the values, in [0, 1], are stretched over the file’s whole range (1 becomes 255 or 65535), as for an image without a sensor bit depth. For display.

An image without a sensor bit depth is always written FullRange (or as is, to a float file).

Values:

enumerator Counts¶

enumerator FullRange¶