=begin comment
$Id: GD::Simple-jp.pod,v 1.3 2005-12-10 14:54:50+09 shige Exp $

GD::Simple-jp.pod
日本語訳: Shigeharu TAKENO <shige@iee.niit.ac.jp>

1)
% perldoc -u GD/Simple.pm > ../GD::Simple.pod
としたものの日本語訳。現在は GD.pm version 2.28 の訳。

2)
原文は begin comment 〜 end comment 内に残しているものもあれば、そうで
ないものもある。

3) 
.pod ファイルとして利用する場合は、=begin comment 〜 =end comment 部分
を削除してから利用すること。例えば以下の通り:

% sed '/^=begin comment/,/^=end comment/'d GD-jp.pod | pod2text \
> GD-jp.txt

4)
pod2text で変換すると行末が合わないよう。こちらでそう書いておく必要があ
るみたい。pod2man | nroff -man も、あまり綺麗ではない。

5)
訳に関しては、shige@iee.niit.ac.jp に連絡すること。

7) ライセンスは、元のファイルのライセンスと同様とする。詳しくは、
「著者」の節を参照。

=end comment
=head1 名前

=begin comment
GD::Simple - Simplified interface to GD library
=end comment
GD::Simple - GD library に対する単純なインターフェース

=head1 形式

    use GD::Simple;

    # 新しい画像を作成
    $img = GD::Simple->new(400,250);

    # 青い境界の赤い長方形を描く
    $img->bgcolor('red');
    $img->fgcolor('blue');
    $img->rectangle(10,10,50,50);

    # 緑の境界の中空の長方形を描く
    $img->bgcolor(undef);
    $img->fgcolor('green');
    $img->rectangle(30,30,100,100);

    # (80,80) に移動して、そこから (100,190) への緑の直線を描く
    $img->moveTo(80,80);
    $img->lineTo(100,190);

    # オレンジの楕円を描く
    $img->moveTo(110,100);
    $img->bgcolor('orange');
    $img->fgcolor('orange');
    $img->ellipse(40,40);

    # 黒の扇型を描く
    $img->moveTo(150,150);
    $img->fgcolor('black');
    $img->arc(50,50,0,100,gdNoFill|gdEdged);

    # デフォルトの組込みフォントを使って (10,180) に文字列を描く
    $img->moveTo(10,180);
    $img->string('This is very simple');

    # 20 ポイントの Times Italic フォントを使って、(280,210) に上向きに
    # 90 度回転させて文字を描く
    $img->moveTo(280,210);
    $img->font('Times:italic');
    $img->fontsize(20);
    $img->angle(-90);
    $img->string('This is very fancy');

    # タートルグラフィックの例
    $img->moveTo(300,100);
    $img->penSize(3,3);
    $img->angle(0);
    $img->line(20);   # 20 ピクセル右へ
    $img->turn(30);   # 30 度回転
    $img->line(20);   # 20 ピクセル直線を引く
    $img->line(20);
    $img->line(20);
    $img->turn(-90); # -90 度回転して
    $img->line(50);  # 50 ピクセル直線を引く

    # 青い境界で水色の多角形を描く
    my $poly = new GD::Polygon;
    $poly->addPt(150,100);
    $poly->addPt(199,199);
    $poly->addPt(100,199);
    $img->bgcolor('cyan');
    $img->fgcolor('blue');
    $img->penSize(1,1);
    $img->polygon($poly);

   # PNG データに変換して出力
   print $img->png;

=head1 機能説明

=begin comment
GD::Simple is a subclass of the GD library that shortens many of the
long GD method calls by storing information about the pen color, size
and position in the GD object itself.  It also adds a small number of
"turtle graphics" style calls for those who prefer to work in polar
coordinates.  In addition, the library allows you to use symbolic
names for colors, such as "chartreuse", and will manage the colors for
you.
=end comment
GD::Simple は GD ライブラリのサブクラスであり、
ペンの色、サイズ、位置の情報を GD のオブジェクト自身の中に保存する
多くの GD の長いメソッド呼び出しを短縮化したものです。
これは、極座標での作業をむしろ好む人用に、
"タートルグラフィックス" 形式の呼び出しもいくつか追加します。
さらにこのライブラリでは、例えば "chartreuse" (明るい薄黄緑色) のような
色の別名も使えますし、複数の色の管理も可能にします。

=head2 ペン

