パーセントエスケープの処理

画像には、実際の画素データ以外にも大量の付随データ（メタデータ）が関連付けられています。このメタデータは、表示・各種計算・後続の画像処理操作の挙動変更などに役立ちます。多くのオプション、たとえば -format や montage の -label などでパーセントエスケープを利用し、画像に関連付けられたさまざまなプロパティや設定を出力できます。

プロファイルデータ	EXIF: データなど。焦点距離・露出・日付、場合によっては GPS 位置情報を含みます。
属性（Attributes）	画像データに直接関わるもので、通常の画像処理の一環としてより一般的に変更されます。幅・高さ・深度・画像タイプ（カラースペース）・タイミング遅延・背景色などが含まれます。大部分の専用パーセントエスケープはこの情報へのアクセスのためにあります。
プロパティ（Properties）	自由形式の文字列のテーブルとして格納され、（可能であれば）画像とともに保存されます（特に MIFF・PNG 画像ファイル形式）。ラベル・キャプション・コメントなどが含まれます。
アーティファクト（Artifacts）	さまざまな演算子が使用する、または将来の利用のためにユーザーが保存しておく各種の動作（上級者向け）設定です。単なる自由形式文字列のテーブルです。画像を書き出すときには保存されません。詳細は後述の「アーティファクトとオプション」を参照してください。
オプション（Options）	これも各種演算子が使用する動作（上級者向け）設定ですが、画像リスト全体に対してグローバルに設定されます（同じく保存されません）。後述の「アーティファクトとオプション」を参照してください。

%[key] のようなパーセントエスケープを要求すると、最初の一致が見つかるまで以下の順序で設定が探索されます…

'artifact:' 'option:' 'exif:' 'fx:' などの特殊なプレフィックスを処理します。これにはそれらのプレフィックスの計算やグロブ（'exif:' や 'artifact:' など）も含まれます（後述）。
key にグロブパターンが含まれる場合（ただし既知のプレフィックスがない場合）、自由形式のプロパティテーブルを検索します。
key が特殊な画像「属性」名（上記リスト参照）であれば、関連付けられた、または計算された画像属性を返します。
自由形式の「プロパティ」として設定を検索します。
自由形式の「アーティファクト」として設定を検索します。
自由形式の「オプション」として設定を検索します。
エスケープを空文字列に置き換え、場合によっては警告を出します。

なお、ロングネーム形式のパーセントエスケープはすべて大文字小文字を区別せずに処理されます。

アーティファクトおよびオプションの自由形式文字列テーブルに直接アクセスできるようになり、上記の順序を上書きして、同名の属性やプロパティへのアクセスを回避できます。

%[artifact:setting]
%[option:setting]

エスケープの処理には画像コンテナへのアクセスが必要です。利用可能なものがない場合、式を処理して値を返せるように空白の画像が作成されます。たとえば magick -print "%[fx:.8765/3.14]" null: null: のようになります。

1 文字属性パーセントエスケープ

画像の最も一般的な属性やプロパティ（画像のファイル名・タイプ・幅・高さなど）を出力するために使われる、一般的な 1 文字エスケープ（短縮形）を以下に示します。

