Pixel Convention

See Pixel Coordinate Conventions for what the conventions mean and when to change them.

struct PixelConvention

The pixel coordinate convention a camera’s users work in.

Pixel coordinates are exchanged with a camera in three places: the principal point passed to it (configure_sensor_from_pitch(), configure_sensor_from_size(), set_intrinsics() and set_intrinsic_matrix()), the positions project_point() returns, and the positions cast_ray() takes. A convention fixes what those numbers mean. Different tools number pixels differently, and the differences are silent: a calibration made in one convention and used in another is off by half a pixel or a whole one, or mirrored vertically.

The convention never changes the rendered image when the principal point is left at its default, the center of the sensor: it only changes the numbers used to talk about it.

The default is OpenCV’s, which most calibration tools share. Presets cover common tools:

Preset	First pixel center	y runs	Used by
opencv()	(0, 0)	down	OpenCV, Kornia, most calibration tools
colmap()	(0.5, 0.5)	down	COLMAP, Direct3D/Vulkan/Metal; Huira pre-0.9.10
matlab()	(1, 1)	down	MATLAB
fits()	(1, 1)	up	FITS / WCS (CRPIX), DS9

Internally Huira works in sensor coordinates: x right and y down from the sensor’s top-left corner, in pixels, so that pixel i covers [i, i + 1). to_sensor() and from_sensor() convert.

Public Functions

inline constexpr float first_pixel_center() const noexcept

Coordinate of the first pixel’s center along either axis: 0, 0.5 or 1.

inline constexpr Pixel to_sensor(const Pixel &p, const Resolution &resolution) const

Converts a position in this convention to sensor coordinates.

inline constexpr Pixel from_sensor(const Pixel &s, const Resolution &resolution) const

Converts a position in sensor coordinates to this convention.

inline std::string to_string() const

Public Members

PixelCenter center = PixelCenter::Integer

PixelOrigin origin = PixelOrigin::TopLeft

Public Static Functions

static inline constexpr PixelConvention opencv()

First pixel centered at (0, 0), y down. The default.

static inline constexpr PixelConvention colmap()

First pixel centered at (0.5, 0.5), y down: pixel edges at integers.

static inline constexpr PixelConvention matlab()

First pixel centered at (1, 1), y down.

static inline constexpr PixelConvention fits()

First pixel centered at (1, 1), y up from the bottom row: the convention of FITS WCS keywords such as CRPIX, for images written by Huira (which stores FITS rows bottom up).

Friends

friend constexpr bool operator==(const PixelConvention&, const PixelConvention&) = default

enum class huira::PixelCenter

Which coordinate the center of the first pixel has.

Values:

enumerator Integer

Pixel centers at integers, the first at 0. Pixel i covers [i - 0.5, i + 0.5).

enumerator HalfInteger

Pixel edges at integers, so the first pixel’s center is at 0.5. Pixel i covers [i, i + 1).

enumerator OneBased

Pixel centers at integers, the first at 1. Pixel n (counting from 1) covers [n - 0.5, n + 0.5).

enum class huira::PixelOrigin

Which corner of the image pixel coordinates count from.

x always runs left to right. This only changes how y is numbered; images are always stored with their top row first.

Values:

enumerator TopLeft

y runs down from the top row.

enumerator BottomLeft

y runs up from the bottom row.