libcamera  v0.3.0+92-226ce294
Supporting cameras in Linux since 2019
Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Static Public Attributes | List of all members
libcamera::ColorSpace Class Reference

Class to describe a color space. More...

Collaboration diagram for libcamera::ColorSpace:
Collaboration graph
[legend]

Public Types

enum  Primaries { Raw, Smpte170m, Rec709, Rec2020 }
 The color primaries for this color space.
 
enum  TransferFunction { Linear, Srgb, Rec709 }
 The transfer function used for this color space.
 
enum  YcbcrEncoding { None, Rec601, Rec709, Rec2020 }
 The Y'CbCr encoding.
 
enum  Range { Full, Limited }
 The range (sometimes "quantisation") for this color space.
 

Public Member Functions

constexpr ColorSpace (Primaries p, TransferFunction t, YcbcrEncoding e, Range r)
 Construct a ColorSpace from explicit values. More...
 
std::string toString () const
 Assemble and return a readable string representation of the ColorSpace. More...
 
bool adjust (PixelFormat format)
 Adjust the color space to match a pixel format. More...
 

Static Public Member Functions

static std::string toString (const std::optional< ColorSpace > &colorSpace)
 Assemble and return a readable string representation of an optional ColorSpace. More...
 
static std::optional< ColorSpacefromString (const std::string &str)
 Construct a color space from a string. More...
 

Public Attributes

Primaries primaries
 The color primaries of this color space.
 
TransferFunction transferFunction
 The transfer function used by this color space.
 
YcbcrEncoding ycbcrEncoding
 The Y'CbCr encoding used by this color space.
 
Range range
 The pixel range used with by color space.
 

Static Public Attributes

static const ColorSpace Raw
 A constant representing a raw color space (from a sensor) More...
 
static const ColorSpace Srgb
 A constant representing the sRGB color space (RGB formats only) More...
 
static const ColorSpace Sycc
 A constant representing the sYCC color space, typically used for encoding JPEG images. More...
 
static const ColorSpace Smpte170m
 A constant representing the SMPTE170M color space. More...
 
static const ColorSpace Rec709
 A constant representing the Rec.709 color space. More...
 
static const ColorSpace Rec2020
 A constant representing the Rec.2020 color space. More...
 

Detailed Description

Class to describe a color space.

The ColorSpace class defines the color primaries, the transfer function, the Y'CbCr encoding associated with the color space, and the range (sometimes also referred to as the quantisation) of the color space.

Certain combinations of these fields form well-known standard color spaces such as "sRGB" or "Rec709".

In the strictest sense a "color space" formally only refers to the color primaries and white point. Here, however, the ColorSpace class adopts the common broader usage that includes the transfer function, Y'CbCr encoding method and quantisation.

More information on color spaces is available in the V4L2 documentation, see in particular

Note that there is no guarantee of a 1:1 mapping between color space names and definitions in libcamera and V4L2. Two notable differences are

Todo:
Define the color space fully in the libcamera API to avoid referencing V4L2

Constructor & Destructor Documentation

◆ ColorSpace()

libcamera::ColorSpace::ColorSpace ( Primaries  p,
TransferFunction  t,
YcbcrEncoding  e,
Range  r 
)
inline

Construct a ColorSpace from explicit values.

Parameters
[in]pThe color primaries
[in]tThe transfer function for the color space
[in]eThe Y'CbCr encoding
[in]rThe range of the pixel values in this color space

Member Function Documentation

◆ adjust()

bool libcamera::ColorSpace::adjust ( PixelFormat  format)

Adjust the color space to match a pixel format.

Parameters
[in]formatThe pixel format

Not all combinations of pixel formats and color spaces make sense. For instance, nobody uses a limited quantization range with raw Bayer formats, and the YcbcrEncoding::None encoding isn't valid for YUV formats. This function adjusts the ColorSpace to make it compatible with the given format, by applying the following rules:

  • The color space for RAW formats must be Raw.
  • The Y'CbCr encoding and quantization range for RGB formats must be YcbcrEncoding::None and Range::Full respectively.
  • The Y'CbCr encoding for YUV formats must not be YcbcrEncoding::None. The best encoding is in that case guessed based on the primaries and transfer function.
Returns
True if the color space has been adjusted, or false if it was already compatible with the format and hasn't been changed

◆ fromString()

std::optional< ColorSpace > libcamera::ColorSpace::fromString ( const std::string &  str)
static

Construct a color space from a string.

Parameters
[in]strThe string

The string str can contain the name of a well-known color space, or be made of the four color space components separated by a '/' character, ordered as

primaries '/' transferFunction '/' ycbcrEncoding '/' range 

Any failure to parse the string, either because it doesn't match the expected format, or because the one of the names isn't recognized, will cause this function to return std::nullopt.

Returns
The ColorSpace corresponding to the string, or std::nullopt if the string doesn't describe a known color space

◆ toString() [1/2]

std::string libcamera::ColorSpace::toString ( ) const

Assemble and return a readable string representation of the ColorSpace.

If the color space matches a standard ColorSpace (such as ColorSpace::Sycc) then the short name of the color space ("sYCC") is returned. Otherwise the four constituent parts of the ColorSpace are assembled into a longer string.

Returns
A string describing the ColorSpace

◆ toString() [2/2]

std::string libcamera::ColorSpace::toString ( const std::optional< ColorSpace > &  colorSpace)
static

Assemble and return a readable string representation of an optional ColorSpace.

This is a convenience helper to easily obtain a string representation for a ColorSpace in parts of the libcamera API where it is stored in a std::optional<>. If the ColorSpace is set, this function returns colorSpace.toString(), otherwise it returns "Unset".

Returns
A string describing the optional ColorSpace

Member Data Documentation

◆ Raw

const ColorSpace libcamera::ColorSpace::Raw
static
Initial value:
= {
Primaries::Raw,
TransferFunction::Linear,
YcbcrEncoding::None,
Range::Full
}

A constant representing a raw color space (from a sensor)

◆ Rec2020

const ColorSpace libcamera::ColorSpace::Rec2020
static
Initial value:
= {
Primaries::Rec2020,
TransferFunction::Rec709,
YcbcrEncoding::Rec2020,
Range::Limited
}

A constant representing the Rec.2020 color space.

◆ Rec709

const ColorSpace libcamera::ColorSpace::Rec709
static
Initial value:
= {
Primaries::Rec709,
TransferFunction::Rec709,
YcbcrEncoding::Rec709,
Range::Limited
}

A constant representing the Rec.709 color space.

◆ Smpte170m

const ColorSpace libcamera::ColorSpace::Smpte170m
static
Initial value:
= {
Primaries::Smpte170m,
TransferFunction::Rec709,
YcbcrEncoding::Rec601,
Range::Limited
}

A constant representing the SMPTE170M color space.

◆ Srgb

const ColorSpace libcamera::ColorSpace::Srgb
static
Initial value:
= {
Primaries::Rec709,
TransferFunction::Srgb,
YcbcrEncoding::None,
Range::Full
}

A constant representing the sRGB color space (RGB formats only)

◆ Sycc

const ColorSpace libcamera::ColorSpace::Sycc
static
Initial value:
= {
Primaries::Rec709,
TransferFunction::Srgb,
YcbcrEncoding::Rec601,
Range::Full
}

A constant representing the sYCC color space, typically used for encoding JPEG images.


The documentation for this class was generated from the following files: