=encoding euc-jp =head1 名前 Image::Size - さまざまなポピュラーな形式の画像の大きさの取得 =head1 概要 use Image::Size; # globe.gifの大きさを取得 ($globe_x, $globe_y) = imgsize("globe.gif"); # この後は、X=60 と Y=40と仮定します。 use Image::Size 'html_imgsize'; # HTML生成のため'width="X" height="Y"'の形式で大きさを取得 $size = html_imgsize("globe.gif"); # $size == 'width="60" height="40"' use Image::Size 'attr_imgsize'; # CGI.pmのルーチンに渡すことができるようなリストで大きさを取得 @attrs = attr_imgsize("globe.gif"); # @attrs == ('-width', 60, '-height', 40) use Image::Size; # メモリ上のバッファの大きさを取得 ($buf_x, $buf_y) = imgsize(\$buf); # $buffがデータであるとします。imgsize()はスカラへのリファレンスを必要とします =head1 説明 BライブラリはAlex Knowles I<(alex@ed.ac.uk)>によって書かれた、 HTMLをチェックし、imageタグに'width'と'height'パラメータを追加するツールである Cスクリプトを元にしています。大きさはファイル名を元に内部でキャッシュ されます。そのため（例えば点がついたリストで使われるような画像のように） 同じファイル名で何回も呼び出しても、計算は繰り返されません。 Bは3つのインターフェースをインポートできるように提供しています: =over =item imgsize(I) XとYの大きさ（順番に幅と高さ）そしてIの画像形式の 3つの要素を持つリストを返します。エラーは前2つの要素が未定義(B)である ことによって示されます。そしてエラー文字列が3番目に入ります。 3番目の要素は無視することができます（そして通常は無視します）。しかし大きさを 調べるデータの形式が分からないときは便利です。 =item html_imgsize(I) Iの幅と高さ(XとY）を、生成されるHTML IMGタグに加えるのに 適したよう'width="X height="Y"'という書式になった1つの文字列で返します。 元になっているCが失敗するとBが返されます。返されるフォーマットは HTMLとXHTMLの両方に適応しています。 =item attr_imgsize(I) Iの幅と高さ(XとY）を、TkやCGIライブラリのような 名前付きパラメータを操作のためにハッシュ・テーブルを使うルーチンに 便利な4つの要素のリストの一部として返します。典型的な戻り値は C<("-width", X, "-height", Y)>です。元になっているCが失敗すると、 Bが返されます。 =back デフォルトではCだけがインポートされます。1つあるいは3つの組み合わせを 明示的にインポートしたり、B<:all>タグで3つすべてをインポートすることができます。 =head2 入力形式 Iとして渡すことができるデータの種類には以下の3つの形式があります： =over =item 文字列 通常のスカラー（文字列）が渡されると、それはファイル名であると想定されます （絶対またはプロセスの作業ディレクトリからの相対のどちらでも）。 そして検索され、（もしあれば）データのソースとしてオープンされます。 発生しうるエラーメッセージ（下記の診断をご覧ください）にはファイル・アクセス 問題が含まれるかもしれません。 =item スカラー・リファレンス streamに渡されたものがスカラー・リファレンスであれば、イメージ・データが入っている メモリ上のバッファを指しているものとして解釈されます。 # &read_dataはデータをどこか（WWWなど）から取得してくるものとします $img = &read_data; ($x, $y, $id) = imgsize(\$img); # $x と $y は大きさ、 $id はイメージの種類です =item オープンされているファイル・ハンドル 3番目の選択肢は既に対象のイメージファイルに結び付けられた、オープンされている ファイルハンドル（例えばCクラスのオブジェクトのような）を渡すことです。 当然、ファイル・ポインタが移動しますが、サブルーチンが終了する前に 元の位置に戻されます。 # 渡された $fh はIO::File へのリファレンスです： ($x, $y, $id) = imgsize($fh); # ファイル名で呼び出すのと同じ。しかしもっと抽象的です =back =head2 理解されるフォーマット Image::Size はそれだけで、以下のフォーマットによるデータを理解し データ大きさを測ります： =over 4 =item GIF =item JPG =item XBM =item XPM =item PPM ファミリー (PPM/PGM/PBM) =item XV サムネイル =item PNG =item MNG =item TIF =item BMP =item PSD (Adobe PhotoShop) =item SWF (ShockWave/Flash) =item PCD (Kodak PhotoCD, see notes below) =back さらにBモジュールがあると、それによってサポートされている 種類も、Image::Sizeによってサポートされます。L<"注意">をご覧ください。 Cインターフェースを使うと、もしプログラマが、それを保存しチェックした ければ、使われない値が3番目に返されます。この値はデータ形式を識別し、 上で挙げたものの2-3文字の省略形で表されます。これはオープンされている ファイル・ハンドルやメモリ上のデータを扱うとき、大きさと同時に形式もわからない 場合に便利です。2つのサポート・ルーチンは、この3番目の戻り値を無視します。 そのため、それを使いたいのであればベースとなるCルーチンを使わなければ なりません。 (自分がサポートしてない全てのファイルのために）代わりにBを 使うとき、データ・タイプ識別子はBにより報告される'format'から 直接やってきます。そのため2-3文字の省略形の形式に合わないかもしれないことに 注意してください。例えばWBMPファイルは、この場合、'Wireless Bitmap (level 0) image' と報告されるでしょう。 =head2 情報のキャッシュとC<$NO_CACHE> ファイル名が大きさを判定する、いずれかのルーチンに渡されると、ライブラリは デフォルトで結果の情報をキャッシュします。キャッシュを削除し更新すべきかを 判定するため、ファイルの更新時刻も記録されます。 これは元々、しばしば同じ画像要素を何度も利用するページのための属性を生成するため、 CGIアプリケーションが、このライブラリを使っていたために追加されました。 しかしキャッシュは、ファイル・システムの更新時刻の解像度を越えるような 頻度でファイルが動的に生成されるときには問題を引き起こすかもしれません。 そのため、オプションでインポートできる制御変数C<$NO_CACHE>が導入されました。 もしこの値がfalseでない値に評価されれば(値1、NULLでない文字列などであれば）、 プログラムが、その変数をfalseに設定することにより再び有効にするまで、 キャッシュは無効になります。 パラメータC<$NO_CACHE>はBルーチンでインポートすることが出来ます。 そしてインポート・タグB>を使ったときにもインポートされます。もし プログラマがそれをインポートしないことを選んだとしても、 B<$Image::Size::NO_CACHE>と完全に修飾されたパッケージ名によりアクセス することができます。 =head2 PhotoCD画像の大きさ判定 バージョン2.95では、Kodak PhotoCD画像形式のサポートが入っています。 しかしこれらの画像ファイルは他のものと大分違っています。 あるファイルは（全て同じ縦横比で）予め決められた解像度での全ての画像の ソースになります。ファイルに本来、特定の解像度にそれを制限するようなものは ないので、ここでの、このサポートはトリッキーです。 ライブラリはスケールとの対応付けを使って、これを処理します。そしてユーザー （あなた）にどのスケールで返して欲しいかを指定するように要求します。前に説明した C<$NO_CACHE>と同じように、これはBを利用するアプリケーションで インポート可能なスカラー変数になります。このパラメータはC<$PCD_SCALE>といい、 同じ名前でインポートされます。これもタグB>を使ってインポートしたり、 B<$Image::Size::PCD_SCALE>で参照することができます。 そのパラメータは以下の値の1つに設定されなければなりません: base/16 base/4 base base4 base16 base64 全てのPhotoCDディスクが解像度Cを持っているわけではないことに 注意してください。PCDフォーマットについてのドキュメントであれば見つけることが できるので、実際の解像度はここの一覧には入っていません。C<$PCD_SCALE>の値は 大文字/小文字を区別しないで扱われます。そのためCはCやCでも 同じです。デフォルトのスケールはCに設定されます。 ライブラリは、要求された解像度が使用できるかどうかを確認するため、 PCDファイルを十分に読み込むという努力はしないということも注意してください。 ここでのポイントは、ライブラリは効率的に処理できるため、必要できるだけ 読み込む量を少なくするということです。このため、発見される唯一、本当の 違いは、画像の方向が縦か横かということです。実際、それだけしかライブラリは 画像ファイルから取り出しません。 =head1 診断 元になるルーチンCは、エラーが発生するとリストの最初の値をBで 返します。3番目の要素は説明のエラーメッセージが入ります。 他の2つのルーチンはエラーの場合、単にBを返します。 =head1 さらなる例 BインターフェースはTk拡張と一緒に使う場合にも適しています: $image = $widget->Photo(-file => $img_path, attr_imgsize($img_path)); CクラスはCと同じようにダッシュがついたオプション名を使うので、 変換は何も要りません。 このパッケージはApache Webサーバコンテキストで使う場合にも適してます。 ファイル・サイズは読込時点でキャッシュされます（変更された場合には、 更新時刻でチェックされます）。子プロセスが1つのリクエストの期間を越えて 残るB環境のための便利な特徴です。 サーバ空間でのフルパス名を取り出すためにサブリクエストを使うという機能のような、 B環境の他の点は、このモジュールにとても適しています。 これはCGIモジュールのHTML生成機能を補足します。CはURLを欲しがりますが、 Cはファイル・パスを必要とします: # $QはCGIクラスのオブジェクトであるとします。$r はApacheリクエスト・オブジェクトです # $imgpathは"/img/redball.gif"のようなURLです。 $r->print($Q->img({ -src => $imgpath, attr_imgsize($r->lookup_uri($imgpath)->filename) })); ここでの利点は、サーバドキュメント・ルートをハード・コードしなくてもよいと いうだけでなく、URLを書換えたり、他を修正する段階も含めて、 通常のリクエスト・ライフサイクルを通してApacheがサブリクエストを渡していく ことです。 =head1 注意 サイズ・データのキャッシングは入力がファイル名であるときにのみ行われます。 オープンされたファイル・ハンドルやスカラー・リファレンスは、信頼性をもって キャッシュ・データのテーブルのためのユニークなキーに変換することができません。 バッファはMD5モジュールを使ってキャッシュすることができます、そしてそれを 将来オプションとするつもりです。しかし現時点では他の要素によって、依存する リストを長くしたくはありません。 Bはハンドルではなくファイル名を扱うので、 その利用はCへの入力がファイル名で与えられた場合に制限されます。 =head1 参考資料 wwwisの説明と取得方法については C, L。 =head1 作者 Perl module interface by Randy J. Ray I<(rjray@blackperl.com)>, original image-sizing code by Alex Knowles I<(alex@ed.ac.uk)> and Andrew Tong I<(werdna@ugcs.caltech.edu)>, used with their joint permission. Some bug fixes submitted by Bernd Leibing I<(bernd.leibing@rz.uni-ulm.de)>. PPM/PGM/PBM sizing code contributed by Carsten Dominik I<(dominik@strw.LeidenUniv.nl)>. Tom Metro I<(tmetro@vl.com)> re-wrote the JPG and PNG code, and also provided a PNG image for the test suite. Dan Klein I<(dvk@lonewolf.com)> contributed a re-write of the GIF code. Cloyce Spradling I<(cloyce@headgear.org)> contributed TIFF sizing code and test images. Aldo Calpini I<(a.calpini@romagiubileo.it)> suggested support of BMP images (which I I should have already thought of :-) and provided code to work with. A patch to allow html_imgsize to produce valid output for XHTML, as well as some documentation fixes was provided by Charles Levert I<(charles@comm.polymtl.ca)>. The ShockWave/Flash support was provided by Dmitry Dorofeev I<(dima@yasp.com)>. Though I neglected to take note of who supplied the PSD (PhotoShop) code, a bug was identified by Alex Weslowski , who also provided a test image. PCD support was adapted from a script made available by Phil Greenspun, as guided to my attention by Matt Mueller I. A thorough read of the documentation and source by Philip Newton I found several typos and a small buglet. Ville SkyttI<(ville.skytta@iki.fi)> provided the MNG and the Image::Magick fallback code.