HDR Shopプラグインの記述

注意：このセクションでは、CまたはC++言語の知識が必要です。

HDR Shopは、ユーザーが新しい画像編集オペレーションを記述し、またそれをHDR Shopのインターフェースに統合できるように、柔軟なプラグイン・アーキテクチャに対応しています。プラグインは特別なスタンドアローン形式のコマンドラインプログラムであり、、コマンドラインの引数からパラメータを受け取ります。HDRShopへのインターフェイスは、コマンドラインの引数と標準のパイプラインを使用するため、プラグインはどのような言語でも記述することができ、画像上で任意のプロセスを行うことができます。このチュートリアルでは、C++を記述言語と仮定して説明します。

簡単な例として、画像をぼかしたり、オプションで半分のサイズに変更したりするプラグインの記述方法を紹介します。

プラグインは、stdin 経由でHDR Shopと通信します。プラグインがシングル・コマンドライン引数"--help" もしくは "/?" で呼び出されたとき、指定のフォーマットでパラメータのリストを出力し、そして終了しなければいけません。このプラグインでは、以下のメッセージを stderr に出力します:

This is a simple test plugin to blur an image.
HDRSHOPFLAGS:
HDRSHOPVERSION: 1.0.1
USAGE: sample_plugin [input.pfm] [output.pfm] [options]
OPTIONS:
 /V:[int=10]  Blur Variance
 /D Downsample 50%

プラグインは、次の各々のブロックにプラグイン自身の情報を示さなければいけません。

• はじめのブロックは、説明書、概要、その他等々のユーザーデータです。HDR Shopは、プラグインが呼ばれたときにユーザーに表示する以外は、これを無視します。
• HDRSHOPFLAGS: 今は、ブランクにしてください。次のバージョンで使う箇所です。
• HDRSHOPVERSION: プラグインが記述されたHDR Shopのバージョンです。
• USAGE: 次の順番で表示してください：プラグインの実行可能ファイル、[input.pfm]プラグインが（pfmフォーマットで）入力画像を必要とする場合、[output.pfm] プラグインが（pfmフォーマットで）出力画像を必要とする場合、[options] プラグインがオプションを必要とする場合。
• OPTIONS: プラグインが許可するコマンドラインのオプション。このデータは、ユーザーがオプションを入力するUIを作成するために、HDR Shopによって解析されます。

オプションは、一行毎に指定されます。各々のオプションは、識別子、オプションのパラメータ記述子、オプションの説明内容を持ちます。各ラインは（空白を無視して）、identifier文字列から始めなければいけません。例えば、 “/V:”と “/D”は、サンプルのプラグインのidentifier文字列です。identifierは、空白またはパラメータ記述子によって終了します。このことは、どのようにオプションを指定したいかに関して、若干のゆとりを与えてくれます。つまり 、“-variance=”や “-downsample”をidentifierとして代わりに使うこともできるのです。

パラメータ記述子は、複数選択で大括弧: {}を使わない限り、四角い括弧: []で囲まれます。四角い括弧の中は、記述子タイプに続けて、任意のデフォルト値が入ります。デフォルト値が記述されていると、HDR Shopはそのオプションの生成されたユーザー・インターフェースをその値に（初期値として）セットします。利用可能なパラメータ記述子のタイプは以下の通りです：

Type タイプ	Descriptor 記述子	Default デフォルト	Example (identifier + descriptor) 例（識別子＋記述子）	Notes 注意
boolean		false	/downsample	このオプションがコマンドラインで示されると、値はtrue、そうでなければfalse
integer	[integer=X],[int=X]	X	--iterations=[int=6]
string	[string=X],[str=X]	X	/greeting:[string=Hello World!]
float	[float=X]	X	/pi=[float]	全ての場合において、もしユーザーがオプションとして値を記述しないなら、そのオプションはコマンドライン引数として渡されない
input filename	[inputfilename=X]	X	/C:[inputfilename=my default.cfg]	プラグインが読むファイルを指定
output filename	[outputfilename=X]	X	/debugout=[outputfilename=debug.txt]	プラグインが書き込むファイルを指定
rectangle	[selection]	注意を参照	/s[selection]	このオプションのユーザー・インターフェースはチェックボックスで、デフォルトでチェックされています。 チェックされたとき、HDRShop 内で現在選択されている画像範囲がプラグインに送られます。フォーマットは：100,100,200,200 （上、左、下、右） 選択されない場合、全体の画像サイズが戻ってきます。
multiple choice	{String1|String2|...|StringN}	String1	--algorithm:{|fast|accurate|weird}	与えられた文字列リストからの複数選択。 1番目の値はデフォルトです。

