Skip to main content
Version: 1.0

Image & Lens API

Source: raptor/image.hpp, raptor/lens.hpp

Types​

NameDescription
ImageOwning image container.
ImageTypeImage format type identifier.
ImageViewNon-owning view over image data.
LensModelType-erased lens model.

Image types and containers​

ImageType​

enum class ImageType : std::uint32_t

Image format type identifier

Enumeration identifying the pixel format of an image.

Gray8 = 0 : Single channel, 8 bits per pixel

Rgb8 = 1 : 3 channels (red, green, blue), 8 bits per channel

Rgba8 = 2 : 4 channels (red, green, blue, alpha), 8 bits per channel

ImageView​

class ImageView

Non-owning view over image data

Lightweight container for passing images without ownership. Provides direct access to image properties and data.

note

The caller must ensure the underlying data outlives the ImageView.

Example:

ImageView view{ImageType::Rgb8, 1920, 1080, data};
std::int32_t w = view.width();
std::int32_t h = view.height();
std::uint32_t ch = view.channels();
const std::uint8_t* ptr = view.bytes().data();

Functions​

NameDescription
ImageView(span)Construct a view from raw image data (span).
ImageView(uint8_t)Construct a view from raw image data (pointer).
ImageView(Image)Construct a view from an Image.
typeImage format type.
widthImage width in pixels.
heightImage height in pixels.
channelsNumber of channels per pixel.
numPixelsTotal number of pixels (width * height).
bytesImage data as a span of bytes.

Function Details​

ImageView​

Function
ImageView(ImageType type, std::int32_t width, std::int32_t height, std::span<const std::uint8_t> data) noexcept

Construct a view from raw image data (span) Parameters:

  • type - Image format type
  • width - Image width in pixels
  • height - Image height in pixels
  • data - Span of image data (must outlive this view)
