GD-2.02

名前
概要
説明
オブジェクト・コンストラクタ：イメージの作成
GD::Imageメソッド
多角形
- GD::Polyline
フォント・ユーティリティ
gdのC言語バージョンの取得
作者
参考資料

名前¶

GD.pm - Gdグラフィックス・ライブラリへのインターフェース

概要¶

    use GD;

    # 新しいイメージを作成
    $im = new GD::Image(100,100);

    # いくつかの色を確保
    $white = $im->colorAllocate(255,255,255);
    $black = $im->colorAllocate(0,0,0);       
    $red = $im->colorAllocate(255,0,0);      
    $blue = $im->colorAllocate(0,0,255);

    # 背景色を透明にし、インターレース化
    $im->transparent($white);
    $im->interlaced('true');

    # 絵の周りを黒く縁取り
    $im->rectangle(0,0,99,99,$black);

    # 青い楕円形を描画
    $im->arc(50,50,95,75,0,360,$blue);

    # 赤で塗りつぶし
    $im->fill(50,50,$red);

    # バイナリ・ストリームへ書きこむことを確実にする
    binmode STDOUT;

    # イメージをPNGに変換し、標準出力に出力
    print $im->png;

説明¶

GD.pmは、Thomas Boutellのgdグラフィックライブラリ(バージョン2.01以降;下記参照)をへのPerlインターフェースです。 GDモジュールを使うことによって、各種のグラフィック関連メソッドを使って絵を作成し、PNGファイルとしてその絵を出力することが出来ます。

GDモジュールは以下の3つのクラスを定義しています:

GD::Image: 画像イメージのクラス。画像データを保持し、グラフィックの基本的なメソッドを受け付けます。
GD::Font: フォントのクラス。静的フォント情報を保持し、テキストの描画するときに利用されます。
GD::Polygon: 簡単な多角形のクラス。画像イメージに多角形を描画するための頂点のリストを保持します

簡単な例:

    #!/usr/local/bin/perl

    use GD;
    
    # 新しいイメージを作成
    $im = new GD::Image(100,100);

    # いくつかの色を確保
    $white = $im->colorAllocate(255,255,255);
    $black = $im->colorAllocate(0,0,0);       
    $red = $im->colorAllocate(255,0,0);      
    $blue = $im->colorAllocate(0,0,255);

    # 背景色を透明にし、インターレース化
    $im->transparent($white);
    $im->interlaced('true');

    # 絵の周りを黒く縁取り
    $im->rectangle(0,0,99,99,$black);

    # 青い楕円形を描画
    $im->arc(50,50,95,75,0,360,$blue);

    # 赤で塗りつぶし
    $im->fill(50,50,$red);

    # バイナリ・ストリームへ書きこむことを確実にする
    binmode STDOUT;

    # イメージをPNGに変換し、標準出力に出力
    print $im->png;

Notes:

1. 新しい空の画像イメージを作成するには、GD::Imageにnewメッセージを送り、作成するイメージの幅と高さを指定します。新しい画像イメージオブジェクトが返されます。他のクラスメソッドにより、画像イメージを既存のJPG、PNG、GD、 GD2、XBMファイルにより初期化することができます。
2. 次に、通常は色を画像イメージのカラーテーブルに追加します。色はcoloAllocate()メソッドを呼び出して追加します。それぞれの呼び出しの3つのパラメータは希望の色の赤、緑、青(bgb)の3つの値を示します。このメソッドは画像イメージのカラーテーブルでのインデックスを返します。後で使うため、このインデックスを取っておく必要があります。
3. これで描画をおこなうことができます！様々な描画関数については、後で説明します。この例ではテキストの描画、楕円形の作成と描画、多角形の作成と描画を行っています。
4. 多角形はGD::Polygonへのnewメッセージにより作成します。返される多角形に addPt()メソッドによって１つずつ頂点を追加できます。多角形は描画するために画像イメージへ渡します。
5. 描画が終わったら、画像イメージをpng()メッセージを送ることにより、 PNG形式に変換することができます。画像イメージのバイナリデータをもつ（潜在的に巨大な）スカラー値を返します。普通はこの時点で印刷したり、ファイル保存します。テキストとバイナリファイルの扱い方が違うプラットホームへの可搬性を保証するため、画像イメージを書きこむファイルにbinmode()を呼び出します。

オブジェクト・コンストラクタ：イメージの作成¶

以下のクラスメソッドを使って新しいGD::Imageオブジェクトを作成することができます。

$image = GD::Image->new([$width,$height],[$truecolor])

$image = GD::Image->new(*FILEHANDLE)

$image = GD::Image->new($filename)

$image = GD::Image->new($data)

new()メソッドがGD::Imageクラスのための主たるコンストラクタです。 2つの整数値の引数で呼び出されると、それは指定された幅と高さの新しい空のイメージを作成します。例えば：

    $myImage = new GD::Image(100,100) || die;

これは100 x 100ピクセルの画像イメージを作成します。指定しなければ、デフォルトで64×64になります。

オプションである3番目の引数$truecolorは、new()にtruecolor GD::Image オブジェクトを作成するよう伝えます。Truecolorイメージは色データを 24ビット(赤、緑、青のチャンネルそれぞれに8ビット)で持ち、写真品質(photograph-quality)精度の色を使うことを可能にします。指定されなければイメージは古いバージョンのlibgdと互換性のため 8ビット・パレットを使用します。

