libcamera: libcamera::ColorSpace Class Reference

libcamera v0.7.0 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
libcamera::ColorSpace Class Reference

Class to describe a color space. More...

Collaboration diagram for libcamera::ColorSpace:
[legend]

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

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

## Static Public Member Functions
static std::string | toString (const std::optional< ColorSpace > &colorSpace)
| Assemble and return a readable string representation of an optional ColorSpace.
static std::optional< ColorSpace > | fromString (const std::string &str)
| Construct a color space from a string.

## 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).
static const ColorSpace | Srgb
| A constant representing the sRGB color space (RGB formats only).
static const ColorSpace | Sycc
| A constant representing the sYCC color space, typically used for encoding JPEG images.
static const ColorSpace | Smpte170m
| A constant representing the SMPTE170M color space.
static const ColorSpace | Rec709
| A constant representing the Rec.709 color space.
static const ColorSpace | Rec2020
| A constant representing the Rec.2020 color space.

## 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

- sRGB
- JPEG
- SMPTE 170M
- Rec.709
- Rec.2020

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

- The sRGB libcamera color space is defined for RGB formats only with no Y'CbCr encoding and a full quantization range, while the V4L2 SRGB color space has a Y'CbCr encoding and a limited quantization range.

- The sYCC libcamera color space is called JPEG in V4L2 due to historical reasons.

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

## Member Enumeration Documentation

## ◆ Primaries

enum class libcamera::ColorSpace::Primaries
| strong

The color primaries for this color space.

Enumerator
Raw | These are raw colors directly from a sensor, the primaries are unspecified.
Smpte170m | SMPTE 170M color primaries.
Rec709 | Rec.709 color primaries.
Rec2020 | Rec.2020 color primaries.

## ◆ Range

enum class libcamera::ColorSpace::Range
| strong

The range (sometimes "quantisation") for this color space.

Enumerator
Full | This color space uses full range pixel values.
Limited | This color space uses limited range pixel values, being 16 to 235 for Y' and 16 to 240 for Cb and Cr (8 bits per sample) or 64 to 940 for Y' and 16 to 960 for Cb and Cr (10 bits).

## ◆ TransferFunction

enum class libcamera::ColorSpace::TransferFunction
| strong

The transfer function used for this color space.

Enumerator
Linear | This color space uses a linear (identity) transfer function.
Srgb | sRGB transfer function
Rec709 | Rec.709 transfer function.

## ◆ YcbcrEncoding

enum class libcamera::ColorSpace::YcbcrEncoding
| strong

The Y'CbCr encoding.

Enumerator
None | There is no defined Y'CbCr encoding (used for non-YUV formats).
Rec601 | Rec.601 Y'CbCr encoding.
Rec709 | Rec.709 Y'CbCr encoding.
Rec2020 | Rec.2020 Y'CbCr encoding.

## Constructor & Destructor Documentation

## ◆ ColorSpace()

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

Construct a ColorSpace from explicit values.

Parameters

  [in] | p | The color primaries
  [in] | t | The transfer function for the color space
  [in] | e | The Y'CbCr encoding
  [in] | r | The 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] | format | The 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] | str | The 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
}
libcamera::ColorSpace::Primaries::Raw
@ Raw
These are raw colors directly from a sensor, the primaries are unspecified.
Definition color_space.h:21
libcamera::ColorSpace::TransferFunction::Linear
@ Linear
This color space uses a linear (identity) transfer function.
Definition color_space.h:28
libcamera::ColorSpace::YcbcrEncoding::None
@ None
There is no defined Y'CbCr encoding (used for non-YUV formats).
Definition color_space.h:34
libcamera::ColorSpace::Range::Full
@ Full
This color space uses full range pixel values.
Definition color_space.h:41

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
}
libcamera::ColorSpace::Primaries::Rec2020
@ Rec2020
Rec.2020 color primaries.
Definition color_space.h:24
libcamera::ColorSpace::TransferFunction::Rec709
@ Rec709
Rec.709 transfer function.
Definition color_space.h:30
libcamera::ColorSpace::YcbcrEncoding::Rec2020
@ Rec2020
Rec.2020 Y'CbCr encoding.
Definition color_space.h:37
libcamera::ColorSpace::Range::Limited
@ Limited
This color space uses limited range pixel values, being 16 to 235 for Y' and 16 to 240 for Cb and Cr ...
Definition color_space.h:42

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
}
libcamera::ColorSpace::Primaries::Rec709
@ Rec709
Rec.709 color primaries.
Definition color_space.h:23
libcamera::ColorSpace::YcbcrEncoding::Rec709
@ Rec709
Rec.709 Y'CbCr encoding.
Definition color_space.h:36

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
}
libcamera::ColorSpace::Primaries::Smpte170m
@ Smpte170m
SMPTE 170M color primaries.
Definition color_space.h:22
libcamera::ColorSpace::YcbcrEncoding::Rec601
@ Rec601
Rec.601 Y'CbCr encoding.
Definition color_space.h:35

A constant representing the SMPTE170M color space.

## ◆ Srgb

const ColorSpace libcamera::ColorSpace::Srgb
| static

Initial value:
= {
Primaries::Rec709,
TransferFunction::Srgb,
YcbcrEncoding::None,
Range::Full
}
libcamera::ColorSpace::TransferFunction::Srgb
@ Srgb
sRGB transfer function
Definition color_space.h:29

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:

- include/libcamera/color_space.h
- src/libcamera/color_space.cpp