=begin comment
GD::Simple maintains a "pen" whose settings are used for line- and
shape-drawing operations.  The pen has the following properties:
=end comment
GD::Simple は "ペン" を使用します。これは、直線や図形の描画命令で使用さ
れます。ペンは以下の属性を持ちます:

=over 4

=item fgcolor

ペンの前景色 (foreground color)  で、線や図形の境界の色として使われます。

=item bgcolor

ペンの背景色 (background color) で、図形内部の塗りつぶしに使われます。

=item pensize

これはペンの幅です。大きなサイズは太い線を描きます。

=item position

これはキャンバス内での現在の位置の (X,Y) 座標です。

=item angle

タートルグラフィックモードでの相対的な長さによる描画の際の、
ペンの進む方向を設定します。

=item turn

タートルグラフィックモードで、次の線を描く前にペンを時計周り、
または反時計周りに回転させる角度を設定します。

=item font

これは文章を書くときに使われるフォントを設定します。
組込まれたビットマップフォントと TrueType フォントがサポートされています。

=item fontsize

これは TrueType フォントで書くときのフォントサイズです。

=back

=begin comment
One sets the position and properties of the pen and then draws.  As
the drawing progresses, the position of the pen is updated.
=end comment
ペンの位置と属性を設定して、それを描画します。描画を進めると、
ペンの位置も更新されます。

=head2 Methods

=begin comment
GD::Simple introduces a number of new methods, a few of which have the
same name as GD::Image methods, and hence change their behavior. In
addition to these new methods, GD::Simple objects support all of the
GD::Image methods. If you make a method call that isn't directly
supported by GD::Simple, it refers the request to the underlying
GD::Image object.  Hence one can load a JPEG image into GD::Simple and
declare it to be TrueColor by using this call, which is effectively
inherited from GD::Image:
=end comment
GD::Simple はいくつかの新しいメソッドを導入しています。
そのうちのいくつかは GD::Image のメソッドと同じ名前ですが、
それらの挙動には違いがあります。
これらの新しいメソッドに加えて、GD::Simple のオブジェクトは 
GD::Image のメソッドを全てサポートしています。
もし GD::Simple が直接サポートしていないメソッド呼び出しを作った場合、
それは下位にある GD::Image オブジェクトへのリクエストを参照します。
よって、JPEG 画像を GD::Simple 内に読み出して、
それをこの呼び出しを使って TrueColor に宣言することができますが、
これは実際 GD::Image から継承されます:

  my $img = GD::Simple->newFromJpeg('./myimage.jpg',1);

=begin comment
The rest of this section describes GD::Simple-specific methods.
=end comment
この節の残りは GD::Simple 特有のメソッドの説明を行います。

=cut

=over 4

=item $img->moveTo($x,$y)

=begin comment
This call changes the position of the pen without drawing. It moves
the pen to position ($x,$y) on the drawing canvas.
=end comment
この呼び出しは描画せずにペンの位置を変更します。
ペンの位置を描画キャンバス上の ($x,$y) へ移動します。


=cut


=cut

=item $img->move($dx,$dy)

=item $img->move($dr)

=begin comment
This call changes the position of the pen without drawing. When called
with two arguments it moves the pen $dx pixels to the right and $dy
pixels downward.  When called with one argument it moves the pen $dr
pixels along the vector described by the current pen angle.
=end comment
この呼び出しは描画せずにペンの位置を変更します。
2 つの引数で呼び出された場合は、
ペンを $dx ピクセルだけ右に、$dy ピクセルだけ下に移動します。 
1 つの引数で呼び出された場合は、
現在のペンの角度で定まるベクトルに沿って $dr ピクセルだけペンを移動します。


=cut

=item $img->lineTo($x,$y)

=begin comment
The lineTo() call simultaneously draws and moves the pen.  It draws a
line from the current pen position to the position defined by ($x,$y)
using the current pen size and color.  After drawing, the position of
the pen is updated to the new position.
=end comment
呼び出し lineTo() は描画とペンの移動を同時に行います。
これは現在のペンの位置から ($x,$y)で定義される位置へ、
現在のペンのサイズと色を使って線分を描画します。
描画が終わるとペンの位置は新しい位置へ更新されます。


=cut

=item $img->line($dx,$dy)

=item $img->line($dr)

