Color Space Conversion

Transform supports Wide Color Gamut (WCG) and High Dynamic Range (HDR) color space conversion.

The color space for a video stream is defined by the following properties:

Properties specified on an input stream provide (or override) the color space information when it is missing (or incorrect). Properties specified on an output stream convert the video to a different color space.

For example the following composition forces the the input color space to narrow range BT.2100 PQ (HDR10) and converts the output color space to BT.2100 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:
    - name: v1
      transfer_characteristics: 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": [
               {
                  "name": "v1",
                  "transfer_characteristics": "hlg"
               }
            ]
         }
      ]
   }
}

Dynamic Range Compression

The dynamic range of a video stream is defined by the following properties:

For example in a standard dynamic range signal (e.g BT.709) the reference black (0% reflectivity) is 0.0 and the reference white (100% reflectivity) is 1.0 (roughly 200 nits). For HDR10 the reference white is 0.58 indicating that the signal may contain highlights well above 100% reflectivity (up to 10000 nits).

Dynamic range compression preserves highlights when converting from a high dynamic range (HDR) color space to standard dynamic range (SDR).

For example the following composition converts HDR10 to BT709 color space preserving highlights up to 200% of the SDR range:

---
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:
    - name: v1
      color_primaries: bt709    
      transfer_characteristics: bt709
      matrix_coefficients: bt709
      dynamic_range: 2.0

{
   "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": [
               {
                  "name": "v1",
                  "color_primaries": "bt709",
                  "transfer_characteristics": "bt709",
                  "matrix_coefficients": "bt709",
                  "dynamic_range": 2.0
               }
            ]
         }
      ]
   }
}

Standard Color Spaces

Use the ColorSpace property to specific a standard color space for an input or output stream (the VideoRange property can be used as an alias for video_range). For example the following composition sets the input color space to narrow range HDR10:

---
input:
  container:
  - name: input1
    video:
    - name: v1
      properties:
        ColorSpace: HDR10

{
  "input": {
    "container": [
      {
        "name": "input1",
        "video": [
          {
            "name": "v1",
            "properties": {
              "ColorSpace": "HDR10"
            }
          }
        ]
      }
    ]
  }
}

The following standard color spaces are supported:

ColorSpace	color_primaries	transfer_characteristics	matrix_coefficients
`NTSC`	`ntsc`	`bt601`	`ntsc`
`PAL`	`pal`	`bt601`	`pal`
`BT709`	`bt709`	`bt709`	`bt709`
`BT2020`	`bt2020`	`bt2020`	`bt2020`
`HDR10`	`bt2020`	`pg`	`bt2020`
`HLG`	`bt2020`	`hlg`	`bt2020`

Lookup Table Conversion

Use the LookupTableInput stream property to provide a lookup table (LUT) for color space conversion.

Transform accepts an RGB LUT in either CUBE or Lustre file formats and supports the following configurations:

a 1D LUT that performs scaling or transfer function conversions.
a 3D LUT that performs tone mapping or color primary conversions.
a 3D LUT with a 1D pre-shaper LUT used to linearize the input.

Note that the output color space must be specified since this information is not provided in the LUT file. For example the following composition uses an external LUT to convert from HDR10 to HLG:

---
input:
  container:
  - name: media
    video:
    - name: v1
      properties:
        ColorSpace: HDR10
        VideoRange: narrow
  - name: LUT
    properties:
      Kind: data
output:
  container:
  - name: output1
    video:
    - route:
        name: v1
      properties:
        LookupTableInput: LUT
        ColorPrimaries: hlg
        VideoRange: narrow

{
   "input": {
      "container": [
         {
            "name": "media",
            "video": [
               {
                  "name": "v1",
                  "properties": {
                     "ColorSpace": "HDR10",
                     "VideoRange": "narrow"
                  }
               }
            ]
         },
         {
            "name": "LUT",
            "properties": {
               "Kind": "data"
            }
         }
      ]
   },
   "output": {
      "container": [
         {
            "name": "output1",
            "video": [
               {
                  "route": {
                     "name": "v1"
                  },
                  "properties": {
                     "LookupTableInput": "LUT",
                     "ColorPrimaries": "hlg",
                     "VideoRange": "narrow"
                  }
               }
            ]
         }
      ]
   }
}

Use the following properties (or the ColorSpace property) to specify the color space produced the the LUT:

