---

42.17.2 イメージのディスクリプタ

イメージディスクリプタ(image descriptor)とは、イメージにたいする基礎的なデータと表示する方法を指定するリストです。これは通常はオーバーレイプロパティかテキストプロパティdisplay(その他のディスプレー仕様を参照)の値を通じて使用されますが、バッファーにイメージを挿入する便利なヘルパー関数についてはイメージの表示を参照してください。

イメージディスクリプタはそれぞれ(image . props)という形式をもちます。ここでpropsはキーワードシンボルと値のペアーからなるプロパティリストであり、少なくともそのイメージタイプを指定するペアー:type typeを含みます。

イメージのサイズを定義するイメージディスクリプタ:width、:height、:max-width、:max-heightは整数(サイズをピクセルで表現)、あるいは (value . em)という形式をとります。ここでvalueはems³³によるサイズの長さ。1emはフォントサイズと等しく、valueは整数または浮動小数。イメージのサイズは(value . ch)と(value . cw)のフォームで指定することもできる。ここでchは正準文字の高さ、cwは正準文字の幅を意味する。

以下はすべてのイメージタイプにたいして意味のあるプロパティのリストです(以降のサブセクションで説明するように特定のイメージタイプにたいしてのみ意味があるプロパティも存在する):

:type type

イメージタイプ。 イメージのフォーマットを参照のこと。 すべてのイメージディスクリプタは。このプロパティを含まなければならない。

:file file

これはファイルfileからイメージをロードすることを意味する。fileが絶対ファイル名でなければ、それはimage-load-pathのディレクトリーそれぞれから相対的に展開される(イメージの定義を参照)。

:data data

これはrawイメージデータを指定する。すべてのイメージディスクリプタは:dataか:fileのいずれかをもたなければならないが両方もつことはできない。

ほとんどのイメージタイプにたいして、:dataプロパティの値はイメージデータを含む文字列であること。いくつかのイメージタイプは:dataをサポートしない。それ以外のイメージタイプにたいしては:data単独では不十分であり、:dataとともに他のイメージプロパティを使用する必要がある。詳細は以下のサブセクションを参照のこと。

:margin margin

これはイメージ周囲に余分なマージンとして何ピクセル追加するかを指定する。値marginは非負の数値か、そのような数値のペアー(x . y)でなければならない。ペアーならxは水平方向に追加するピクセル数、yは垂直方向に追加するピクセル数を指定する。:marginが指定されない場合のデフォルトは0。

:ascent ascent

これはイメージのアセント(ベースラインの上の部分)に使用するイメージの高さの分量を指定する。値ascentは0から100の数値かシンボルcenterでなければならない。

ascentが数値ならアセントに使用するイメージの高さのパーセンテージであること。

ascentがcenterなら、イメージにたいしてテキストプロパティやオーバーレイプロパティにより指定される方法で、センターライン(そのイメージ位置にテキストを描画する際の垂直方向のセンターライン)の垂直方向中心にイメージが配置される。

このプロパティが省略された場合のデフォルトは50。

:relief relief

これはイメージ周辺にシャドー矩形を追加する。値reliefはシャドーライン幅をピクセルで指定する。reliefが負ならボタンを押下した状態、それ以外はボタンを押下していない状態のイメージでシャドーを描画する。

:width width, :height height

キーワード:widthと:heightはイメージのスケーリングに使用される。いずれか一方のみが指定された場合には、アスペクト比を保つためにもう一方が算出される。両方が指定された場合にはアスペクト比は保たれないかもしれない。

:max-width max-width, :max-height max-height

キーワード:max-widthと:max-heightは、イメージのサイズがこれらの値を超過した場合のスケーリングに使用される。:widthがセットされた場合にはmax-widthより優先されて、:heightがセットされた場合にはmax-heightより優先されるだろうが、それ以外ではこれらのキーワードを望むように混交できる。

:max-widthと:heightが指定されていて:widthが未指定なら、アスペクト比を維持することにより:max-widthを超える幅が要求されるかもしれない。これが発生した場合には、スケーリングは:max-widthを超過しないアスペクト比を維持できるように、小さい値を使用する。:max-heightと:widthが指定されていて:heightが未指定のときも同様。たとえば200x100のイメージがあり:widthを400、:max-heightを150に指定すると、アスペクト比を保持しつつ“max”のセッティングを超過しないようにイメージは最終的には300x150になる。このパラメーターの組み合わせは、“可能なかぎり大きく、ただし利用可能なディスプレイエリア以下でこのイメージを表示せよ”のように指示する簡便な手段である。