Function
ImageView(ImageType type, std::int32_t width, std::int32_t height, const std::uint8_t&#42; data) noexcept

Construct a view from raw image data (pointer) Parameters:

  • type - Image format type
  • width - Image width in pixels
  • height - Image height in pixels
  • data - Pointer to image data (must outlive this view)
Function
ImageView(const Image& image) noexcept

Construct a view from an Image Parameters:

  • image - The image to create a view from (must outlive this view)

type​

Function
[[nodiscard]] ImageType type() const noexcept

Returns: Image format type

width​

Function
[[nodiscard]] std::int32_t width() const noexcept

Returns: Image width in pixels

height​

Function
[[nodiscard]] std::int32_t height() const noexcept

Returns: Image height in pixels

channels​

Function
[[nodiscard]] std::uint32_t channels() const noexcept

Returns: Number of channels per pixel

numPixels​

Function
[[nodiscard]] std::size_t numPixels() const noexcept

Returns: Total number of pixels (width * height)

bytes​

Function
[[nodiscard]] std::span<const std::uint8_t> bytes() const noexcept

Returns: Image data as a span of bytes

Image​

class Image

Owning image container

Owns the image data and provides direct access to image properties.

Example:

Image image{ImageType::Rgb8, 1920, 1080, data};
std::int32_t w = image.width();
std::int32_t h = image.height();
std::uint8_t* ptr = image.bytes().data();

Functions​

NameDescription
Image(span)Construct an image from raw image data (copies data from span).
Image(uint8_t)Construct an image from raw image data (copies data from pointer).
Image(ImageView)Construct an image from an ImageView (copies data).
typeImage format type.
widthImage width in pixels.
heightImage height in pixels.
channelsNumber of channels per pixel.
numPixelsTotal number of pixels (width * height).
bytes(1)Image data as a mutable span of bytes.
bytes(2)Image data as a const span of bytes.

Function Details​

Image​

Function
Image(ImageType type, std::int32_t width, std::int32_t height, std::span<const std::uint8_t> data)

Construct an image from raw image data (copies data from span) Parameters:

  • type - Image format type
  • width - Image width in pixels
  • height - Image height in pixels
  • data - Span of image data to copy Throws: std::invalid_argument - If width or height is non-positive, data is empty, or data.size() does not equal width * height * channels(type).
Function
Image(ImageType type, std::int32_t width, std::int32_t height, const std::uint8_t&#42; data)

Construct an image from raw image data (copies data from pointer) Parameters:

  • type - Image format type
  • width - Image width in pixels
  • height - Image height in pixels
  • data - Pointer to image data to copy Throws: std::invalid_argument - If width or height is non-positive, or data is null.
Function
explicit Image(const ImageView& view)

Construct an image from an ImageView (copies data) Parameters:

  • view - View to copy data from Throws: std::invalid_argument - If the view has non-positive dimensions or empty data.

type​

Function
[[nodiscard]] ImageType type() const noexcept

Returns: Image format type

width​

Function
[[nodiscard]] std::int32_t width() const noexcept

Returns: Image width in pixels

height​

Function
[[nodiscard]] std::int32_t height() const noexcept

Returns: Image height in pixels

channels​

Function
[[nodiscard]] std::uint32_t channels() const noexcept

Returns: Number of channels per pixel

numPixels​

Function
[[nodiscard]] std::size_t numPixels() const noexcept

Returns: Total number of pixels (width * height)

bytes​

Function
[[nodiscard]] std::span<std::uint8_t> bytes() noexcept

Returns: Image data as a mutable span of bytes

Function
[[nodiscard]] std::span<const std::uint8_t> bytes() const noexcept

Returns: Image data as a const span of bytes

Lens model types for various projection equations​

Pinhole​

struct Pinhole

Pinhole lens parameters

Standard pinhole camera with focal lengths and principal point. No lens distortion.

Variables​

NameDescription
fxFocal length in pixels (width axis); must be finite and > 0.
fyFocal length in pixels (height axis); must be finite and > 0.
cxPrincipal point x (width axis); must be finite and >= 0.
cyPrincipal point y (height axis); must be finite and >= 0.

Functions​

NameDescription
fromFovCreate Pinhole parameters from field of view angles.

Variable Details​

fx​

double fx

Focal length in pixels (width axis); must be finite and > 0

fy​

double fy

Focal length in pixels (height axis); must be finite and > 0

cx​

double cx

Principal point x (width axis); must be finite and >= 0

cy​

double cy

Principal point y (height axis); must be finite and >= 0

Function Details​

fromFov​

Function
[[nodiscard]] static Pinhole fromFov(double hfov, double vfov, std::int32_t width, std::int32_t height)

Create Pinhole parameters from field of view angles

The principal point (cx, cy) is assumed to be at the image center. Focal lengths are computed using: f = (size/2) / tan(fov/2) Parameters:

  • hfov - Horizontal field of view in radians
  • vfov - Vertical field of view in radians
  • width - Image width in pixels
  • height - Image height in pixels Returns: Pinhole parameters with principal point at image center Throws: std::invalid_argument - If hfov or vfov is not finite, not positive, or > π.

LensModel​

class LensModel

Type-erased lens model

Encapsulates a projection equation choice together with its parameter values in an ABI-stable internal format. Behaves like a variant - you can only retrieve the same params type that was stored.

Example:

// Create directly from explicit pinhole parameters
LensModel l1{lens::Pinhole{
    .fx = 1000.0, .fy = 1000.0, .cx = 960.0, .cy = 540.0}};

// Or from FOV using the Pinhole factory method (~90° x ~53° FOV)
LensModel l2{lens::Pinhole::fromFov(1.5708, 0.9273, 1920, 1080)};

// Get as Pinhole (same type as stored)
const auto& pinhole = l1.get<lens::Pinhole>();  // OK

// Check params type before getting
if (l1.holds<lens::Pinhole>()) {
    const auto& p = l1.get<lens::Pinhole>();
}

// Use visitor pattern
l1.visit([](const auto& params) {
    // Handle each params type
});

Functions​

NameDescription
LensModel()Default constructor - creates identity pinhole lens model.
LensModel(Pinhole)Create lens model from Pinhole lens parameters.
getGet lens parameters in specified params format.
holdsCheck if lens model holds a specific params type.
visitApply a visitor to the stored lens parameters.

Function Details​

LensModel​

Function
LensModel()

Default constructor - creates identity pinhole lens model

Creates a pinhole lens model with fx=fy=1.0, cx=cy=0.0.

Function
explicit LensModel(const lens::Pinhole& params)

Create lens model from Pinhole lens parameters Parameters:

  • params - Pinhole lens parameter struct

get​

Function
template<typename ParamsType> [[nodiscard]] const ParamsType& get() const

Get lens parameters in specified params format

ParamsType: : lens::Pinhole, etc. Returns: Reference to lens parameters in the specified params format Throws: std::bad_variant_access - if ParamsType does not match the stored params type

holds​

Function
template<typename ParamsType> [[nodiscard]] bool holds() const noexcept

Check if lens model holds a specific params type

ParamsType: : lens::Pinhole, etc. Returns: true if the stored params matches ParamsType

visit​

Function
template<typename Visitor> decltype(auto) visit(Visitor&& vis) const

Apply a visitor to the stored lens parameters

Visitor : Callable that accepts each supported lens params type Parameters:

  • vis - Visitor callable Returns: Result of calling visitor with the stored params

Example using raptor::Overloaded for combining lambdas:

#include "raptor/overloaded.hpp"

lens.visit(raptor::Overloaded{
    [](const lens::Pinhole& p) { std::cout << "fx=" << p.fx << "\n"; },
    // [](const lens::Fisheye& f) { ... },  // add handlers for future params
});