\	バックスラッシュ。次の文字をリテラルとして扱い、解釈の対象としません
\n	改行
\r	キャリッジリターン
<	小なり記号
>	大なり記号
&	アンパサンド記号
%%	パーセント記号
%b	読み込んだ画像のファイルサイズ（B 単位で強制するには -precision 16 を使用）
%c	comment メタデータプロパティ
%d	パスのディレクトリ部分
%e	ファイル名の拡張子またはサフィックス
%f	ファイル名（サフィックスを含む）
%g	レイヤーのキャンバスページジオメトリ（"%Wx%H%X%Y" と等価）
%h	現在の画像の高さ（ピクセル）
%i	画像のファイル名（注: "info:" の場合は出力ファイル名になる）
%k	計算値: 一意な色の数
%l	label メタデータプロパティ
%m	画像ファイル形式（ファイルマジック）
%n	現在の画像シーケンス内の画像数。フレームごとに 1 回報告
%o	出力ファイル名（デリゲートで使用）
%p	現在の画像リスト内における画像のインデックス
%q	量子化深度（コンパイル時定数）
%r	画像クラスとカラースペース
%s	シーン番号（再割り当てされていなければ入力由来）
%t	ディレクトリおよび拡張子（サフィックス）を除いたファイル名
%u	一意な一時ファイル名（デリゲートで使用）
%w	現在の幅（ピクセル）
%x	x 解像度（密度）
%y	y 解像度（密度）
%z	画像の深度（変更されない限り読み込み時のもの。画像保存深度）
%A	画像の透過チャンネル。値には Undefined（透過チャンネルなし）・Blend・Copy・Update があります。
%B	読み込んだ画像のファイルサイズ（バイト単位）
%C	画像の圧縮タイプ
%D	画像の GIF 破棄メソッド
%G	元の画像サイズ（%wx%h。あらゆるリサイズ前）
%H	ページ（キャンバス）の高さ
%M	Magick ファイル名（読み込み修飾子を含む、与えられたとおりの元ファイル）
%N	現在の画像シーケンス内の画像数。画像シーケンスごとに 1 回報告
%O	ページ（キャンバス）オフセット（ = %X%Y）
%P	ページ（キャンバス）サイズ（ = %Wx%H）
%Q	画像の圧縮品質（0 = デフォルト）
%S	?? シーン ??
%T	画像の時間遅延（センチ秒）
%U	画像の解像度単位
%W	ページ（キャンバス）の幅
%X	ページ（キャンバス）の x オフセット（符号を含む）
%Y	ページ（キャンバス）の y オフセット（符号を含む）
%Z	一意なファイル名（デリゲートで使用）
%@	計算値: トリム境界ボックス（実際にはトリムしない）
%#	計算値: 画像値の「シグネチャ」ハッシュ

以下は、ファイル名 bird.miff、幅 512、高さ 480 の画像に対するサンプルコマンドとその出力です。

-> identify -format "%m:%f %wx%h" bird.miff
MIFF:bird.miff 512x480

なお、すべての 1 文字パーセントエスケープはロングフォームでも使用できます（IM バージョン 6.7.6-9 以降。次節参照）。たとえば %[f] は短縮形 %f と等価です。

警告: 短縮形のパーセントエスケープは、パーセントが数値の後にある場合には実行されません。たとえば 10%x10 では %x はパーセントエスケープとして展開されません。明示的に 'x' を展開したい場合は、この特殊ケースを上書きするロングフォームを使用してください。例: 10%[x]10。

また、計算による属性は生成に時間がかかることがあり、特に大きな画像で顕著です。

ロングフォーム属性パーセントエスケープ

上記の専用属性および計算属性に加えて、波括弧で囲んだ（ロングフォーム）次の指定も認識されます。

%[basename]	サフィックスなしの基本ファイル名（%t と同じ）
%[bit-depth]	画素データの実際のビット深度
%[bounding-box]	画像の境界ボックスの左上隅と右下隅
%[caption]	caption メタデータプロパティ
%[caption:lines]	キャプションを折り返した際に生成された行数を返す
%[caption:pointsize]	caption: 処理中に計算されたポイントサイズを返す
%[channels]	カラースペースのニーモニックに続く総チャンネル数とメタチャンネル数。例: `cmyka 8.3` は、アルファチャンネルを持つ CMYK 画像で合計 8 チャンネル・3 メタチャンネルを示す。
%[colors]	画像内の一意な色の数（IM 7.0.3.8 以降）
%[colorspace]	画像データのカラースペース（透過を除く）
%[compose]
%[compression]	画像の圧縮タイプ
%[convex-hull]	前景オブジェクトを囲む凸包を形成する点群。-define convex-hull:background-color=color で画像の背景色を指定する。背景色が一様でない場合は -fuzz を使用する。
%[convex-hull:extreme-points]	凸包の上・右・下・左の極点を返す。
%[copyright]	ImageMagick の著作権文字列
%[depth]	書き出し用の画像の深度（変更されない限り入力どおり）
%[deskew:angle]	傾き補正の角度（回転の度）
%[directory]	ファイル名のディレクトリ部分（%d と同じ）
%[distortion]	参照画像にどれだけ似ているか（-compare）
%[dominant-color]	画像の主要色を 16 進で返す。使用前に -kmeans を実行する。
%[entropy]	計算値: 画像のエントロピー
%[extension]	ファイル名の拡張子部分（%e と同じ）
%[gamma]	画像のガンマ値
%[group]	??? ウィンドウグループ ???
%[height]	画像の元の高さ（読み込み時）
%[histogram:contrast-stretch]	計算されたコントラストストレッチの最小・最大パーセンテージ
%[histogram:linear-stretch]	計算された線形ストレッチの最小・最大パーセンテージ
%[input]	入力画像のファイル名
%[interlace]	画像のインターレースモード（IM 7.0.3.8 以降）
%[kurtosis]	計算値: 画像の尖度統計量
%[label]	label メタデータプロパティ
%[label:pointsize]	label: 処理中に計算されたポイントサイズを返す
%[magick]	画像の読み込みに使われたコーダー（ファイルサフィックスではない）
%[max]	計算値: 画像の最大値統計量
%[mean]	計算値: 画像の平均値統計量
%[median]	計算値: 画像の中央値統計量
%[min]	計算値: 画像の最小値統計量
%[minimum-bounding-box]	-define convex-hull:background-color=color で画像の背景色を指定する。背景色が一様でない場合は -fuzz を使用する。境界ボックスの点に加えて、minimum-bounding-box:area、minimum-bounding-box:width、minimum-bounding-box:height、minimum-bounding-box:angle、minimum-bounding-box:unrotate のプロパティも設定される。
%[opaque]	計算値: 画像は完全に不透明か?
%[orientation]	画像の向き
%[page]	仮想キャンバス（ページ）ジオメトリ
%[papersize:name]	72DPI における name の用紙サイズ（ピクセル）（例: papersize:A4）
%[printsize.x]	X 印刷サイズ
%[printsize.y]	Y 印刷サイズ
%[profile:icc]	ICC プロファイル情報
%[profile:icm]	ICM プロファイル情報
%[profiles]	埋め込まれたプロファイルの一覧
%[quality]	画像品質値（IM 7.0.3.8 以降）
%[rendering-intent]	画像のレンダリングインテント（IM 7.0.3.8 以降）
%[resolution.x]	X 密度（解像度）。単位なし
%[resolution.y]	Y 密度（解像度）。単位なし
%[scene]	入力ファイル内の画像の元のシーン番号
%[size]	画像の元のサイズ（読み込み時）
%[skewness]	計算値: 画像の歪度統計量
%[standard-deviation]	計算値: 画像の標準偏差統計量
%[type]	計算値: 画像タイプ
%[unique]	一意な一時ファイル名 ???
%[units]	画像の解像度単位
%[version]	実行中のこの ImageMagick のバージョン情報
%[width]	画像の元の幅（読み込み時）
%[zero]	ゼロ（デリゲート用の一意なファイル名）

プロパティ

上記以外のロングフォームのパーセントエスケープ（1 文字ロングフォームを除く）は、すべて大文字小文字を区別せずに処理されます。そのようなエスケープは、その名前で特定のデータソースを参照しようとします。

主な検索対象は（上記の特定の属性でなければ）自由形式のプロパティ文字列です。そのような文字列は画像に関連付けられて保存され、通常は -set CLI オプション（または API の同等物）か、便利な専用オプション（-label・-comment・-caption など）で設定されます。

これらの便利なオプションはグローバルに保存され（「グローバルオプション」として、画像を読み込む前に設定できます）、後で画像が読み込まれたときにのみ個々の画像のプロパティへ転送されます。その時点で、内部に存在するパーセントエスケープが処理されます。

すでにメモリ上にある画像のプロパティを変更するには、-set を使用する必要があります。

なお、プロパティは属性（やプロファイル）と同様に、画像ファイル形式が許せば書き出し時に画像とともに保存されます。

アーティファクトとオプション

