ART Ver. 1.21 から搭載された CTL に関して、公式サイトの以下に説明があります。
本記事では、上記記事の日本語訳を掲載します。
-----------
[お知らせ 2024.9]
オリジナル記事では、2024.8.25 に float型配列の説明が追加されました。この翻訳を追加しました (褐色部分)。
-----------
CTL スクリプト
CTL（the Color Transformation Language）は、カスタムピクセルレベルの画像変換操作を作成するために設計されたスクリプト言語です。CTLスクリプトとして書かれたLUTは、CLF LUTよりもさらに強力で柔軟性があり、複雑な画像操作操作をCやC++に似た言語でプログラムとして表現することができます。
重要なのは、ART の CTL スクリプトはパラメトリックであることです。スクリプト内で特別な書式のコメントを使用することで、ユーザーはスクリプトのメイン関数のいくつかの引数を、ART GUI から直接変更できるパラメータであると宣言できます（その値は .arp サイドカーファイルに保存されます）。これにより、ユーザーが書いたフィルターでARTを拡張する、シンプルで強力な方法が提供されます。
ART 互換の CTL スクリプトを書く
ARTで使用するためには、CTLスクリプトにART_mainと呼ばれる関数を定義しなければなりません。この関数は、float型の3つの変化する入力引数と、それに対応するfloat型の3つの変化する出力引数を取る必要があります。これらの引数は、処理される画像の各ピクセルの赤、緑、青の各成分に対応します。具体的には、この関数は入力画像の各ピクセルに対して呼び出されます。この画像は RGB 形式で、SDR (標準的ディスプレイレンジ) の階調範囲が [0, 1] の区間に対応するように正規化されています (ただし、データは入力でも出力でもこの範囲を超える可能性があります)。デフォルトでは、RGB値はACES 2065-1色空間でエンコードされますが、スクリプトに以下の形式のART色空間タグを挿入することで上書きできます：
// @ART-colorspace: "<colorspace>"
ここで <colorspace> には ACES2065-1（デフォルト）、ACEScg、Rec2020、Rec709、ProPhoto、AdobeRGB のいずれかが入ります。
さらに、ART_mainは、スクリプトのパラメータとして解釈される、int型、float型、bool型の任意の数の一様な引数を取ることができます。このような各パラメータは、CTL スクリプト内で関連する ART パラメータ定義が必要です。ART パラメータ定義は、以下の形式の特別なコメント行で行います：
// @ART-param: <param-def>
ここで、<param-def>はJSON形式の配列で、その内容はパラメータのタイプによって異なります。最初の要素はパラメータ名（ART_mainで使用されている名前と同じでなければなりません）を含む文字列で、2番目の要素はGUIラベルです。配列の残りの部分は次のような構造になっています：
・boolパラメータ (True または False を取るパラメータ) の場合、オプションの3番目の要素はデフォルト値を指定します。代わりにオプションの4番目の要素は、GUIの「グループ名」です：これが設定されると、GUIで指定された名前の折りたたみパネルの下にコントロールが表示されます；
・float (浮動小数点型) パラメータでは、配列のサイズは最低4、最大7でなければなりません。3番目と4番目の要素は、GUIスライダーの最小値と最大値です。オプションの5番目の要素はデフォルト値、オプションの6番目の要素はGUIで使用する精度（例えば0.01はGUIで小数点以下2桁を使用します）、オプションの最後の要素はGUIグループ名です；
・int (整数型) パラメータの場合、配列サイズは少なくとも 3、最大 6 である必要があります。3番目のパラメータが文字列の配列の場合、それは選択メニューのオプションのリストとして解釈され、値は配列のインデックスに対応します（つまり、1番目のオプションは0、2番目は1など）。この場合、配列は最大2つの要素を含むことができ、それぞれデフォルト値とオプションのGUIグループ名となります。
3番目のパラメータが文字列の配列でない場合、配列のサイズは少なくとも4でなければならず、3番目と4番目の要素はGUIスライダの最小値と最大値に対応します。オプションの5番目の要素はデフォルト値で、オプションの最後の要素はGUIグループ名です。
・float (浮動小数点型) 配列は、曲線を 1次元 LUT として表すために使用されます。パラメータ定義に応じて、ART でサポートされている両方の曲線タイプ (つまり、「対角線」と「平坦」) を使用できます。パラメータ定義の配列サイズは、少なくとも 2、最大 8 である必要があります。 3 番目のパラメータは、曲線のタイプを示します。0 は対角線、1 は平坦、2 は制御点付き平坦 (たとえば、ART の色相曲線のような) です。指定しない場合は、デフォルトで 0 が設定されます。4 番目のパラメータを指定した場合は、曲線のデフォルト値を指定します。これは 0 (つまり恒等曲線)、または .rtc 曲線ファイルで使用される形式で曲線のタイプとその制御点を定義する浮動小数点数の配列のいずれかになります。 5 番目と 6 番目のパラメータは、GUI の曲線の下部と左に表示されるグラデーションを定義するために使用できます。最後に、他のパラメータ タイプと同様に、最後の 2 つのオプション要素は GUI グループ名とツールチップ文字列です。
ART パラメータ定義でデフォルト値が指定されていない場合、デフォルト値は ART_main 関数の定義から取得されます。デフォルトが指定されていない場合は、ゼロが使用されます。
以下は、サポートされている各タイプのパラメーター定義の例です。 param_float の場合、必要な最小値と最大値に加えて、デフォルトと GUI の精度も指定します。 param_int の場合は、必要な要素のみが提供されます。 param_bool には、デフォルト値 true が指定されます。最後に、param_choice には、考えられるすべての要素が提供されます。
// @ART-param: ["param_float", "A float slider", -1.0, 1.0, 0.5, 0.1] // @ART-param: ["param_int", "An int slider", -10, 10] // @ART-param: ["param_bool", "A checkbox", true] // @ART-param: ["param_choice", "A combo box", ["Option A", "Option B"], 1, "Choice group"] void ART_main(varying float r, varying float g, varying float b, output varying float r_out, output varying float g_out, output varying float b_out, float param_float, int param_int, bool param_bool, int param_choice) { // ... }
例:
以下は、露出補正を実行するための簡単な ART 互換 CTL スクリプトです。このスクリプトは、適用する露出補正の Ev 値を指定する 1 つのパラメーターを受け取ります。 CTL コードは次のようになります。
// @ART-param: ["expcomp", "Exposure compensation", -5.0, 5.0, 0, 0.1] void ART_main(varying float r, varying float g, varying float b, output varying float r_out, output varying float g_out, output varying float b_out, float expcomp) { const float scale = pow(2, expcomp); r_out = r * scale; g_out = g * scale; b_out = b * scale; }
ART (の「カラー/トーン補正」ツール) に読み込まれたときに GUI 上は次のように表示されます。
より複雑な例
バージョン 1.21 以降、ART には、darktable の シグモイド トーン マッパーの (やや簡易化された) 実装が CTL スクリプトとして同梱されています。これは ART の代替トーン マッパーとして使用でき、「フィルム シミュレーション」モジュールで自動的に利用可能になります (コンパイル時に CTL サポートが有効になっている場合)。
他のサンプルのコレクションは、こちらのリポジトリで入手できます。
CTL スクリプトを自動的に使用可能にする
ART config フォルダーの ctlscripts サブディレクトリ (通常、Linux では $HOME/.config/ART、Windows では %LOCALAPPDATA%\ART) に配置された CTL スクリプトは、起動時に ART によって自動的にロードされ、「カラー /色調補正」ツールの追加操作モードとして使用できます。
たとえば、例示の expcomp.ctl を $HOME/.config/ART/ctlscripts に置くことで、追加モードとして使用できます。
デフォルトでは、ファイル名 (拡張子 .ctl を除く) がモード名として使用されます。これは、次の形式で ART ラベル タグを CTL スクリプトに追加することでカスタマイズできます。
// @ART-label: "<ツール名>"
たとえば、次のように追加します。
// @ART-label: "Simple exposure compensation" (単純な露出補正)
expcomp.ctl に、GUI でより適切な名前で表示されるようになりました。
------------------------------
なお、プログラミングンの際のエラーメッセージを得るには、
$ ART-cli --check-lut $(pwd)/*.ctlで得られます。なお、Ver. 1.21 では、ctl ファイルのパスは、絶対パスで指定してください。
-----------------------------
CTL の説明およびレファレンスマニュアルはこちらから。