=begin comment
The line() call simultaneously draws and moves the pen. When called
with two arguments it draws a line from the current position of the
pen to the position $dx pixels to the right and $dy pixels down.  When
called with one argument, it draws a line $dr pixels long along the
angle defined by the current pen angle.
=end comment
呼び出し line() は描画とペンの移動を同時に行います。
2 つの引数で呼び出された場合は、
これは現在のペンの位置から $dx ピクセルだけ右、
$dy ピクセルだけ下の位置へ線分を描きます。
1 つの引数で呼び出された場合は、
現在のペンの角度に沿って $dr ピクセルだけ線分を描きます。


=cut

=item $img->clear

=begin comment
This method clears the canvas by painting over it with the current
background color.
=end comment
このメソッドは現在の背景色で塗りつぶすことでキャンバス全体を消去します。


=cut

=item $img->rectangle($x1,$y1,$x2,$y2)

=begin comment
This method draws the rectangle defined by corners ($x1,$y1),
($x2,$y2). The rectangle's edges are drawn in the foreground color and
its contents are filled with the background color. To draw a solid
rectangle set bgcolor equal to fgcolor. To draw an unfilled rectangle
(transparent inside), set bgcolor to undef.
=end comment
このメソッドは ($x1,$y1) と ($x2,$y2) を角に持つ長方形を描画します。
長方形の境界は前景色で描画され、その内部は背景色で塗りつぶされます。
長方形面 (内部の塗りつぶされた長方形) を描画するには、
背景色を前景色と同じに設定します。
内部を塗らない長方形 (内部が透明) を描画するには、
背景色を undef に設定します。


=cut

=item $img->ellipse($cx,$cy,$width,$height)

=begin comment
This method draws the ellipse defined by center ($cx,$cy), width
$width and height $height.  The ellipse's border is drawn in the
foreground color and its contents are filled with the background
color. To draw a solid ellipse set bgcolor equal to fgcolor. To draw
an unfilled ellipse (transparent inside), set bgcolor to undef.
=end comment
このメソッドは、中心が ($cx,$cy) で、横が $width, 縦が $height の
楕円を描画します。
楕円の境界は前景色で描画し、楕円内部は背景色で塗りつぶします。
楕円面 (内部の塗りつぶされた楕円) を描画するには、
背景色を前景色と同じに設定します。
内部を塗らない楕円 (内部が透明) を描画するには、
背景色を undef に設定します。


=cut

=item $img->arc($cx,$cy,$width,$height,$start,$end [,$style])

=begin comment
This method draws filled and unfilled arcs.  See L<GD> for a
description of the arguments. To draw a solid arc (such as a pie
wedge) set bgcolor equal to fgcolor. To draw an unfilled arc, set
bgcolor to undef.
=end comment
このメソッドは塗りつぶされた/塗りつぶさない円弧、扇形を描画します。
引数の詳細については L<GD> を参照してください。
扇型面 (内部の塗りつぶされた扇型) を描画するには、
背景色を前景色と同じに設定します。
内部を塗らない円弧、扇形を描画するには、
背景色を undef に設定します。


=cut

=item $img->polygon($poly)

=begin comment
This method draws filled and unfilled polygon using the current
settings of fgcolor for the polygon border and bgcolor for the polygon
fill color.  See L<GD> for a description of creating polygons. To draw
a solid polygon set bgcolor equal to fgcolor. To draw an unfilled
polygon, set bgcolor to undef.
=end comment
このメソッドは塗りつぶされた/塗りつぶさない多角形を描画します。
現在の前景色を使って多角形の境界を描画し、
背景色を使って多角形内部を塗りつぶします。
多角形の生成の詳細については L<GD> を参照してください。
多角形面 (内部の塗りつぶされた多角形) を描くには、
背景色を前景色と同じに設定します。
内部を塗らない多角形を描画するには、
背景色を undef に設定します。


=cut

=item $img->string($string)

=begin comment
This method draws the indicated string starting at the current
position of the pen. The pen is B<not> moved.  Depending on the font
selected with the font() method, this will use either a bitmapped GD
font or a TrueType font.  The angle of the pen will be consulted when
drawing the text. For TrueType fonts, any angle is accepted.  For GD
bitmapped fonts, the angle can be either 0 (draw horizontal) or -90
(draw upwards).
=end comment
このメソッドは、指定された文字列を現在のペンの位置から描きます。
ペンの位置は変化B<しません>。
font() メソッドで選択されたフォントによって、
これは GD ビットマップフォントか TrueType フォントのどちらかを使用します。
ペンの角度は文字列の描画の際に参照されます。
TrueType フォントに関しては任意の角度が許されますが、
GD ビットマップフォントは角度は 0 (水平描画) か -90 (鉛直上向き描画)
のみが許されます。