これまでのパーセントエスケープは、主に属性（Attributes）とプロパティ（Properties）に関連付けられたものでした。これがそうしたパーセントエスケープの本来かつ主たる対象です。

しかし、さまざまな ImageMagick 演算子が使用する動作設定の多くは、設定して後でアクセスできると便利です。これらは、画像ごとのアーティファクトと、グローバルオプション（画像のリスト、通常は現在の画像リストに関連付けられる）から成ります。

アーティファクトとプロパティの主な違いは、アーティファクトが内部の動作設定であるため、（可能であっても）画像とともに保存されないという点です。

たとえば -define 'distort:viewport=100x100' を使用すると、実際にはグローバルオプションが生成され、-distort 演算子がそれを使って挙動（歪み出力画像の「ビュー」）を変更します。

オプションは本質的に、画像のリスト（具体的には画像の「Wand」）の一部としてグローバルに格納されたアーティファクトです。したがって両者は同一であり、オプションは関連付けられたすべての画像に対するグローバルなアーティファクトにすぎません。

そのため、-set 'option:distort:viewport' '100x100' を使って、distort 操作が使用するアーティファクトを設定するのと同じ結果が得られます。

グローバルオプションの内部処理…

コアライブラリ（'MagickCore'）は通常、グローバルオプションを直接は理解しません。前の例を続けると、DistortImages() 関数は 'viewport' が提供されているかどうかを調べるためにアーティファクトのみを参照します。

ライブラリ関数がアーティファクトを要求したときにグローバルオプションがどう使われるかは、IMv6 と IMv7 の主要な違いの 1 つです。

グローバルオプションのデータへのリンクが設定されるため、特定の画像ごとのアーティファクトが見つからない場合、その画像リストの同等なグローバルオプションを直接探します。これにより、こうした自由形式オプションを繰り返しアーティファクトへコピーする必要がなくなり、リストに対するグローバルオプションと、そのリスト内の特定画像に対する上書き用の個別アーティファクトを別々に定義できるようになります。

なお、Wand を使用しない API も多くあります（たとえば PerlMagick は Wand ではなく画像の配列を使用します）。これらの API ではグローバルオプションは存在せず、画像ごとのアーティファクトのみです。

要するに、グローバルオプションは（利用可能であれば）画像ごとのアーティファクトと等価です。

プロパティ・アーティファクト・オプションのグロブパターンによる列挙

設定にはグロブパターンを含められます。これにより、すべての自由形式文字列のプロパティ・アーティファクト・オプション（ただし特定の画像属性は除く）を次のように列挙できます…

magick ... \
   -print "__Properties__\n%[*]" \
   -print "__Artifacts__\n%[artifact:*]" \
   -print "__Options__\n%[option:*]" \
   ...

グロブパターンの形式は非常に特殊で、画像処理での利用というよりは、デバッグ時などに特定の設定を列挙するために一般的に使われます。

計算系パーセントエスケープのプレフィックス

最初の ':' より前に置く特殊なプレフィックスのいくつかは、その後に続くユーザー指定の文字列に基づいて計算を行います。たとえば、与えられた FX 式を評価する数値計算には %[fx:...] を使用します。

%[fx:expression]

FX 式で定義された画素の色を評価するには pixel: または hex: を使用します。

%[pixel:expression]

色の準拠規格を指定するには -define を使用します（例: -define pixel:compliance=css）。

特定プロファイルのパーセントエスケーププレフィックス

読み込んだ画像に含まれていた EXIF 画像メタデータを出力するには、次の特殊な書式構文も使用できます。

%[EXIF:tag]

tag は以下から選びます。

