カラールックアップテーブルを適用するlut1d、lut3d

カラールックアップテーブル（CLUT）を適用して色調補正するlut1d、lut3dフィルタの使い方。lut1dフィルタが1次元でlut3dフィルタが3次元になる。平成26年度「デジタル映像の制作・流通のファイルフォーマットに関する調査より「主に諧調変換に対しては1次元LUTが使われ、色域の変換には3次元LUTが使われることが多い。」。ダイナミックレンジを変更するHDRとSDRの相互変換にも使える。それぞれタイムライン編集に対応。

• 第一回　LUTの基本 | TVLogic
• 3D LUTの基礎とHDRでの活用：PDF
• VP9 HDR Encoding | Google Developers
• Blackmagic Forum • View topic – LUT documentation (to create from another program)

外部ファイルを参照して色調補正するフィルタにcurvesフィルタがある。
トーンカーブで RGB の調整が出来る curves

CUBE形式の書き方

1次元、3次元のCUBE形式の書き方の仕様PDF：Cube LUTSpecificationVersion 1.0 : archive.org

共通の書き方。

• 文字と文字の間のセパレータは半角スペース（0x20）とタブ文字（0x09、\t）が使える。ブログでは半角スペースとする
• 改行は0x0A（\n）とし、文字コードはUTF-8とする
• TITLE “text”：CUBEファイルのタイトルの指定。無指定も可能で未定義になる
• DOMAIN_MIN rl gl bl：RGB（赤緑青）の下限の指定。0から1までの浮動小数点が一般的だが、わかりやすく8ビットの0から255までの整数でもよい。省略すると0 0 0になる
• DOMAIN_MAX rh gh bh：RGB（赤緑青）の上限の指定。0から1までの浮動小数点が一般的だが、わかりやすく8ビットの0から255までの整数でもよい。省略すると1 1 1になる
• 各テーブルの最初のサンプル点は下界に対応する
• 各テーブルの最後のサンプル点は上界に対応する
• 中間値は中間サンプル点に比例して対応する
• テーブルは可能なすべての入力値に対してサンプル点を含む必要はない
• テーブルに含まれない入力値について等間隔を置いた近くのサンプル点間で補間する
• 3つのテーブル、RGBは同じサイズのNを持つことと並列に並んでいることを除いて互いに独立している
• 一部のアプリケーションではNが2の整数乗のときに最適な性能を示す
• 一部のアプリケーションではN=256をサポートするのに十分なメモリがない

1次元LUTの書き方。

• テーブルは赤、緑、青の3つの1次元テーブルからなり、各テーブルは入力チャネルと1つの出力チャネルがある
• LUT_1D_SIZE N：N個のテーブル行と3×N個の列のデータとしNは2以上65536以下の整数とする
• テーブルの値は線形補間で正しい出力値を生成するように設定しなければならない
• テーブルのデータの行は最初のサンプルポイントから最後のサンプルポイントまで昇順とする

3次元LUTの書き方。

• テーブルは3次元とし、3つの入力チャネルと3つの出力チャネルを持つ
• LUT_3D_SIZE N：各次元のサンプルポイント数をN個とすると、Nの3乗個の列のデータとしNは2以上256以下の整数とする
• テーブルの値は四面体補間で正しい出力値を生成するように設定しなければならない
• ファイルはNの3乗行のデータテーブルを含み、それぞれがサンプルポイントに対応する
• データテーブルの行は1列目のインデックス（赤）が最も急速に変化し、3列目のインデックス（青）が最も急速に変化しないようにインデックスを昇順にしなければならない

lut1d

1次元のCLUTを適用するlut1dフィルタ。手書きするなら3次元よりも書きやすい。

わかりやすいサンプル例。ただし色の変化はない。

TITLE "lut1d 8bit sample"
LUT_1D_SIZE 4
DOMAIN_MIN 0 0 0
DOMAIN_MAX 255 255 255
0 0 0
85 85 85
190 190 190
255 255 255

基本コマンド

input.cubeを読み込んで、線形補間を行う。出力カラースペースはRGBになり、YUVの動画で出力するときにscale、zscaleフィルタで出力カラーマトリックスを解像度の応じて指定しないと意図した色にならないことがある。

リサイズする scale
Zライブラリを使ったリサイズフィルタ zscale

ffmpeg -i input -vf lut1d=input.cube:interp=linear,scale=out_color_matrix=bt709 -pix_fmt yuv420p -c:a copy output
ffplay -i input -vf lut1d=input.cube:linear

LUTの変換精度を上げるにはあらかじめ3×16の48ビットRGBに変換する。
ffmpeg -i input -vf format=rgb48,lut1d=input.cube:interp=linear,scale=out_color_matrix=bt709 -pix_fmt yuv420p -c:a copy output
ffplay -i input -vf format=rgb48,lut1d=input.cube:linear

挙動を調べるグラデーション画像。
ffmpeg -f lavfi -i color,geq='r=255-ceil(255*X/W):g=255-ceil(255*X/W):b=255-ceil(255*X/W)' -vframes 1 gradation.png
ffmpeg -i gradation.png -vf lut1d=1d.cube:linear,format=gbrp output.png

上のサンプルからRの85のところを90にすると線形補間ならGBが85のところでRが90になり、2倍のGBが170のところでRが180になる。