代わりにオープンされているファイルハンドル、ファイル名またはイメージデータそのものを与えることにより、既存のイメージを元にGD::Imageオブジェクトを作成することもできます。自動的に理解され、受け付けられるイメージのフォーマットは：PNG, JPEG, XPM そして GD2です。 GIF, WBMP, そして GD バージョン 1を含む他のフォーマットは現時点では自動的には理解されません。

うまくいかなかった場合（例えば、メモリが不充分だった場合など）には、undefを返します。

$image = GD::Image->trueColor([0,1])

前のバージョンのGDのスクリプトとの後方互換性のため、スクラッチ(幅、高さ）から作成された新しいイメージは、デフォルトではパレットベースになります。このデフォルトをイメージがtrue colorを使うよう変更するためには、新しいイメージを作成するためのどこかで以下のようにしてください:

    GD::Image->trueColor(1);

デフォルトであるパレット使用に戻すためには、以下のようにしてください:

    GD::Image->trueColor(0);

$image = GD::Image->newPalette([$width,$height])

$image = GD::Image->newTrueColor([$width,$height])

newPalette() と newTrueColor()メソッドは、trueColor()の現在の設定に関係なく、明示的にパレット・ベースあるいはtrue colorイメージを作成するために使うことが出来ます。

$image = GD::Image->newFromPng($file, [$truecolor])

$image = GD::Image->newFromPngData($data, [$truecolor])

newFromPng()メソッドは与えられたファイルハンドルまたはパスを通して読み取られるPNGファイルからイメージを作成します。ファイルハンドルは適切なPNGファイルまたはパイプに対して、あらかじめオープンされていなければなりません。正常にいくと、好きなように扱うことが出来る、初期化されたイメージを返します。失敗した場合、それは通常、ファイルハンドルが適切なPNGファイルでなかったときなどにおこりますが、呼び出しはundefを返します。この呼び出しはあなたの代りにファイルハンドルを自動的にクローズしないことに注意してください。しかしこれが問題となるプラットフォームでは、あなたの代りにbinmode(FILEHANDLE)はおこないます。

オプションのtruecolor (0/1)値は、返されるイメージがパレットベースか truecolorかを指定するtrueColor()のグローバルな設定をオーバーライドするために使うことができます。

引数として以下のいずれかを渡すことが出来ます:

  1) STDINのような、単なるファイルハンドル
  2) *PNGのような、ファイルハンドル・グロブ
  3) \*PNGのような、グロブへのリファレンス
  4) IO::Fileオブジェクト
  5) ファイルのパス名

最後の場合、newFromPng()は、あなたに代ってファイルをオープンし、 PNG情報をそれから読み込もうとします。

  例1:

  open (PNG,"barnswallow.png") || die;
  $myImage = newFromPng GD::Image(\*PNG) || die;
  close PNG;

  例2:
  $myImage = newFromPng GD::Image('barnswallow.png');

大きさや色の情報を取得するために、後で説明する問い合わせメソッドを使うことができます。

newFromPngData()メソッドは$dataに入ったPNGフォーマットデータで初期化された新しいGD::Imageを作成します。

$image = GD::Image->newFromJpeg($file, [$truecolor])

$image = GD::Image->newFromJpegData($data, [$truecolor])

これらはJPEGファイルからイメージを作成します。これはnewFromPNG()、newFromPngData()と同じように機能し、同じファイルハンドルとパス名の引数を受取ります。オプションのtruecolor (0/1)値は、返されるイメージがパレットベースか truecolorかを指定するtrueColor()のグローバルな設定をオーバーライドするために使うことができます。

JPEGが24ビット形式で、GDは8ビットであることに気をつけてください。つまり写真のような画像がポスタライズされてしまうということです。

$image = GD::Image->newFromXbm($file)

これはnewFromPngとまったく同じように機能しますが、 Xビットマップ(白黒）ファイルの内容を読み込みます:

    open (XBM,"coredump.xbm") || die;
    $myImage = newFromXbm GD::Image(\*XBM) || die;
    close XBM;

newFromXbmData()関数はありません。これは対応する関数がgdライブラリにないためです。

$image = GD::Image->newFromWMP($file)

これは新しいGD::IamgeオブジェクトをWBMPフォーマットのファイルやファイルハンドルから作成します。現在はnewFromWMPData()メソッドはありません。

$image = GD::Image->newFromGd($file)

$image = GD::Image->newFromGdData($data)

これらのメソッドはGD::ImageをGdファイル、ファイルハンドルまたはデータで初期化します。GdはTom Boutellのディスクベースの格納形式です。あまりないケースですが、ディスクに高速にイメージを書きこんだり、読み込んだりする必要があるときに向いています。しかし、一般的な使用には向いていません。というのもGIFやJPEGとは違いイメージを圧縮しないために、ファイルが巨大になるためです。

    $myImage = newFromGd GD::Image("godzilla.gd") || die;
    close GDF;

$image = GD::Image->newFromGd2($file)

$image = GD::Image->newFromGd2Data($data)

これはnewFormgd()とまったく同じように機能します。しかし新しい圧縮された GD2イメージ形式を使います。

$image = GD::Image->newFromGd2Part($file,srcX,srcY,width,height)

このクラス・メソッドはGDバージョン2イメージファイルの一部だけを読み込むことを可能にします。ファイルハンドルに加えて、読み込む画像領域の左上の角と範囲（幅、高さ）を受け取ります。例えば:

    open (GDF,"godzilla.gd2") || die;
    $myImage = GD::Image->newFromGd2Part(\*GDF,10,20,100,100) || die;
    close GDF;

これは位置(10,20)から始まる100x100の画像の四角い部分を読み込みます。

$image = GD::Image->newFromXpm($filename)

これは新しいGD::Imageオブジェクトをファイル名から作成します。これは他のnewFrom()関数とは違います、というのもこれはファイルハンドルを取らないからです。この違いは元になっているgdライブラリで一貫性が無いことから来ています：

    $myImage = newFromXpm GD::Image('earth.xpm') || die;

この関数はlibgdがXPMサポート付きでコンパイルされているときにのみ使えます。

注意:libgdライブラリはある種のXPMファイルを読むことは出来ず、代りにすべての黒のイメージを返します。

GD::Imageメソッド¶

一度GD::Iamgeオブジェクトが作成されると、それに描画したり、コピーしたり、 2つのイメージをマージすることができます。オブジェクトを操作し終ったら、標準の画像ファイル・フォーマットに変換して、出力したりファイルに保存することができます。

画像データ出力メソッド¶

以下のメソッドは内部の描画フォーマットを標準の出力ファイル・フォーマットに変換します。

$pngdata = $image->png

これはイメージデータをPNG形式で返します。それを出力したり、表示プログラムにパイプしたり、ファイルに書きこんだりすることができます。例えば：

    $png_data = $myImage->png;
    open (DISPLAY,"| display -") || die;
    binmode DISPLAY;
    print DISPLAY $png_data;
    close DISPLAY;

binmode()を使うことに注意してください。DOSのようなプラットホームへ移植するためには必須です。

$jpegdata = $image->jpeg([$quality])

これはイメージデータをJPEG形式で返します。それを出力したり、表示プログラムにパイプしたり、ファイルに書きこんだりすることができます。JPEGのクォリティを制御するために、オプションでクォリティ・スコアをjpeg()に渡すこともできます。これは0〜100の整数でなければなりません。高いクォリティ・スコアほどファイルは大きくなり、イメージの品質はよくなります。クォリティを指定しなければ、 jpeg()が適切なデフォルトを選択します。

$gddata = $image->gd

これはイメージデータをGD形式で返します。それを出力したり、表示プログラムにパイプしたり、ファイルに書きこんだりすることができます。例えば

    binmode MYOUTFILE;
    print MYOUTFILE $myImage->gd;

$gd2data = $image->gd2

gd()と同じです。ただし圧縮されたGD2形式でデータを返します。

$wbmpdata = $image->wbmp([$foreground])

これは画像データをWBMP形式で返します。それは白黒イメージのフォーマットです。前景色となる色のインデックスを指定してください。他のピクセルは背景と考えられます。

色の制御¶

これらのメソッドによってGD::Imageカラー・テーブルを制御し操作することができます。

$index = $image->colorAllocate(red,green,blue)

指定されれば、指定された赤、緑、青を組み合わせた色を確保し、カラーテーブルでのそのインデックスを返します。最初に確保された色はイメージの背景色（background color）となります。(255,255,255)は白（すべてのピクセルがオン）、(0,0,0)は黒（すべてのピクセルがオフ）、（255,0,0）は真っ赤。(127, 127, 127)は50%灰色です。（X-Window環境では） /usr/X11/lib/X11/rgb.txtに多くの例が入っています。

色が確保できなかった場合、-1を返します。

例：

    $white = $myImage->colorAllocate(0,0,0); #背景色
    $black = $myImage->colorAllocate(255,255,255);
    $peachpuff = $myImage->colorAllocate(255,218,185);

$image->colorDeallocate(colorIndex)

指定されたインデックスの色を解放できることを示す印を付けます。次にcolorAllocateが呼ばれると、このエントリが書き換えられます。複数の色を解放するときには、繰り返して呼び出します。この関数に戻り値はありません。

例：

    $myImage->colorDeallocate($peachpuff);
    $peachy = $myImage->colorAllocate(255,210,185);

$index = $image->colorClosest(red,green,blue)

カラーテーブルの中で指定された赤、緑、青の組み合わせに一番近い色のインデックスを返します。まだ何も色が確保されていない場合には-1を返します。

例：

    $apricot = $myImage->colorClosest(255,200,180);

$index = $image->colorClosestHWB(red,green,blue)

これも指定された赤、緑、青の組み合わせに一番近い色のインデックスを返そうとします。選択される色をより人が見て似ている色により近づけることができるように、Hue/White/Black色表現を使っています。

まだ何も色が確保されていない場合には-1を返します。

例:

    $mostred = $myImage->colorClosestHWB(255,0,0);

$index = $image->colorExact(red,green,blue)

指定された赤、緑、青の組み合わせと全く同じ色のインデックスを返します。そのような色がカラーテーブルになければ−１を返します。

    $rosey = $myImage->colorExact(255,100,80);
    warn "Everything's coming up roses.\n" if $rosey >= 0;

$index = $image->colorResolve(red,green,blue)

指定された赤、緑、青の組み合わせと全く同じ色のインデックスを返します。そのような色がカラーテーブルになければ、カラーテーブルにその色を確保し、そのインデックスを返します。

    $rosey = $myImage->colorResolve(255,100,80);
    warn "Everything's coming up roses.\n" if $rosey >= 0;

$colorsTotal = $image->colorsTotal) オブジェクト・メソッド

そのオブジェクトで確保されている色の総数を返します。

    $maxColors = $myImage->colorsTotal;

$index = $image->getPixel(x,y) オブジェクト・メソッド

指定された位置のカラーテーブル・インデックスを返します。 rgb()と組み合わせて、対象のピクセルのRGB値を取得することができます。

例:

        $index = $myImage->getPixel(20,100);
        ($r,$g,$b) = $myImage->rgb($index);

($red,$green,$blue) = $image->rgb($index)

指定されたカラーインデックスの赤、緑、青の値の組み合わせを返します。

例:

    @RGB = $myImage->rgb($peachy);

$image->transparent($colorIndex)

指定された色を透明であるという印をつけます。この色で描かれた部分は見えなくなります。ペイントブラシの形を作成したり、Webｅｂで表示する PNGの背景を透明にするのに便利です。いつでも一色だけが透明となります。透明にする色をなくす場合には-1を指定します。

何も指定しないでこのメソッドを呼び出すと、透明な色のインデックス（なければ-1）を返します。

例：

    open(PNG,"test.png");
    $im = newFromPng GD::Image(PNG);
    $white = $im->colorClosest(255,255,255); # 白を検索
    $im->transparent($white);
    binmode STDOUT;
    print $im->png;

特別な色¶

GDはいくつかの特殊な効果を実現するための特別な色を用意しています。これらの定数はGD::名前空間に定義されますが、 GDモジュールがロードされたとき、自動的にエクスポートされます。

$image->setBrush($image)

色や形をブラシパターンを使って描くことができます。ブラシは普通に作成し操作できるイメージになります。ブラシを使って描くと、その内容が線の色や形のために使われます。

ブラシラインを作成するためには、まずブラシのイメージを作成し、ロードしておきます。そしてsetBrushをつかってイメージに設定します。そして特殊な色gdBrushedを使うことにより、ブラシを使って描画します。色の無い部分が他のイメージの上書きしないよう、ブラシのバックグラウンドを透明にすることがよくあります。

例：

    # 斜線イメージの作成
    $diagonal_brush = new GD::Image(5,5);
    $white = $diagonal_brush->allocateColor(255,255,255);
    $black = $diagonal_brush->allocateColor(0,0,0);
    $diagonal_brush->transparent($white);
    $diagonal_brush->line(0,4,4,0,$black); # NE diagonal

    # ブラシの設定
    $myImage->setBrush($diagonal_brush);
    
    # ブラシを使って円を描く
    $myImage->arc(50,50,25,25,0,360,gdBrushed);

（訳者注： TAKIさんからの指摘でallocateColorでなく、colorAllocateの間違いです）

$image->setStyle(@colors)

スタイル付きの線は任意の繰り返された色により構成され、点線を描くときなどに便利です。スタイル付きの線を作成するためには、 setStyleを使って、色の並びを指定します。それは１つまたは複数のカラーインデックスからなる配列を受取ります。そして特殊な色gdStyledを使って描画します。もう１つの特殊な色gdTransparentを使って、線に「穴」を入れることができます。以下に例を示します。

例：

    # 黄色4ピクセル、青4ピクセル、2ピクセルの空白
    # からなるスタイルを指定します
    $myImage->setStyle($yellow,$yellow,$yellow,$yellow,
               $blue,$blue,$blue,$blue,
               gdTransparent,gdTransparent);
    $myImage->arc(50,50,25,25,0,360,gdStyled);

gdStyledとgdBrushedを組み合わせて使うためには、gdStyledBrushedを使います。この場合、ブラシパターンのピクセルのうちsetStyleによって指定された色がgdTransparentでも0(背景色)でもないところが描画されます。

gdTiled

塗りつぶした形や塗りつぶしのさいに使われます。このパターンはイメージです。その画像イメージは指定された空間を塗りつぶすよう、壁紙のような効果を作りながら繰り返し貼り付けられます。 gdTiledカラーを指定するとき、描画のために使用する特定のタイルパターンを定義するためにはsetTileを使わなければなりません。詳細は下記参照。

gdStyled

gdStyled は点線を作成するために使われます。スタイル付きの線は色の並びによって構成され、setStyle()コマンドを使って作られます。

描画コマンド¶

これらのコマンドにより、線、四角、扇型を書き、塗りつぶしのような特殊な操作をおこなうことができます。

$image->setPixel($x,$y,$color)

x,yの位置に指定された色のピクセルを設定します。このメソッドに戻り値はありません。左上が(0,0)となり、下や右にいくほど大きくなります。色には通常の色のほか、特殊な色 gdBrushed 、gdStyled 、 gdStyledBrushedが指定できます。

例:

    # $peachはすでに確保されているものとします
    $myImage->setPixel(50,50,$peach);

$image->line($x1,$y1,$x2,$y2,$color)

指定された色で (x1,y1)から (x2,y2)へ線を引きます。色には通常の色のほか、特殊な色 gdBrushed 、gdStyled 、 gdStyledBrushedが指定できます。