*  (すべての EXIF タグを keyword=data 形式で出力)
!  (すべての EXIF タグを tag_number data 形式で出力)
#hhhh (EXIF タグ #hhhh のデータを出力)
ImageWidth
ImageLength
BitsPerSample
Compression
PhotometricInterpretation
FillOrder
DocumentName
ImageDescription
Make
Model
StripOffsets
Orientation
SamplesPerPixel
RowsPerStrip
StripByteCounts
XResolution
YResolution
PlanarConfiguration
ResolutionUnit
TransferFunction
Software
DateTime
Artist
WhitePoint
PrimaryChromaticities
TransferRange
JPEGProc
JPEGInterchangeFormat
JPEGInterchangeFormatLength
YCbCrCoefficients
YCbCrSubSampling
YCbCrPositioning
ReferenceBlackWhite
CFARepeatPatternDim
CFAPattern
BatteryLevel
Copyright
ExposureTime
FNumber
IPTC/NAA
EXIFOffset
InterColorProfile
ExposureProgram
SpectralSensitivity
GPSInfo
ISOSpeedRatings
OECF
EXIFVersion
DateTimeOriginal
DateTimeDigitized
ComponentsConfiguration
CompressedBitsPerPixel
ShutterSpeedValue
ApertureValue
BrightnessValue
ExposureBiasValue
MaxApertureValue
SubjectDistance
MeteringMode
LightSource
Flash
FocalLength
MakerNote
UserComment
SubSecTime
SubSecTimeOriginal
SubSecTimeDigitized
FlashPixVersion
ColorSpace
EXIFImageWidth
EXIFImageLength
InteroperabilityOffset
FlashEnergy
SpatialFrequencyResponse
FocalPlaneXResolution
FocalPlaneYResolution
FocalPlaneResolutionUnit
SubjectLocation
ExposureIndex
SensingMethod
FileSource
SceneType

書式指定は引用符で囲み、シェルが空白や角括弧を誤って解釈しないようにしてください。

ファイルに含まれる IPTC 情報を出力するには、次の特殊な書式構文を使用できます。

%[IPTC:dataset:record]

dataset と record は以下から選びます。

  Envelope Record
  1:00  Model Version
  1:05  Destination
  1:20  File Format
  1:22  File Format Version
  1:30  Service Identifier
  1:40  Envelope Number
  1:50  Product ID
  1:60  Envelope Priority
  1:70  Date Sent
  1:80  Time Sent
  1:90  Coded Character Set
  1:100  UNO (Unique Name of Object)
  1:120  ARM Identifier
  1:122  ARM Version

Application Record
  2:00  Record Version
  2:03  Object Type Reference
  2:05  Object Name (Title)
  2:07  Edit Status
  2:08  Editorial Update
  2:10  Urgency
  2:12  Subject Reference
  2:15  Category
  2:20  Supplemental Category
  2:22  Fixture Identifier
  2:25  Keywords
  2:26  Content Location Code
  2:27  Content Location Name
  2:30  Release Date
  2:35  Release Time
  2:37  Expiration Date
  2:38  Expiration Time
  2:40  Special Instructions
  2:42  Action Advised
  2:45  Reference Service
  2:47  Reference Date
  2:50  Reference Number
  2:55  Date Created
  2:60  Time Created
  2:62  Digital Creation Date
  2:63  Digital Creation Time
  2:65  Originating Program
  2:70  Program Version
  2:75  Object Cycle
  2:80  By-Line (Author)
  2:85  By-Line Title (Author Position) [Not used in Photoshop 7]
  2:90  City
  2:92  Sub-Location
  2:95  Province/State
  2:100  Country/Primary Location Code
  2:101  Country/Primary Location Name
  2:103  Original Transmission Reference
  2:105  Headline
  2:110  Credit
  2:115  Source
  2:116  Copyright Notice
  2:118  Contact
  2:120  Caption/Abstract
  2:122  Caption Writer/Editor
  2:125  Rasterized Caption
  2:130  Image Type
  2:131  Image Orientation
  2:135  Language Identifier
  2:150  Audio Type
  2:151  Audio Sampling Rate
  2:152  Audio Sampling Resolution
  2:153  Audio Duration
  2:154  Audio Outcue
  2:200  ObjectData Preview File Format
  2:201  ObjectData Preview File Format Version
  2:202  ObjectData Preview Data

Pre-ObjectData Descriptor Record
  7:10   Size Mode
  7:20   Max Subfile Size
  7:90   ObjectData Size Announced
  7:95   Maximum ObjectData Size

ObjectData Record
  8:10   Subfile

Post ObjectData Descriptor Record
  9:10   Confirmed ObjectData Size