Property	Type	Description
`ColorPrimaries`	string	Specifies the location (in XYZ space) of the red (R), green (G) and blue (B) color primaries and reference white point (W).
`TransferCharacteristics`	string	Specifies the the Opto-Electronic Transfer Function (OETF) used to convert between scene linear light levels and nonlinear component values.
`VideoRange`	string	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)

External LUT Job Submission

The composition in the the following API request provides an external LUT file to be used for a color space conversion.

{
   "composition":{
      "input":{
         "container":[
            {
               "name":"input",
               "video":[
                  {
                     "name":"v1"
                  }
               ]
            },
            {
               "name":"lut",
               "properties":{
                  "Kind":"data"
               }
            }
         ]
      },
      "output":{
         "container":[
            {
               "type":"mov ",
               "name":"output",
               "video":[
                  {
                     "name":"v2",
                     "route":{
                        "name":"v1"
                     },
                     "width":3840,
                     "height":2160,
                     "encode":{
                        "properties":{
                           "OutputFormat":"apcn"
                        },
                        "type":"appr"
                     },
                     "properties":{
                        "LookupTableInput":"lut",
                        "ColorPrimaries":"bt2020",
                        "TransferCharacteristics":"hlg",
                        "MatrixCoefficients":"bt2020",
                        "VideoRange":"narrow",
                        "ReferenceWhite":0.83
                     }
                  }
               ]
            }
         ]
      }
   },
   "inputs":{
      "input":{
         "url":"s3://bucket/1080p29.97_BT.709.mov"
      },
      "lut":{
         "url":"s3://bucket/BT.709_HLG_UPCONVERT.cube"
      }
   },
   "outputs":{
      "output":{
         "path_format":"$original$.mov"
      }
   }
}

Predefined Lookup Tables

Use the LookupTableName property to specify a predefined lookup table for color space conversion. For example the following composition will use a BBC lookup table to convert from HDR10 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
    video:
    - route:
        name: v1
      properties:
        LookupTableName: BBC1

{
   "input": {
      "container": [
         {
            "name": "input1",
            "video": [
               {
                  "name": "v1",
                  "color_primaries": "bt2020",
                  "transfer_characteristics": "pq",
                  "matrix_coefficients": "bt2020",
                  "video_range": "narrow"
               }
            ]
         }
      ]
   },
   "output": {
      "container": [
         {
            "name": "output1",
            "video": [
               {
                  "route": {
                     "name": "v1"
                  },
                  "properties": {
                     "LookupTableName": "BBC1"
                  }
               }
            ]
         }
      ]
   }
}

BBC Lookup Tables

Transform supports the following BBC developed lookup tables for HLG color space conversions:

Name	Input	Output	Notes
`BBC1`	BT2020 PQ	BT2020 HLG	1000 nit peak
`BBC2`	BT2020 PQ	BT2020 HLG	4000 nit peak
`BBC3`	BT709	BT2020 HLG	Display referenced (100% SDR = 75% HLG)
`BBC4-1`	BT709	BT2020 HLG	Scene referenced (100% SDR = 75% HLG)
`BBC4-2`	BT709	BT2020 HLG	Scene referenced (100% SDR = 75% HLG), High resolution
`BBC5`	BT709	BT2020 HLG	Display referenced (100% SDR = 83% HLG)
`BBC6-1`	BT709	BT2020 HLG	Scene referenced (100% SDR = 79% HLG)
`BBC6-2`	BT709	BT2020 HLG	Scene referenced (100% SDR = 79% HLG), High resolution
`BBC7`	BT2020 HLG	BT2020 PQ	1000 nit peak
`BBC8`	BT2020 HLG	BT709
`BBC10`	BT2020 S-LOG3	BT2020 HLG	100% S-Log3 = 90% reflectance = 73% HLG
`BBC11`	BT2020 S-LOG3	BT2020 HLG	200% S-Log3 = 90% reflectance = 73% HLG
`BBC12-1`	BT2020 HLG	BT709	Scene referenced (79% HLG = 100% SDR)
`BBC12-2`	BT2020 HLG	BT709	Scene referenced (79% HLG = 100% SDR), High resolution
`BBC14`	P3D65 PQ	BT2020 HLG	1000 nit peak
`BBC15`	BT2020 HLG	P3D65 PQ	1000 nit peak