Color Space Filters

Video Format Converter

The vfc filter converts between various uncompressed YUV and RGB pixel formats. The filter supports the following properties:

Property

Type

Description

OutputFormat

string

The output pixel format as a four character code.

MatrixCoefficients

integer

Specifies the matrix coefficients used to convert the output between YUV and RGB.

See Media Streams.

VideoRange

integer

Specifies the output video range.

See Media Streams.

ChromaSiting

integer

Specifies the output chroma location.

See Media Streams.

ConversionStrategy

integer

1 Prefer quality over speed
2 Prefer speed over quality

RoundingMode

integer

Specifies the method used to round values to a lower bit depth.
0 Down
1 Up
2 Nearest
3 Dither

Video Color Space Converter

The vcsc filter uses a lookup table (LUT) to perform color space conversions. By default the filter generates an internal lookup table (LUT). The filter can also accept an external LUT in either CUBE or Lustre file format.

The filter supports the following LUT configurations:

  • a 1D LUT used to perform scaling or transfer function conversions
  • a 3D LUT required to perform tone mapping or color primary conversions
  • a 3D LUT with a 1D "pre-shapper" LUT used to linearize the RGB signals

The filter accepts either 4:4:4 RGB or 4:4:4 YUV formats. The internal LUT is computed based on the input format and will produce the same format on the output.

For an external LUT the user must ensure that the input color space and pixel format match the LUT requirements (since this information is not provided by the LUT file).

In the following example the pq2hlg.cube LUT file expects RGB input values and converts from PQ to HLG:

---
input:
  container:
  - name: input1
    video:
    - name: v1
      color_primaries: BT2020
      transfer_characteristics: PQ
      matrix_coefficients: BT2020
      video_range: narrow
output:
  container:
  - name: output1
    type: 'mov '
    video:
    - route:
        name: v1
      filter:
      - type: 'vfc '
        properties:
          OutputFormat: 'R64L'
          VideoRange: 1
      - type: 'vcsc'
        properties:
          LutFile: /pq2hlg.cube
          ColorPrimaries: 9
          TransferCharacteristics: 18
          VideoRange: 1
      - type: 'vfc '
        properties:
          OutputFormat: 'v216'
          MatrixCoefficients: 9
      encode:
        type: 'appr'
        properties:
          OutputFormat: 'apch'
{
  "input": {
    "container": [
      {
        "name": "input1",
        "video": [
          {
            "name": "v1",
            "color_primaries": "BT2020",
            "transfer_characteristics": "PQ",
            "matrix_coefficients": "BT2020",
            "video_range": "narrow"
          }
        ]
      }
    ]
  },
  "output": {
    "container": [
      {
        "name": "output1",
        "type": "mov ",
        "video": [
          {
            "route": {
              "name": "v1"
            },
            "filter": [
              {
                "type": "vfc ",
                "properties": {
                  "OutputFormat": "R64L",
                  "VideoRange": 1
                }
              },
              {
                "type": "vcsc",
                "properties": {
                  "LutFile": "/pq2hlg.cube",
                  "ColorPrimaries": 9,
                  "TransferCharacteristics": 18,
                  "VideoRange": 1
                }
              },
              {
                "type": "vfc ",
                "properties": {
                  "OutputFormat": "v216",
                  "MatrixCoefficients": 9
                }
              }
            ],
            "encode": {
              "type": "appr",
              "properties": {
                "OutputFormat": "apch"
              }
            }
          }
        ]
      }
    ]
  }
}

The composition performs the following:

  • overrides the input color space information to BT.2020 PQ.
  • converts the input to 16 bit RGB R64L.
  • converts the color space to BT.2020 HLG using the LUT file.
  • converts the output to 10 bit YUV v210 using the BT.2020 matrix coefficients.
  • encodes the output in Apple ProRes HQ format.

Property

Type

Description

LutFile

string

Path to a CUBE 3D LUT file.

TableSize

integer

Specifies the number of elements in each dimension of the lookup table.

MatrixCoefficients

integer

Specifies the matrix coefficients used to convert the output between YUV and RGB.

See Media Streams.

ColorPrimaries

integer

Specifies the location (in XYZ space) of the red (R), green (G) and blue (B) color primaries and reference white point (W).

See Media Streams.

TransferCharacteristics

integer

Specifies the the Opto-Electronic Transfer Function (OETF) used to convert between scene linear light levels and nonlinear component values.

See Media Streams

VideoRange

integer

Specifies the range of signal values that represent the real component values in the normalized range of 0.0 (black) to 1.0 (peak white).

See Media Streams.

ReferenceBlackLevel

number

Specifies the normalized signal value that represents 0% reflectivity.

ReferenceWhiteLevel

number

Specifies the normalized signal value that represents 100% reflectivity.

EnableRangeCompression

boolean

Enables compression (rather than clipping) of high dynamic range signals when converting to a lower dynamic range. Default is true.

RangeCompressionRatio

number

Specifies the compression ratio for Extended Reinhard dynamic range compression.

Light levels above this value clipped. Light levels below this value are compressed into the legal range.

Default value is 1.0.

RangeCompressionToe

number

Specifies the normalized linear black level for Telestream dynamic range compression.

Light levels above this value are linear. Light levels below this value are compressed into the legal range.

Default value is 0.0.

RangeCompressionShoulder

number

Specifies the normalized linear white level for Telestream dynamic range compression.

Light levels below this value are linear. Light levels above this value are compressed into the legal range.

Default value is 1.0.

ForceSceneReferencedConversion

boolean

Disables application of an OOTF (optical to optical transfer function).

Default value is true.

GamutCoercionMode

number

Specifies the method used to reduce gamut:
0 None
1 Clamp
2 Interpolate

For an example of a full API request payload, see External LUT Job Submission.

ColorFront Color Space Converter

The ColorFront(r) based color space conversion cfcs filter supports the following input color spaces:

  • BT2020 PQ
  • BT2020 HLG
  • BT709
  • P3D65 PQ
  • P3DCI ST428
  • XYZ ST428

The filter implements the following conifguration properties:

Property

Type

Description

ColorSpace

enum

Determines the output color space.

HdrAmount

number

Controls the strength of the tone mapping. A value of 0 produces an SDR output.

HdrSurround

number

Affects the highlight range to be boosted.

The filter supports the following output color space types:

Value

Color Space

Notes

0

BT2020 PQ

100 cd/m^2 (HDR10)

1

BT2020 PQ

100 cd/m^2

2

BT2020 HLG

1000 cd/m^2

3

BT2020 HLG

100 cd/m^2

4

BT709

5

P3DCI ST428

6

XYZ ST428

For example the following composition:

  • overrides the input color space to BT2020 PQ (YUV)
  • converts the input color space to BT2020 HLG (RGB) using the cfcs filter
  • converts the RGB to 16 bit narrow range BT2020 YUV using the vfc filter
  • encodes the output as ProRes 444
input:
  container:
  - name: input1
    video:
    - name: v1
      color_primaries: BT2020
      transfer_characteristics: PQ
      matrix_coefficients: BT2020
      video_range: narrow
output:
  container:
  - name: output1
    type: 'mov '
    video:
    - route:
        name: v1
      filter:
      - type: cfcs
        properties:
          ColorSpace: 2
      - type: 'vfc '
        properties:
          OutputFormat: y416
          MatrixCoefficients: 9
          VideoRange: 1
      encode:
        type: appr
        properties:
          OutputFormat: ap4x

Did this page help you?