=begin comment
For consistency between the TrueType and GD font behavior, the string
is always drawn so that the current position of the pen corresponds to
the bottom left of the first character of the text.  This is different
from the GD behavior, in which the first character of bitmapped fonts
hangs down from the pen point.
=end comment
TrueType フォントと GD フォントでの動作の一貫性のために、
文字列は常に現在のペンの位置が最初の文字の左下になるように
描画されることになっています。
これは GD の挙動とは違っていて、
GD ではビットマップフォントの最初の文字はペンの位置から
ぶら下がりるようになっています。

=begin comment
When rendering TrueType, this method returns an array indicating the
bounding box of the rendered text.  If an error occurred (such as
invalid font specification) it returns an empty list and an error
message in $@.
=end comment
TrueType での描画の場合、このメソッドは、
描画した文字列が丁度収まる長方形のデータを保持する配列を返します。
無効なフォントの指定などのエラーが起きた場合は、
空のリストを返し、$@ にエラーメッセージを返します。


=cut

=item ($x,$y) = $img->curPos

=begin comment
Return the current position of the pen.  Set the current position
using moveTo().
=end comment
現在のペンの位置を返します。moveTo() を使って現在の位置を設定します。


=cut

=item $font = $img->font([$newfont])

=begin comment
Get or set the current font.  Fonts can be GD::Font objects, TrueType
font file paths, or fontconfig font patterns like "Times:italic" (see
L<fontconfig>). The latter feature requires that you have the
fontconfig library installed and are using libgd version 2.0.33 or
higher.
=end comment
現在のフォントを取得/設定します。フォントは GD::Font オブジェクト、
TrueType フォントファイルパス名、または "Times:italic" のような
fontconfig フォントパターン (L<fontconfig> 参照) などです。
fontconfig パターンは、fontconfig ライブラリがインストールされていて、
libgd バージョン 2.0.33 以降を使っている場合のみ利用できます。


=cut

=item $size = $img->fontsize([$newfontsize])

=begin comment
Get or set the current font size.  This is only valid for TrueType
fonts.
=end comment
現在のフォントサイズを取得/設定します。
これは TrueType フォントにのみ有効です。


=cut

=item $size = $img->penSize([$newpensize])

=begin comment
Get or set the current pen width for use during line drawing
operations.
=end comment
線の描画で使われる現在のペンの幅を取得/設定します。


=cut

=item $angle = $img->angle([$newangle])

=begin comment
Set the current angle for use when calling line() or move() with a
single argument. 
=end comment
1 つの引数の line() や move() の呼び出しで使われる現在の角度を設定します。

=begin comment
Here is an example of using turn() and angle() together to draw an
octagon.  The first line drawn is the downward-slanting top right
edge.  The last line drawn is the horizontal top of the octagon.
=end comment
turn() と angle() の両方を使って八角形を描画する例を紹介します。
最初に描かれるのは右上の斜め下向きの線、
最後に描かれるのは八角形の天井の水平線です。

  $img->moveTo(200,50);
  $img->angle(0);
  $img->turn(360/8);
  for (1..8) { $img->line(50) }


=cut

=item $angle = $img->turn([$newangle])

=begin comment
Get or set the current angle to turn prior to drawing lines.  This
value is only used when calling line() or move() with a single
argument.  The turning angle will be applied to each call to line() or
move() just before the actual drawing occurs.
=end comment
現在の、前の方向から次の描画への回転角を取得/設定します。
この値は 1 つの引数の line() や move() の呼び出しでのみ使われます。
回転角は line() や move() のそれぞれの呼び出しの際に、
実際に描画が行われる直前に適用されます。

=begin comment
Angles are in degrees.  Positive values turn the angle clockwise.
=end comment
角の単位は度です。正の値は時計回りの回転角を意味します。


=cut

=item $color = $img->fgcolor([$newcolor])

=begin comment
Get or set the pen's foreground color.  The current pen color can be
set by (1) using an (r,g,b) triple; (2) using a previously-allocated
color from the GD palette; or (3) by using a symbolic color name such
as "chartreuse."  The list of color names can be obtained using
color_names().
=end comment
ペンの前景色を取得/設定します。
現在のペンの色は、(1) (r,g,b) の三つの組、(2) GD パレットからあらかじめ
割り当てた色、(3) "chartreuse" (明るい薄黄緑色) のような別名、
のいずれかを使って設定できます。
色名の一覧は color_names() を使って取得できます。