TITLE "lut1d 8bit linear sample"
LUT_1D_SIZE 4
DOMAIN_MIN 0 0 0
DOMAIN_MAX 255 255 255
0 0 0
90 85 85
190 190 190
255 255 255

ちなみにhaldclutsrcにlut1dフィルタを当てて、haldclutフィルタで合わせても同じ結果になる。
ffmpeg -f lavfi -i haldclutsrc=level=6 -vf lut1d=1d.cube:linear -vframes 1 haldclutsrc.png
ffmpeg -i gradation.png -i haldclutsrc.png -filter_complex [0][1]haldclut output2.png

CLUTから色を置換するhaldclut
ffmpeg で使える映像のテストソース

公式ドキュメント：FFmpeg Filters Documentation : lut1d

オプション

• file[string]
  1次元のLUTファイルの指定。CUBEとCSP（cineSpace）が読み込める
• interp[int]
  補間方法の指定
• 0, nearest
• 1, linear。既定値
• 2, cubic
• 3, cosine
• 4, spline

lut3d

3次元のCLUTを適用するlut3dフィルタ。こちらは検索するとたくさんサンプルが見つかる。

関連記事
Autodesk®Lustre®Color Management : PDF
Use of Look-Up Tables (LUTs) in FFmpeg : PDF

サンプル配布先例。

• Free LUTs – ON1
• 3D-LUT File for Blackmagic Design DaVinci Resolve : archive.org
• Q-DDL : A Large Free Collection (800+) of 3D Color LUTs – archive.org
• HDRコンテンツの輝度マップ生成用の3DLUTを作る – toruのブログ
• HDRとSDRの同時制作の手法 | 映像編集のソフトウェアEDIUS（エディウス）の総合サイト
• Everything looks better on KODACHROME – K-Tone LUT – Frank Glencairn
• FranceBB/LinearTransformation: This script performs Linear Transformations based on a matrix conversion. Matrices are made by Francesco Bucciantini (FranceBB)
• About LUT (Look-up Table) | Download | Digital Camera | Digital AV | Support | Panasonic Global
• Software & Downloads – Sony Pro
• digitaltvguy/NBCU-HDR-SDR-Single-Stream_Workflow_Recommendation
• Grading HDR Video on a Rec.709 Monitor (For YouTube & Beyond) — Wesley Knapp
• F-Log用LUT（Look Up Table） | 富士フイルム Xシリーズ & GFX
• FREE SAGAMI LUT – AUXOUT

公式ドキュメント：FFmpeg Filters Documentation : lut3d

基本コマンド

input.cubeを読み込んで、四面体補間を行う。YUVの動画で出力するときにscale、zscaleフィルタで出力カラーマトリックスを解像度の応じて指定しないと意図した色にならないことがある。

リサイズする scale
Zライブラリを使ったリサイズフィルタ zscale

ffmpeg -i input -vf lut3d=input.cube:interp=tetrahedral,scale=out_color_matrix=bt709 -pix_fmt yuv420p -c:a copy output
ffplay -i input -vf lut3d=input.cube:tetrahedral

LUTの変換精度を上げるにはあらかじめ48ビットRGBに変換する。
ffmpeg -i input -vf format=rgb48,lut3d=input.cube:interp=tetrahedral,scale=out_color_matrix=bt709 -pix_fmt yuv420p -c:a copy output
ffplay -i input -vf format=rgb48,lut3d=input.cube:tetrahedral

SDRからHDR HLGにアップマッピングする。
ffmpeg -i input -vf lut3d=input.cube:interp=tetrahedral,scale=in_range=tv:out_range=tv:in_color_matrix=bt709:out_color_matrix=bt2020_nc -color_primaries bt2020 -colorspace bt2020_ncl -color_trc arib-std-b67 –pix_fmt yuv422p10le -c:a copy output.mp4

オプション

• file[string]
  3次元のLUTファイルの指定。CUBE、3DL（AfterEffects）、DAT（DaVinci）、M3D（Pandora）とCSP（cineSpace）が読み込める
• clut[int]
  CLUTの読み込み方法
• 0, first：最初だけ
• 1, all：全部。既定値
• interp[int]
  補間方法の指定
• 0, nearest：最近傍補間
• 1, trilinear：三線形補間
• 2, tetrahedral：四面体補間。既定値
• 3, pyramid：三角錐補間
• 4, prism：三角柱補間

色の設定

どの組み合わせが正解か微妙に結果が異なるのでまだよくわかっていない。

フルレンジかリミテッドレンジを明示するのにsetrangeフィルタがある。
FFmpeg Filters Documentation : setrange

フィルタでは色の情報を明示するsetparamsフィルタがある。
フィールドタイプや色域を記述するsetparams

ffmpeg -i input -vf setparams=field_mode=prog:range=tv:color_primaries=bt709:color_trc=bt709:colorspace=bt709,format=rgb48,lut3d=input.cube,scale=out_color_matrix=bt709 -pix_fmt yuv420p -color_primaries bt709 -color_trc bt709 -colorspace bt709 -c:a copy output

カラースペースなどの入力、出力オプションは以下の記事を参照。
色の情報の扱いについて

[FFmpeg-user] vf_lut3d supports type 3 ?
How to do 3D Lut color correction (.3DL .Cube) with avisynth(+) ? [Archive] – Doom9’s Forum