例:

    # 現在指定されているペイント・ブラシのパターンで
    # 対角線を引きます
    $myImage->line(0,0,150,150,gdBrushed);

$image->dashedLine($x1,$y1,$x2,$y2,$color)

指定された色で (x1,y1)から (x2,y2)へ点線を引きます。任意の点線を生成する、よりパワフルな方法は、下記で説明するsetStyle() メソッドを使用し、特殊な色gdStyledを使って線を引くことです。

例:

    $myImage->dashedLine(0,0,150,150,$blue);

GD::Image::rectangle($x1,$y1,$x2,$y2,$color)

指定された色で (x1,y1)、(x2,y2)を左上、右下の頂点とする四角形を描きます。色には通常の色のほか、特殊な色 gdBrushed 、gdStyled 、gdStyledBrushedが指定できます。

例:

    $myImage->rectangle(10,10,100,100,$rose);

$image->filledRectangle($x1,$y1,$x2,$y2,$color)

指定された色で (x1,y1)、(x2,y2)を左上、右下の頂点とする塗りつぶされた四角形を描きます。色には通常の色のほか、特殊な色 gdTiledが指定できます。

例:

    # 塗りつぶしのパターンを読込、設定
    $tile = newFromPng GD::Image('happyface.png');
    $myImage->setTile($tile); 

    # 四角を描き、中をパターンで塗りつぶします
    $myImage->filledRectangle(10,10,150,200,gdTiled);

$image->polygon($polygon,$color)

指定された色で多角形を描きます。多角形は事前に作成しておく必要があります（下記参照）。多角形は少なくとも３つの頂点をもたなければなりません。もし最後の頂点によって多角形が閉じていなければ、自動的に閉じられます。色には通常の色のほか、特殊な色 gdBrushed、gdStyled、 gdStyledBrushedが指定できます。

例：

    $poly = new GD::Polygon;
    $poly->addPt(50,0);
    $poly->addPt(99,99);
    $poly->addPt(0,99);
    $myImage->polygon($poly,$blue);

$image->filledPolygon($poly,$color)

指定された色で塗りつぶされた多角形を描きます。塗りつぶす色には通常の色のほか、パターンで多角形を塗りつぶすために特殊な塗りつぶし色 gdTiledが指定できます。

例:

    # 多角形を作ります
    $poly = new GD::Polygon;
    $poly->addPt(50,0);
    $poly->addPt(99,99);
    $poly->addPt(0,99);

    # 多角形を描画し、色で塗りつぶします
    $myImage->filledPolygon($poly,$peachpuff);

$image->arc($cx,$cy,$width,$height,$start,$end,$color)

指定された色で楕円や扇型を描きます。 (cx,cy)は中心点となり、 (width,height) はそれぞれ幅と高さを指定します。start、stopにより楕円の一部分だけを指定し、扇型をつくります。start、stopには0から 360の角度で指定します。0は楕円の上を示し、角度は時計回りに増えます。閉じた楕円を作るには、start、stopを0と360にします。円を描くためには幅と高さを同じにします。

色には通常の色のほか、特殊な色gdBrushed、gdStyled、 gdStyledBrushedが指定できます。

例:

    # 中心を100,100とする半円を書きます
    $myImage->arc(100,100,50,50,0,180,$blue);

$image->fill($x,$y,$color)

指定された色で塗りつぶします。開始点(x,y)から開始点とは違う色のピクセルまでが指定された色になります。（よくあるペイントツールでの "バケツ"と同じようなものです）色には通常の色のほか、塗りつぶしのパターンとして特殊な色 gdTiledが指定できます。

例：

    # 四角を書き、その内側を青にします
    $myImage->rectangle(10,10,100,100,$black);
    $myImage->fill(50,50,$blue);

$image->fillToBorder($x,$y,$bordercolor,$color)

fillと同様に、このメソッドも開始点(x,y)から指定された色で領域を塗りつぶします。ただし開始点とは違う色のピクセルまでではなく、境界の色(bordercolor)で指定された色のピクセルまでを塗りつぶします。境界の色(bordercolor)には通常のインデックスされた色を指定しなければなりません。しかし塗りつぶしの色には特殊な色 gdTiledも指定できます。

例:

    # これは前の例と同じ効果を持ちます
    $myImage->rectangle(10,10,100,100,$black);
    $myImage->fillToBorder(50,50,$black,$blue);

イメージ・コピー・コマンド¶

イメージの四角形の領域を他の領域にコピーするために、2つのメソッドが提供されています。一つはサイズを変更せず、もう一つはコピー処理のさいに拡大・縮小をすることができます。

2つのメソッドは両方とも、出力先のイメージのカラーテーブルをコピー元のカラーテーブルにあわせようとすることに気をつけてください。もし出力先のカラーテーブルが一杯になっている場合には、出力結果を一番近い色に合わせようとします。

$image->copy($sourceImage,$dstX,$dstY,

$srcX,$srcY,$width,$height)

これがコピーのうち簡単なほうのメソッドで、指定された領域をコピー元から指定された位置へコピーします。(srcX,srcY)には元イメージでの四角形の左上の頂点を、 (width,height)にはコピーする領域の幅と高さを指定します。 (dstX,dstY) は出力イメージの位置を指定します。出力先とコピー元に同じイメージを指定することもできますが、コピー元と出力先が重ならないようにしないと、おかしなことになる可能性があります。

