PNG I/O

template<IsNonSpectralPixel T>
std::pair<Image<T>, Image<float>> huira::read_image_png(const fs::path &filepath)

Reads a PNG image file and converts it to linear color space.

Loads a PNG image from disk, automatically detecting and converting from the source color space (sRGB, linear, gamma, or ICC profile) to linear light. Supports 8-bit and 16-bit images, grayscale and RGB color types, and optional alpha channels. The function handles PNG transformations such as palette expansion and low bit-depth expansion automatically.

Template Parameters:

T – The pixel type for the output image (must satisfy IsNonSpectralPixel)

Parameters:

filepath – Path to the PNG file to read

Throws:

std::runtime_error – if the file cannot be opened, is not a valid PNG, or if any error occurs during reading

Returns:

A pair containing the main image and an optional alpha channel image. If the PNG has no alpha channel, the second image will be empty (0x0).

template<IsNonSpectralPixel T>
void huira::write_image_png(const fs::path &filepath, const Image<T> &image, int bit_depth)

Writes an image to a PNG file without an alpha channel.

Converts the image from linear color space to sRGB and writes it to a PNG file. This is a convenience overload that calls the full version with an empty alpha image.

Template Parameters:

T – The pixel type of the input image (must satisfy IsNonSpectralPixel)

Parameters:

  • filepath – Path where the PNG file will be written

  • image – The image to write

  • bit_depth – Bit depth of the output PNG (8 or 16)

Throws:

std::runtime_error – if the file cannot be created, the image is empty, or if any error occurs during writing

template<IsNonSpectralPixel T>
void huira::write_image_png(const fs::path &filepath, const Image<T> &image, const Image<float> &alpha, int bit_depth)

Writes an image to a PNG file with an optional alpha channel.

Converts the image from linear color space to sRGB and writes it to a PNG file. The function automatically creates necessary directories, handles both grayscale and RGB images, and supports 8-bit or 16-bit output. An sRGB color profile is embedded in the PNG metadata.

Template Parameters:

T – The pixel type of the input image (must satisfy IsNonSpectralPixel)

Parameters:

  • filepath – Path where the PNG file will be written

  • image – The image to write

  • alpha – Optional alpha channel image (must match dimensions of image, or be empty)

  • bit_depth – Bit depth of the output PNG (must be 8 or 16)

Throws:

std::runtime_error – if the file cannot be created, the image is empty, bit_depth is invalid, or if any error occurs during writing