ユーザーによってプラグインが選択されると、HDR Shopは “sample_plugin –help”を実行し、結果のテキストを解析します。

HDR Shopは次に、ユーザーが全てのプラグイン・オプションの値を入力可能なダイアログ・ボックスを作成します。ユーザーがオプションを選択し、 “Execute”がクリックされると、HDRShop はプラグインを再度呼び出し、今度はパッケージ化された全てのオプションを、コマンドライン引数として送ります。オプションは、上述したフォーマットでプラグインに渡されます。例えば、ユーザーが"Blur Variance" の値として１５を選択すると、HDR Shopはコマンドライン引数/V:15を渡します。そして、ユーザーが "Downsample" オプションを選択すると、HDRShop は引数/D を渡し、そうでなければ引数は渡しません。

画像を操作するプラグインに対して、HDRShop は .pfm ファイルとしてその画像を渡します。これらのファイルをどのように計算するかは、下記の詳細を参照してください。HDR Shopは現行の画像を、一時的な“.pfm”ファイルに記述し、それをプラグインに渡します。プラグインがHDR Shopに画像を返すと想定されるときは、HDR Shopはプラグインがその“.pfm”ファイルを保存するよう、一時ファイルの名前を指定します。

それでは、プラグインの実際のソース・コードを調べてみましょう。

int main(int argc, char *argv[])
{
 char *inputfilename = 0;
 char *outputfilename = 0;
 int downsample = 0;
 int variance = 10;
 
 if (argc == 1) {
  printHelp();
 exit(0);
 }
 
 for (x = 1; x < argc; x++) {
 if (argv[x][0] == '-') {
 if (argv[x][1] == '-') {
 if (strncmp("help", &argv[x][2], 4) == 0) {
 printHelp();
 exit(0);
 }
 }
 }
 else if (argv[x][0] == '/') {
 switch(argv[x][1]) {
 case '?':
 printHelp();
 exit(0);
 break;
 case 'V':
 variance = atoi(argv[x]+3);
 break;
 case 'D':
 downsample = 1;
 break;
 }
 }
 else {
 if (inputfilename == 0) 
 inputfilename = argv[x];
 else 
 outputfilename = argv[x];
 }
 }
 ...

このセクションでは、コマンドライン引数を分析しています。プログラムが "/?" または "--help" を通過すると、上に詳述したメッセージを stderr にプリントしてプログラムを終了する printHelp()が呼び出されます。そうでなければ、プログラムはコマンドライン・オプションを指示するために、 “/（スラッシュ）”を探します。オプションが “?”の場合、 “help”メッセージがプリントされます。オプションが“V”の場合は、variance(分散)の整数の値を求めて文字列の残りの箇所を通過します。オプションが“D”の場合は、 “downsample”フラグをtrueにセットします。最後に、コマンドライン引数がオプションではない場合、それは入力ファイル名として認識されます。もし、入力ファイル名がすでに認識されていたら、それは出力ファイル名として認識されます。

 if (!inputfilename)
 doError(1);
 if (!outputfilename)
 doError(2);
 
 floatimage fimg;
 if (!fimg.LoadPFM(inputfilename))
 doError(3);
 
 fimg.fast_gaussian_blur(variance);
 if (downsample)
 fimg.halfsize();
 
 if (!fimg.SavePFM(outputfilename))
 doError(4);
 
 return 0;
}

ファンクション“doError()”はStdErrにエラーの文字列をプリントします。そして、HDR Shopに対し、エラーが生じたことを示すため、ゼロで無い値とともに “exit()”を呼び出します。HDR Shopは、ユーザーに対し、Stderrに出力された全てをエラーメッセージとして表示します。 “floatimage”クラスは、ユーティリティのクラスです。このクラスは、多様なフォーマットからなるファイルの入出力や、アンチエイリアスのピクセル読み込み、ぼかし、畳み込み(convolution)、その他のユーティリティなど、数多くの便利な機能を提供します。“floatimage”の全ソースコードと、サンプル・プラグインは、ここからダウンロードできます。

プラグインが実行可能ファイルとしてコンパイルできたら、HDRShop の実行ファイルが存在するディレクトリのサブディレクトリ "plugins" に配置しなければいけません。プラグイン名は、HDR Shopのメニューバー “plugins”のプルダウンメニューに表示されるでしょう。

「参考：HDRShopの日本語訳」に戻る