例:

    $myImage = new GD::Image(100,100);
    ... いくつかの描画作業 ...
    $srcImage = new GD::Image(50,50);
    ... さらに描画作業 ...
    # 25x25 ピクセルの領域を$srcImageから
    # $myImageの(10,10)から始まる四角にコピーします
    $myImage->copy($srcImage,10,10,0,0,25,25);

$image->clone()

イメージのコピーを作成し、新しいオブジェクトを返します。新しいイメージは見た目が同じです。しかしカラー・パレットの大きさや、他の基本的ではない詳細で違いがあります。

例：

    $myImage = new GD::Image(100,100);
    ... いくつかの描画作業 ...
        $copy = $myImage->clone;

$image->copyMerge($sourceImage,$dstX,$dstY,

$srcX,$srcY,$width,$height,$percent)

これは指定された四角をソース・イメージから出力先イメージに、指定されたパーセント（0から100までの整数)に色をマージしながら、コピーします。100%を指定すると、copy()と同じ効果になります-- ソース・イメージで出力先のピクセルを置きかえます。これはソリッドな四角をマージすることによりその領域を目立たせるのに大変便利です。

例：

    $myImage = new GD::Image(100,100);
    ... いくつかの描画作業 ...
    $redImage = new GD::Image(50,50);
    ... さらに描画作業 ...
    # 25x25 ピクセルの領域を$srcImageから
    # $myImageの(10,10)から始まる四角に50%マージしながらコピーします
    $myImage->copyMerge($srcImage,10,10,0,0,25,25,50);

$image->copyMergeGray($sourceImage,$dstX,$dstY,

$srcX,$srcY,$width,$height,$percent)

これはcopyMerge()と同じです。ただしすべての出力先の四角のピクセルをマージする前にグレイスケールに変換することにより、元の色相は保ちます。

$image->copyResized($sourceImage,$dstX,$dstY,

$srcX,$srcY,$destW,$destH,$srcW,$srcH)

このメソッドはcopyに似ていますが、コピー元と出力先に違う大きさを指定することができます。コピー元と出力先の大きさは、それぞれ (srcW,srcH) と (destW,destH) で指定します。copyResized()は指定された大きさに合わせてイメージを拡大、縮小をおこないます。

例：

    $myImage = new GD::Image(100,100);
    ... いくつかの描画作業 ...
    $srcImage = new GD::Image(50,50);
    ... さらに描画作業 ...
    #  25x25 ピクセルの領域を $srcImage から
    # $myImageの(10,10)に大きくしてコピーします。
    $myImage->copyResized($srcImage,10,10,0,0,50,50,25,25);

$image->copyResampled($sourceImage,$dstX,$dstY,

$srcX,$srcY,$destW,$destH,$srcW,$srcH)

このメソッドはcopyResized()に似ていますが、代表となる1つのピクセルを選択するのではなく、元の領域のピクセルの重み付け平均を使って、大きな画像から小さなものへの"スムーズな"複写を提供します。この関数は出力イメージがパレット・イメージであれば、 copyResized()と同じです。

$image->trueColorToPalette([$dither], [$colors])

このメソッドはtruecolorイメージをパレットイメージに変換します。この関数のためのコードはIndependent JPEG Groupライブラリ・コードから引き入れました。それは素晴らしいものです。出来るだけ色を保存しながら、できるだけ多くのアルファ・チャネル情報を保持するように変更されています。これは望まれるほどうまくは機能しません。通常、これは代わりに単に truecolor出力イメージを出力するのが一番です。それは非常に高い出力品質を保障します。ディザリング(0/1、デフォルト=0)と使用される色の最大数(<=256, デフォルト=gdMaxColors)は両方とも指定することができます。

イメージ変形コマンド¶

Gdはいくつかのよく使うイメージ変形も提供します:

$image = $sourceImage->copyRotate90()
$image = $sourceImage->copyRotate180()
$image = $sourceImage->copyRotate270()
$image = $sourceImage->copyFlipHorizontal()
$image = $sourceImage->copyFlipVertical()
$image = $sourceImage->copyTranspose()
$image = $sourceImage->copyReverseTranspose(): これらのメソッドはイメージの回転、鏡像(=flip)、反転(=transpose)のために使われます。メソッドの結果はイメージのコピーです。
$image->rotate180()
$image->flipHorizontal()
$image->flipVertical(): これらはcopy*バージョンに似ていますが、その場でイメージを変更します。

Character and String Drawing¶

Gdでは文字を通常通り水平にも、90度回転させても描画することもできます。これらのメソッドは後で説明するGD::Fontオブジェクトを使います。組み込まれているフォントはgdGiantFont、gdLargeFont、gdMediumBoldFont、 gdSmallFont、gdTinyFontの５つがあります。いまのところ独自に動的にフォントを作り出すことはできません。

$image->string($font,$x,$y,$string,$color)

このメソッドは(x,y)の位置から文字列を指定されたフォント、色で描画します。フォントはgdGiantFont、gdLargeFont、gdMediumBoldFont、gdSmallFont、gdTinyFontが選べます。

例:

    $myImage->string(gdSmallFont,2,10,"Peachy Keen",$peach);

$image->stringUp($font,$x,$y,$string,$color)