:scale scale

イメージ用のスケーリングファクターを指定する数値であること。このファクターをイメージの幅と高さの両方に乗ずることにより、値が1より大きければイメージサイズの拡大、小さければサイズを縮小する。たとえば値0.25はイメージをオリジナルの1/4のサイズにするだろう。このスケーリングにより:max-widthや:max-heightで指定されたイメージの元のサイズより大きくなる場合でも、結果サイズがこれら2つの値を超過することはない。:scaleおよび:height/:widthの両方が指定されたら、高さ/幅は指定されたスケーリング倍率に調整される。

scaleの値はシンボルdefaultでもよい。これはimage-scaling-factorの値を使用することを意味する。値が数値の場合には使用するスケールファクター、auto (デフォルト)ならそのフレームのデフォルトフェイス(低レベルのフォント表現を参照)に使用されているフォントのサイズ(ピクセル)にもとづいてスケーリングファクターを計算することを意味する。特にデフォルトフェイスのピクセル幅が10より大きい場合には、フォント幅10にたいする比率として算出されたファクターによってイメージは拡大される。たとえばデフォルトフォントの幅が15なら、イメージファクター1.5でスケーリングされるだろう。

scaleが与えられなければ、create-imageはimage-scaling-factorに値に応じてイメージをスケーリングする。

:rotation angle

ローテーション角度を度数(degree)で指定する。イメージタイプがimagemagickでなければ、90°の倍数のみをサポート。値が正なら時計回り、負なら反時計回り。ローテーションはスケーリングとクロッピング(cropping: 切り取り、抜き出し)の後に行われる。

:flip flip

tならイメージを水平方向に反転(flip)する。現在のところイメージタイプがimagemagickなら効果はない。垂直方向の反転はイメージの180度回転とこの値を切り替えることによって行われている。

:transform-smoothing smooth

これがtならイメージ変換にスムージングを適用、nilならスムージングを適用しない。使用する正確なアルゴリズムはプラットフォームに依存するが、バイリニアフィルタリング(bilinear filtering)と等価であること。スムージングを無効にすると、もっとも近い類似アルゴリズムを使用する。

このプロパティが未指定なら、create-imageはスケーリングするかしないかを指示するために、ユーザーオプションimage-transform-smoothingを使用する。このオプションはnil (スムージングなし)、t (スムージングを使用)、またはイメージオブジェクトを唯一のパラメーターとして呼び出されてnilかtをリターンする述語関数であること。デフォルトではダウンスケーリングにはスムージングを適用、巨大なアップスケーリングにはスムージングを適用しない。

:index frame

マルチフレームのイメージを参照のこと。

:conversion algorithm

これはイメージを表示する前に適用するべき変換アルゴリズムを指定する。値algorithmは何のアルゴリズムかを指定する。

laplace

emboss

カラーの大きな差異を強調して小さな差異を不鮮明にするラプラスエッジ検出アルゴリズム(Laplace edge detection algorithm)を指定する。無効なボタンのイメージ表示に、これが役立つと考える人もいます。

(edge-detection :matrix matrix :color-adjust adjust) ¶

一般的なエッジ検出アルゴリズムを指定する。matrixは数値からなる9要素のリストかベクターでなければならない。変換されたイメージ内の位置x/yにあるピクセルは、その位置周辺にある元のピクセルから計算される。matrixはx/yに近接する各ピクセルにたいして、そのピクセルが変換先ピクセルに影響するファクター(factor: 要因)を指定する。以下のように要素0はx-1/y-1にあるピクセルのファクター、要素1はx/y-1にあるピクセルにたいするファクター、...を指定する。

  (x-1/y-1  x/y-1  x+1/y-1
   x-1/y    x/y    x+1/y
   x-1/y+1  x/y+1  x+1/y+1)

結果となるピクセルは周辺ピクセルのRGB値を合計したカラーを指定されたファクターで乗じて、その合計をファクター絶対値の合計で除した色強度から計算される。

ラプラスエッジ検出は現在のところは以下のマトリクス

  (1  0  0
   0  0  0
   0  0 -1)

エンボスエッジ検出(Emboss edge-detection)は以下のマトリクスを使用する

  ( 2 -1  0
   -1  0  1
    0  1 -2)

disabled

イメージが無効(disabled)に見えるよう変換することを指定する。

:mask mask

maskがheuristicか(heuristic bg)なら、フレームのバックグラウンドがイメージ背後に見えるようにイメージのクリッピングマスクを構築する。bgが未指定かtなら、イメージ4隅に最頻するカラーをそのイメージのバックグラウンドカラーとみなしてバックグラウンドカラーを決定する。それ以外ならbgはイメージのバックグラウンドとみなすべきカラーを指定するリスト(red green blue)でなければならない。

maskがnilなら、イメージがマスクをもつ場合にはマスクを削除する。マスクを含むフォーマットのイメージは:mask nilを指定することにより削除される可能性がある。

:pointer shape

これはマウスポインターがそのイメージ上にある際のポインターシェイプを指定する。利用可能なポインターシェイプについてはポインターの形状を参照のこと。

:map map ¶

これはイメージにホットスポット(hot spots)のイメージマップを関連付ける。

イメージマップは各要素が(area id plist)という形式をもつalist。areaにはrectangle(矩形)、circle(円)、またはpolygon(ポリゴン、多角形)のいずれかを指定する。

rectangleは矩形エリアの左上隅と右下隅のピクセル座標を指定するコンス(rect . ((x0 . y0) . (x1 . y1)))。

circleは円の中心と半径を指定するコンス(circle . ((x0 . y0) . r))。rは整数か浮動小数点数。

polygonは各ペアーが多角形の1つの頂点を記述するコンス(poly . [x0 y0 x1 y1 ...])。

マウスポインターがホットスポット上にある際には、ホットスポットのplistが参照される。これがhelp-echoプロパティを含むならそのホットスポットのツールチップ、pointerプロパティを含む場合はマウスカーソルがホットスポット上にあるときのマウスカーソルのシェイプを指定する。利用可能なポインターシェイプについてはポインターの形状を参照のこと。

マウスポインターがホットスポット上にあるときにマウスをクリックしたときのイベントは、ホットスポットのidとマウスイベントを組み合わせて構成される。たとえばホットスポットのidがarea4なら[area4 mouse-1]。

このマップの座標はすべての変換(ローテーション、スケーリング等)の後に表示されたイメージを反映する必要があり、更に(デフォルトでは)Emacsの行う自動スケーリングの効果もあるので、イメージ作成時には:scale 1.0を指定するか、マップ要素の計算にimage-compute-scaling-factorの結果を用いる必要があることにも注意。

イメージの:scale、:rotation、:flipが変更されると、:original-mapの値とこれらの変換の値にもとづいて:mapが再計算される。

:original-map original-map ¶

これはイメージの:scale、:rotation、:flipが変更された後に:mapの再計算に使用される未変換のイメージマップを指定する。

create-imageでイメージ作成時に:original-mapを指定しないと、与えられた:map、並びに非nilの:scale、:rotation、:flipにもとづいて計算される。

反対に:original-mapは指定されているが:mapが指定されていなければ、:mapは:original-map、:scale、:rotation、:flipにもとづいて計算される。

User Option: image-recompute-map-p ¶

このユーザーオプションをnilにセットすれば、イメージの:original-mapにもとづいてEmacsが自動的に:mapを再計算することを抑止できる。

Function: image-mask-p spec &optional frame ¶

この関数はイメージspecがマスクビットマップをもつならtをリターンする。frameはそのイメージが表示されるフレーム。frameがnilか省略された場合には選択されたフレームが使用される(入力のフォーカスを参照)。

Function: image-transforms-p &optional frame ¶

この関数はframeがイメージのスケーリングとローテーションをサポートすれば非nilをリターンする。frameがnilか省略なら選択されたフレームの使用を意味する(入力のフォーカスを参照)。リターンされるリストには何のイメージ変換操作がサポートされるかを示すシンボルが含まれる:

scale

frameは:scale、:width、:height、:max-width、:max-heightのプロパティを通じたイメージスケーリングをサポートする。

rotate90

frameはローテーション角度が90°の整数倍ならイメージローテーションをサポートする。

イメージ変換がサポートされていなければ:rotation、:crop、:width、:height、:scale、:max-width、:max-heightは(利用可能なら)ImageMagickを通じた場合のみ使用可能(ImageMagickイメージを参照)。