=cut

=item $color = $img->bgcolor([$newcolor])

=begin comment
Get or set the pen's background color.  The current pen color can be
set by (1) using an (r,g,b) triple; (2) using a previously-allocated
color from the GD palette; or (3) by using a symbolic color name such
as "chartreuse."  The list of color names can be obtained using
color_names().
=end comment
ペンの背景色を取得/設定します。
現在のペンの色は、(1) (r,g,b) の三つの組、(2) GD パレットからあらかじめ
割り当てた色、(3) "chartreuse" (明るい薄黄緑色) のような別名、
のいずれかを使って設定できます。
色名の一覧は color_names() を使って取得できます。


=cut

=item $index = $img->translate_color(@args)

=begin comment
Translates a color into a GD palette or TrueColor index.  You may pass
either an (r,g,b) triple or a symbolic color name. If you pass a
previously-allocated index, the method will return it unchanged.
=end comment
色を GD パレットか TrueColor 番号に変換します。
(r,g,b) の三つの組か別名は割り当てをパスするかもしれません。
番号への割り当てをパスをした場合、
このメソッドはそれを変換せずに返します。


=cut

=item @names = GD::Simple->color_names

=item $translate_table = GD::Simple->color_names

=begin comment
Called in a list context, color_names() returns the list of symbolic
color names recognized by this module.  Called in a scalar context,
the method returns a hash reference in which the keys are the color
names and the values are array references containing [r,g,b] triples.
=end comment
リストコンテキストで呼び出された場合、
color_names() はこのモジュールで認識される色の別名のリストを返します。
スカラーコンテキストで呼び出された場合、
このメソッドは、キーが色名で値が [r,g,b] の 3 つの組を含む配列参照である
ようなハッシュ配列の参照を返します。


=cut

=item $gd = $img->gd

=begin comment
Return the internal GD::Image object.  Usually you will not need to
call this since all GD methods are automatically referred to this object.
=end comment
内部の GD::Image オブジェクトを返します。
全ての GD メソッドは自動的にこのオブジェクトを参照するので、
通常はこれを呼び出す必要はありません。


=back


=cut

=head1 色

=begin comment
This script will create an image showing all the symbolic colors.
=end comment
このスクリプトは全ての別名の色を示す画像を生成します。

 #!/usr/bin/perl

 use strict;
 use GD::Simple;

 my @color_names = GD::Simple->color_names;
 my $cols = int(sqrt(@color_names));
 my $rows = int(@color_names/$cols)+1;

 my $cell_width    = 100;
 my $cell_height   = 50;
 my $legend_height = 16;
 my $width       = $cols * $cell_width;
 my $height      = $rows * $cell_height;

 my $img = GD::Simple->new($width,$height);
 $img->font(gdSmallFont);

 for (my $c=0; $c<$cols; $c++) {
   for (my $r=0; $r<$rows; $r++) {
     my $color = $color_names[$c*$rows + $r] or next;
     my @topleft  = ($c*$cell_width,$r*$cell_height);
     my @botright = ($topleft[0]+$cell_width,
	$topleft[1]+$cell_height-$legend_height);
     $img->bgcolor($color);
     $img->fgcolor($color);
     $img->rectangle(@topleft,@botright);
     $img->moveTo($topleft[0]+2,$botright[1]+$legend_height-2);
     $img->fgcolor('black');
     $img->string($color);
   }
 }

 print $img->png;

=head1 著者

=begin comment
The GD::Simple module is copyright 2004, 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.
=end comment
GD::Simple モジュールは 2004 年 Lincoln D. Stein が著作権を持っています。
これは Perl 自身と同じ条件の下で配布されています。
ライセンス条項に関しては、Perl のソースコード配布物に含まれる 
"Artistic License" を参照してください。 

(訳注: この日本語訳は Shigeharu TAKENO <shige@iee.niit.ac.jp> に
よります。)

=begin comment
The latest versions of GD.pm are available at
=end comment
GD.pm の最新版は以下にあります:

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

=head1 関連項目

L<GD>,
L<GD::Polyline>,
L<GD::SVG>,
L<Image::Magick>


=cut