前の呼び出しと同じですが、文字が反時計回りに90度回転されて描画されます。

$image->char($font,$x,$y,$char,$color)

$image->charUp($font,$x,$y,$char,$color)

これらのメソッドは１つの文字を (x,y)に指定されたフォント、色で描画します。これらは文字と文字列を区別するCインターフェースから持ち越してきたもので、 Perlでは違いはありません。

@bounds = $image->stringFT($fgcolor,$fontname,$ptsize,$angle,$x,$y,$string)

@bounds = GD::Image->stringFT($fgcolor,$fontname,$ptsize,$angle,$x,$y,$string)

このメソッドはスケール付きの、アンチエイリアスされた(antialiased：境界線がぼかされた)文字列を、選択されたTrueTypeベクトル・フォントを使ってTrueTypeを使います。これはlibgdがTrueType サポート付きでコンパイルされ、適切なTrueTypeフォントがシステムにインストールされている必要があります。

引数は以下の通りです：

  fgcolor    文字列を描画するためのカラーインデックス
  fontname   TrueType(.ttf)フォントファイルへの絶対または相対パス
  ptsize     ポイント・サイズ（小数も可）
  angle      回転する角度、ラジアンで。
  x,y        文字列の描画を開始するXとY
  string     文字列そのもの

成功すると、メソッドは文字列を描画した境界を与える８つの要素を持つリストを返します。

 @bounds[0,1]  左下の角 (x,y)
 @bounds[2,3]  右下の角 (x,y)
 @bounds[4,5]  右上の角 (x,y)
 @bounds[6,7]  左上の角 (x,y)

（フォントが使えないまたはTTFサポートが利用できないような）エラーの場合、メソッドは空のリストを返し$@にエラーメッセージを設定します。

実際には描画しないけれども、高価ではない操作を使って境界の箱を返すため、 GD::Imageクラス名からこのメソッドを呼ぶことも出来ます。これを使って、描画の前のレイアウト処理を行うことが出来ます。

FreeTypeライブラｒの以前のバージョンとの後方互換性のため、 stringTTF()も理解されます。libgdライブラリの問題のために、相対フォント・パスは理解されないことにも注意してください。

その他のイメージ・メソッド¶

ある環境ではこれらのユーティリティ・メソッドがとても便利です。

$image->interlaced([$flag])

イメージのインターレース化の設定、問い合わせをおこないます。インターレース化すると対応したビューワーでカッコよく表示されます。インターレース化するにはパラメータにtrueを指定します。 undefを指定すると解除されます。パラメータなしで呼び出すと現在の設定を返します。

($width,$height) = $image->getBounds()

このメソッドはそのイメージの幅と高さの２つ要素を持つリストを返します。取得することはできますが、一度、作成したらイメージの大きさを変更することはできません

$is_truecolor = $image->isTrueColor()

このメソッドはイメージがtrue colorであるか否かのブール値の表現を返します。

$flag = $image1->compare($image2)

2つのイメージを比較し、もしあれば見つかった違いを記述するビットマップを返します。返される値は違いを判定するため、1つまたは複数の定数で論理的にANDされます。以下の定数が使えます：

  GD_CMP_IMAGE             2つのイメージは見た目が違う
  GD_CMP_NUM_COLORS        2つのイメージは色の数が違う
  GD_CMP_COLOR             2つのイメージのパレットが違う
  GD_CMP_SIZE_X            2つのイメージは水平の次元で違う
  GD_CMP_SIZE_Y            2つのイメージは垂直の次元で違う
  GD_CMP_TRANSPARENT       2つのイメージは異なる透明色を持っている
  GD_CMP_BACKGROUND        2つのイメージは異なる背景色を持っている
  GD_CMP_INTERLACE         2つのイメージはインターレースで異なる
  GD_CMP_TRUECOLOR         2つのイメージは両方ともtrue colorではない

これらのうちもっとも重要なのはGD_CMP_IMAGEです。これは2つのイメージが、カラーパレットでの色の順序やその他の見えない違いを無視して、見た目で異なることを示します。定数はデフォルトではインポートされません。個別にインポートされるか、:cmpタグによってインポートされなければなりません。例えば:

  use GD qw(:DEFAULT :cmp);
  # どこかから$image1を取得
  # どこかから$image2を取得
  if ($image1->compare($image2) & GD_CMP_IMAGE) {
     warn "images differ!";
  }

多角形¶

基本的な多角形の作成、操作にはいくつかのメソッドが提供されています。これらはGdライブラリの一部ではありませんが、一緒に扱えるだろうと考えています(qd.pl Quickdraw ライブラリからの借用です)。GD::Polyline もご覧ください。

$poly = GD::Polygon->new

頂点をもたない空の多角形を作成します。

    $poly = new GD::Polygon;

$poly->addPt($x,$y)

頂点(x,y) を多角形に追加します。

    $poly->addPt(0,0);
    $poly->addPt(0,50);
    $poly->addPt(25,25);
    $myImage->fillPoly($poly,$blue);

($x,$y) = $poly->getPt($index)

指定された頂点の位置を取得します。

    ($x,$y) = $poly->getPt(2);

$poly->setPt($index,$x,$y)

既にある頂点の値を変更します。既に定義されていない場合にはエラーとなります。

    $poly->setPt(2,100,100);

($x,$y) = $poly->deletePt($index)

