by Hippo2000(2001/2/10)
GD::Graphモジュールなのです。GIFgraphの後継にあたります。GD自体の機能アップもあってTrueTypeを利用することにより。日本語も使えるようにもなりました。(^^)v。これについてはGD::Textをごらんください。
原本の著作権はMartien Verbruggen 氏がお持ちです（詳しくは著作権情報を見てください）。Martien Verbruggen 氏からは、メールで了解をいただきました。Thank you, Mr Verbruggen!
内容等が間違っていたら修正します。ご連絡ください。
GD::Graphには以下のサブクラスがあります
モジュール 説 明 GD::Graph::Colour GD::Graphで使われる色操作ルーチン GD::Graph::FAQ よく聞かれる質問 GD::Graph::Data GD::Graphのためのデータセットのカプセル化 GD::Graph::Error GD::Graph クラスのためのエラー・ハンドリング
GD::Graph - Perl5のためのグラフ作成モジュール
use GD::Graph::モジュール名;
GD::Graph とは、GDモジュールを使ってグラフ作成するPerl5モジュールです。以下の軸ありグラフのためのクラスが定義されています：
さらに以下のタイプもあります：
ディストリビューションでのsamplesディレクトリをご覧になり、そこのMakefileをお読みください。
X軸の項目とデータセットが入った配列の配列を作成します。各配列のサイズはすべて同じにしてください。そうしないとGD::Graphは文句を言って、グラフを作成するのを止めてしまいます。
@data = (
["1st","2nd","3rd","4th","5th","6th","7th", "8th", "9th"],
[ 1, 2, 5, 6, 3, 1.5, 1, 3, 4],
[ sort { $a <=> $b } (1, 2, 5, 6, 3, 1.5, 1, 3, 4) ]
);
データセットのなかにデータがない箇所があれば、undefを使うことができます。その点は飛ばされます。
作りたい種類のグラフにnew演算子を呼び出すことにより、新しいGD::Graphオブジェクトを作成します。（chartにはbars, lines, points, linespoijnts,mixedそしてpieが指定できます）
$graph = GD::Graph::chart->new(400, 300);
オプションを設定します
$graph->set(
x_label => 'X Label',
y_label => 'Y label',
title => 'Some simple graph',
y_max_value => 8,
y_tick_number => 8,
y_label_skip => 2
);
グラフを出力します。
my $gd = $my_graph->plot(\@data);
そこであなたのGDがそのバージョンでファイルに保存するために可能にしていることをします。1.19よりも古いGDのバージョンでは、以下のようにすることができます。
open(IMG, '>file.gif') or die $!; binmode IMG; print IMG $gd->gif; close IMG;
そしてより新しい(1.20以上）では以下のように書くでしょう
open(IMG, '>file.png') or die $!; binmode IMG; print IMG $gd->png;
あるいは
open(IMG, '>file.gd2') or die $!; binmode IMG; print IMG $gd->gd2;
そしてもちろん、短いバージョンでもできます（それぞれはGDがサポートするエクスポートされた関数です）
print IMG $my_graph->plot(\@data)->gif; print IMG $my_graph->plot(\@data)->png; print IMG $my_graph->plot(\@data)->gd; print IMG $my_graph->plot(\@data)->gd2;
もしgifまたはpngが使うかどうかを「知る」ことを要求しないように書きたければ、以下のようにすることができます。
if ($gd->can('png')) { # ほんにゃらはんにゃら }
もしくは便宜的なメソッドexport_formatを使うことができます。
my $format = $my_graph->export_format; open(IMG, ">file.$format") or die $!; binmode IMG; print IMG $my_graph->plot(\@data)->$format(); close IMG;
もしくはCGIスクリプト用：
use CGI qw(:standard);
#...
my $format = $my_graph->export_format;
print header("image/$format");
binmode STDOUT;
print $my_graph->plot(\@data)->$format();
(そこにメソッド名があることを意味しているとコンパイラに判定させるのを助けるために、$formatの後ろの括弧は必要です。）
もしplotメソッドを呼ぶ前にGD::Imageオブジェクトに描画するのであれば、背景色を保証すること、透明色の設定の設定について責任を持たなければならないことに注意してください。
boxcolorを除いてすべての色は 色 で記述されているような正しい値でなければなりません。boxcolorが未定義であると、箱は塗りつぶされません。
すべての色は色 で記述されているような正しい値でなければなりません。
$graph->set( dclrs => [ qw(green pink blue cyan) ] );
最初（5番目、9番目）のデータは緑(green)に、次はピンク(pink)などとなります。デフォルト：[
qw(lred lgreen lblue lyellow lpurple cyan
lorange) ]
背景色と同じ色に境界線の色を設定すると、棒がX軸上で"浮かんでいる"ように見えます。例えば（背景色が白だったとします）
$graph->set( dclrs => [ qw(white cyan cyan) ] );
$graph->set( borderclrs => [ qw(white black black) ] );
これは黒い線のついたcyan色のバーが真ん中を通っているように見えます。これは平均値をもった範囲をしめすのに理想的です。
棒、折れ線、点、点付折れ線、混合、そして面グラフのためのオプションです。
これらの属性は_long_ticks, y_long_ticks, x_tick_length そして y_tick_lengthによってx軸、y軸、別々にしていできます。
$label = sprintf( $s->{y_number_format, $value );
サブルーチンへのリファレンスであれば、値を引数に実行されます。:
$label = &{$s->{y_number_format}}($value);
これはとても便利です。例えば、正しい位置に−符号がつく通貨の形式にしようと思ったときには以下のようにします。:
sub y_format
{
my $value = shift;
my $ret;
if ($value >= 0)
{
$ret = sprintf("\$%d", $value * $refit);
}
else
{
$ret = sprintf("-\$%d", abs($value) * $refit);
}
return $ret;
}
$my_graph->set( 'y_number_format' => \&y_format );
(もちろんもっと短く、簡単にできることはわかっています。)
デフォルト: undef
qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec)
そしてx_label_skip を3に設定したとすると、X軸の目盛はJan, Apr, Jul, Oct そして Decとなります。これが常に欲しいものではありません。もしx_tick_offsetを1に設定するとFeb, May, Aug, Nov そして Decとなります。もし2に設定するとMar, Jun Sep そして Decとなります。そして最後のものが一番よいように見えます。6と5の組み合わせも月にはあっているようです。
x_tick_offset のための値は周期的であることに注意してください。つまり整数nについてx_tick_offset + n * x_label_skip.と同じ効果があるということです。
範囲 (y_min_value〜y_max_value) はすべてのデータ値を含んでいなければなりません。そうでなければGD::Graphはメッセージとともに死にます（die)。
棒グラフ、面グラフでは、範囲 (y_min_value〜y_max_value) に０が入っていなければなりません。そうでなければ、グラフを作成する前に値が調整されます。
デフォルト: データセットから計算します。
デフォルト：8
注意：これは現在、棒グラフ、面グラフにのみ機能します。
データセットの負の値が入っていると、このオプションを設定するとおかしなことになります。もちろんグラフそのものがまったく無意味になるでしょう。
注意：積み重ねセットを生成するためにoverwriteを2に設定するというのは廃棄対象です。GD::Graphの将来のバージョンではなくなります。代わりにcumulate属性をご覧ください。
この値がtrueのとき、データポイントの数が確実にグラフの描画領域ピクセルの数よりも小さくする必要があります。水平方向の大きさが小さすぎるというエラーを得るのであれば、手動でこれをオフにするか、棒グラフ以外のタイプを利用するように考えなければなりません。
デフォルト：棒グラフでは1、混合グラフでは実行時に計算、それ以外は0。
場合によっては、明確にするためにデータポイントや棒グラフの値をデータポイントの上に値を描画したいかも知れません。GD::Graphはこれを一般的な方法で、あるいは１つポイントを落としてさえ制御することを可能にしています。
これをGD::Graph::Data オブジェクト、あるいはplotメソッドに渡したデータ・オブジェクトと同じ形、同じ次元の配列リファレンスに設定してください。このオプションの理由は、それはあなたのデータセットのコピーを作ることを可能にします。そして選択的に描画できない点をundefにします。
my $data = GD::Graph::Data->new(
[ [ 'A', 'B', 'C' ], [ 1, 2, 3 ], [ 11, 12, 13 ] ]);
my $values = $data->copy;
$values->set_y(1, 1, undef);
$values->set_y(2, 0, undef);
$graph->set(show_values => $values); $graph->plot($data);
デフォルト： 0.
まず最初に：GD::Graphは数値のX軸はあるべき姿でサポートしていません。X軸のデータはすべて等しく空間が取られます。その上で：数値のX軸をもったグラフの作成をなんとかサポートをしています。Scott Prahlに感謝します。オプション x_tick_numberが定義された値であれば、GD::GraphはXのデータを数値として扱おうとします。
特殊なオプション：
$graph->set( line_types => [3, 2, 4] );
使える線の種類は 1: 実線（solid）、 2: ダッシュ（dashed） 3: 点線（dotted） 4: 点線（dot-dashed）
デフォルト: [1] (常に実線)
$graph->set( markers => [3, 5, 6] );
使える点（マーカー）は: 1: 塗りつぶされた四角（filled square）, 2: 四角（open square）, 3: 十字（horizontal cross）、 4: 対角線の十字(diagnal cross), 5: 塗りつぶされた菱形（filled diamond）, 6: 菱形（open diamond）, 7: 塗りつぶされた丸（filled circle）, 8: 丸（open circle）です。
デフォルト: [1,2,3,4,5,6,7,8]
$graph->set( types => [qw(lines bars points area linespoints)] ); $graph->set( types => ['lines', undef, undef, 'bars'] );
undefもしくはわからない値であればdefault_type が設定されます。
デフォルト: すべて default_type に設定されます。
デフォルト: lines （折れ線グラフ）
現在、凡例は最低限しかサポートしていません。
メソッド
@legend_keys
の要素はplot()
に指定されるデータセットに対応します。キーが undef または空文字列であれば、凡例の要素は飛ばされます。
オプション
凡例の位置が下(B)であれば、そうなるように計算して「知的な」折り返しを行います。もし凡例の位置が右(R)であれば、すべての要素が上下に並びます。
（訳者注：最初の文字がBだった場合には凡例の項目が横に、Rだった場合には縦に並びます。）
このモジュールでは、オプションでの色(colour)の書き方はすべてclrと省略しています。その大きな理由は、同じ言葉に２つのスペル('colour'と'color')をサポートしたくないということです。
色が必要なときには、GD::Graph::colourパッケージの色の名前を使わなければいけません。「
perldoc GD::graph::colour」とすると、正しい色の名前が入った、そのモジュールの説明を見ることができます。もし使用可能であればシステムのrgb.txtを読み込むように変更することができます。
あなたのGDのバージョンによっては、これはGD組込フォントといわゆるTrueTypeフォントの両方を受け入れます。TrueTypeフォントの場合、フォントサイズを指定しなければなりません。詳細とその他については GD::Text をご覧ください。というのもGD::Graphでのフォントの取扱いはすべてそこに委任されているからです。
例：
$my_graph->set_title_font('/fonts/arial.ttf', 18);
$my_graph->set_legend_font(gdTinyFont);
$my_graph->set_legend_font(
['verdana', 'arial', gdMediumBoldFont], 12)
(上記の話はGD::Text 0.65を元にしています。古いバージョンではより制約された動きになります。）
これが実験的な機能であること、そしてインターフェースは将来、変更される可能性があること、その可能性が高いことに注意してください。
GD::Graphは各データポイントのために内部的な座標のセットを持っています。この仕様はHTMLイメージマップの仕様と非常にており、実際、主にはそのために存在しています。これらのホットスポットをget_hotspotメソッドで取得することができます。このメソッドは2つのオプションの引数を受け取ります。あなたが興味を持っているデータセットの番号とそのデータセットでのあなたが興味を持っているポイントの番号です。２つの引数をつけてこのメソッドを呼び出すと以下のような形式のリストを返します：
'rect', x1, y1, x2, y2 'poly', x1, y1, x2, y2, x3, y3, .... 'line', xs, ys, xe, ye, width
rect(長方形）のためのパラメータは長方形の角の座標です。poly（多角形）のためのパラメータは多角形の頂点の座標です。lineのためのパラメータは開始点と終了点の座標そして幅です。ほとんど直接これらをHTMLイメージマップの仕様に変換することができます。
もしget_hotspotの2番目の引数が省略されると、配列へのリファレンスが返されます。このリストは指定されたデータセット中のすべての点を表します。そしてそれぞれの配列は上記で表したような形式になります。
['rect', x1, y1, x2, y2 ], ['rect', x1, y1, x2, y2], ...
もしget_hotspotの両方の引数が省略されると、返されるリストには各データセットのための配列へのリファレンスが入ってきます。それぞれ各ポイントのための配列へのリファレンスが入っています。
[
['rect', x1, y1, x2, y2 ], ['rect', x1, y1, x2, y2], ...
],
[
['line', xs, ys, xe, ye, w], ['line', xs, ys, xe, ye, w], ...
],...
Perlのすべてのモジュールへ：インターフェースを守るようにしてください。もしこのモジュールの内部の知識をもてあそぶと、痛い目にあうでしょう。私はいつこれを変更するかわかりません。
GD::Graphオブジェクトは再使用することができません。新しく描画するためには、新しいGD::Graphオブジェクトを作成しなければなりません。
Martien Verbruggen <mgjv@comdyn.com.au>
GIFgraph: Copyright (c) 1995-1999 Martien Verbruggen. Chart::PNGgraph: Copyright (c) 1999 Steve Bonds. GD::Graph: Copyright (c) 1999 Martien Verbruggen.
All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Thanks to Steve Bonds for releasing Chart::PNGgraph, and keeping the code alive when GD reached version 1.20, and I didn't have time to do something about it.
Thanks to the following people for contributing code, or sending me fixes: Dave Belcher, Steve Bonds, Mike Bremford, Damon Brodie, Gary Deschaines brian d foy, Edwin Hildebrand, Ari Jolma, Tim Meadowcroft, Honza Pazdziora, Scott Prahl, Vegard Vesterheim, Jeremy Wadsack.
And some people whose real name I don't know, and whose email address I'd rather not publicise without their consent.
GD::Graph::FAQ, GD::Graph::Data, GD::Graph::Error, GD::Graph::colour
ご意見、ご質問はこちらの掲示板で受け付けています。
またメールは河馬屋(Nifty)にお願いします。