指定された頂点を削除し、その値を返します。

    ($x,$y) = $poly->deletePt(1);

$poly->toPt($dx,$dy)

現在の頂点からの相対位置 (dx,dy)への描画をおこないます。初めての場合にはaddPtと同じような動きになります。

    $poly->addPt(0,0);
    $poly->toPt(0,50);
    $poly->toPt(25,-25);
    $myImage->fillPoly($poly,$blue);

$vertex_count = $poly->length

多角形の頂点の数を返します。

    $points = $poly->length;

@vertices = $poly->vertices

多角形のすべての頂点のリストを返します。リスト中のそれぞれの要素は(x,y)配列へのリファレンスとなります。

    @vertices = $poly->vertices;
    foreach $v (@vertices)
       print join(",",@$v),"\n";
    }

@rect = $poly->bounds

多角形が完全に入る最小の四角形を返します。四角形の(左, 上,右,下) のリストが返されます。

    ($left,$top,$right,$bottom) = $poly->bounds;

$poly->offset($dx,$dy)

全ての頂点を指定された水平(dh)、垂直(dy)方向にずらします。 0より大きな値が指定されると多角形は下や右に移動します。

    $poly->offset(10,30);

$poly->map($srcL,$srcT,$srcR,$srcB,$destL,$dstT,$dstR,$dstB)

必要であればサイズを変更しながら、多角形を元の四角形から出力先の四角形の対応する位置に移動します。どのようになるかはpolys.plを見てください。元と出力先の四角は(左,上,右,下)で指定されます。簡単にするために、元の四角形として多角形自身を取り囲むものを使うことができます。

    # 多角形を非常に高くします
    $poly->map($poly->bounds,0,0,50,200);

$poly->scale($sx,$sy)

各頂点を指定されたsx,sy分X,Y方向に拡大、縮小をおこないます。例えばscale(2,2) は多角形を2倍の大きさにします。 scaleする前に、多角形の中心を(0,0)に持ってきて、 scaleの後、元の位置に戻すとよいでしょう。

$poly->transform($sx,$rx,$sy,$ry,$tx,$ty)

多角形の各頂点に行列変換を描けます。sx,syはX,Y方向の拡大、 rx,ryはX,Y方向の回転、tx,tyは X、,Yのオフセットを指定します。詳しい説明やどのようになるかについては、Adobe PostScript Referenceのページ154をご覧ください

GD::Polyline¶

開いた多角形やスプラインを作成することに関する情報については GD::Polylineをご覧ください。

フォント・ユーティリティ¶

（Perl GDライブラリによって使われる）libgdライブラリには約半ダースのフォントについての組込みサポートを持っており、それらはパブリック・ドメインの X Windowsフォントから変換されました。より多くのフォントのためには、 libgdをTrueTypeサポート付きでコンパイルし、stringFT()呼び出しを使ってください。

さらに多くの組込みフォントを追加したければ、bdf_scriptsディレクトリには X-Windows BDF形式フォントをlibgdが内部的に使うフォーマットに変換することで助けてくれる2つの寄付されたユーティリティが入っています。しかしながら、これらのスクリプトは独自のmini-gdライブラリが入っていた以前のバージョンのGDのために書かれたものです。これらのスクリプトは libgdと一緒に使うように適応させる必要があり、libgdそのものを再コンパイルし、リンクする必要があります。これらのスクリプトについてのヘルプで私にコンタクトしないでください:それらはサポート対象外です。

これらのそれぞれのフォントは、インポートされたグローバル(例えば gdSmallFont)、あるいはパッケージ・メソッド（例えば GD::Font-Small>）の両方で使うことができます。

gdSmallFont

GD::Font->Small

本的な小さなフォント、よく知られているパブリックドメインの 6x12 font. を "借用"しています。

gdLargeFont

GD::Font->Large

基本的な大きなフォント、よく知られているパブリックドメインの 8x16 font を "借用"しています。

gdMediumBoldFont

GD::Font->MediumBold

LargeとSmallの中間の太字フォント。よく知られているパブリックドメインの 7x13 font を借用しています。

gdTinyFont

GD::Font->Tiny

ほとんど読めないくらい小さいフォント。大きさは 5x8 ピクセルです。

gdGiantFont

GD::Font->Giant

9x15 の太字フォント。Jan Pazdziora により sans serif X11 フォントから変換されました。

$font->nchars

そのフォントの中の文字数を返します。

    print "The large font contains ",gdLargeFont->nchars," characters\n";

$font->offset

そのフォントでの最初の文字のASCII値を返します。

$width = $font->width

$height = $font->height

height

これらはそのフォントの幅と高さを返します。

  ($w,$h) = (gdLargeFont->width,gdLargeFont->height);

gdのC言語バージョンの取得¶

libgd, gdのC言語バージョン、はURL http://www.boutell.com/gd/ から取得できます。それのインストール方法と使用方法はそのサイトにあります。 libgdについてのヘルプのために私にコンタクトしないで下さい。

作者¶

The GD.pm interface is copyright 1995-2000, Lincoln D. Stein. It is distributed under the same terms as Perl itself. See the "Artistic License" in the Perl source code distribution for licensing terms.

The latest versions of GD.pm are available at

  http://stein.cshl.org/WWW/software/GD

参考資料¶

GD::Polyline, Image::Magick