=begin comment $Id: GD::Polyline-jp.pod,v 1.9 2005-12-20 16:23:41+09 shige Exp $ GD::Polyline-jp.pod 日本語訳: Shigeharu TAKENO 1) % perldoc -u GD/Polyline.pm > ../GD::Polyline.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::Polyline - Polyline object and Polygon utilities (including splines) for use with GD =end comment GD::Polyline - 折れ線オブジェクト、及び GD で使用するための多角形ユーティリティ (スプラインを含む) =head1 形式 use GD; use GD::Polyline; # 画像を作成 $image = new GD::Image (500,300); $white = $image->colorAllocate(255,255,255); $black = $image->colorAllocate( 0, 0, 0); $red = $image->colorAllocate(255, 0, 0); # 新しい折れ線を作成 $polyline = new GD::Polyline; # 点をいくつか追加 $polyline->addPt( 0, 0); $polyline->addPt( 0,100); $polyline->addPt( 50,125); $polyline->addPt(100, 0); # 折れ線は多角形メソッドも使える (逆も可) $polyline->offset(200,100); # 中心に関して 60 度回転 $polyline->rotate(3.14159/3, $polyline->centroid()); # 中心からの縮尺変換 $polyline->scale(1.5, 2, $polyline->centroid()); # 折れ線の描画 $image->polydraw($polyline,$black); # スプラインの作成 (これは折れ線でもある) $spline = $polyline->addControlPoints->toSpline; $image->polydraw($spline,$red); # PNG 出力 binmode STDOUT; print $image->png; =head1 機能説明 =begin comment B extends the GD module by allowing you to create polylines. Think of a polyline as "an open polygon", that is, the last vertex is not connected to the first vertex (unless you expressly add the same value as both points). =end comment B は、GD モジュールを、折れ線を作成できるように 拡張します。折れ線とは、"開いた多角形"、 すなわち最後の頂点が最初の頂点と結ばれていないもの、 と考えてください (明示的にその両者を同一の点としなければ)。 =begin comment For the remainder of this doc, "polyline" will refer to a GD::Polyline, "polygon" will refer to a GD::Polygon that is not a polyline, and "polything" and "$poly" may be either. =end comment この文書中、今後 "polyline" は GD::Polyline を意味し、 "polygon" は折れ線でない GD::Polygon を意味し、 "polything" と "$poly" はどちらか一方を指すものとします。 (訳注: 日本語訳では、"polyline" は「折れ線」、"polygon" は「多角形」、 "polything" は「折れ線 (または多角形)」のように記載します。) =begin comment The big feature added to GD by this module is the means to create splines, which are approximations to curves. =end comment このモジュールによって GD に追加される大きな機能は、 スプライン曲線の生成で、これは折れ線を曲線で近似します。 =head1 折れ線オブジェクト =begin comment GD::Polyline defines the following class: =end comment GD::Polyline は以下のクラスを定義します: =over 5 =item C =begin comment A polyline object, used for storing lists of vertices prior to rendering a polyline into an image. =end comment 折れ線のオブジェクト。これは、画像内に折れ線を描画する前に、 頂点のリストを保存するのに使われます。 =item C Cnew> I =begin comment Create an empty polyline with no vertices. =end comment 頂点を持たない、空の折れ線を生成します。 $polyline = new GD::Polyline; $polyline->addPt( 0, 0); $polyline->addPt( 0,100); $polyline->addPt( 50,100); $polyline->addPt(100, 0); $image->polydraw($polyline,$black); =begin comment In fact GD::Polyline is a subclass of GD::Polygon, so all polygon methods (such as B and B) may be used on polylines. Some new methods have thus been added to GD::Polygon (such as B) and a few updated/modified/enhanced (such as B) I. See section "New or Updated GD::Polygon Methods" for more info. =end comment 実は、GD::Polyline は GD::Polygon のサブクラスで、 B や B のようなすべての多角形用のメソッドを 折れ線にも使うことができます。 そして、GD::Polygon のメソッドに、B のような 新しいメソッドもいくつか追加されていて、 B のように I<このモジュール内で> 少し更新/改良/拡張されている メソッドもあります。 =back =begin comment Note that this module is very "young" and should be considered subject to change in future releases, and/or possibly folded in to the existing polygon object and/or GD module. =end comment このモジュールはまだ "若い" ので、将来のリリースでは変更される 可能性があると考えてください。 そして、GD モジュールの多角形オブジェクトに含まれることになるかもしれません。 =head1 Updated Polygon Methods =begin comment The following methods (defined in GD.pm) are OVERRIDDEN if you use this module. =end comment GD.pm で定義されている以下のメソッドは、 このモジュールを使うと上書きされます。 =begin comment All effort has been made to provide 100% backward compatibility, but if you can confirm that has not been achieved, please consider that a bug and let the the author of Polyline.pm know. =end comment 100% の後方互換性を提供するために色んな努力をしてきましたが、 それが行われていないことを確認できたならば、 それをバグと見なして Polyline.pm の著者に連絡してください。 =over 5 =item C =begin comment C<$poly-Escale($sx, $sy, $cx, $cy)> I =end comment C<$poly-Escale($sx, $sy, $cx, $cy)> I<オブジェクトメソッド -- GD::Polygon::scale の更新版> =begin comment Scale a polything in along x-axis by $sx and along the y-axis by $sy, about centery point ($cx, $cy). =end comment これは、折れ線 (または多角形) を、点 ($cx, $cy) を中心に、 x-軸方向に $sx 倍、y-軸方向に $sy 倍します。 =begin comment Center point ($cx, $cy) is optional -- if these are omitted, the function will scale about the origin. =end comment 中心点 ($cx, $cy) の指定は必須ではありません。 それが省略された場合は、この関数は原点を中心に拡大します。 =begin comment To flip a polything, use a scale factor of -1. For example, to flip the polything top to bottom about line y = 100, use: =end comment 拡大率として -1 を指定すると、折れ線 (または多角形) を反転します。 例えば、折れ線 (または多角形) を、直線 y=100 に関して 上下反転するには: $poly->scale(1, -1, 0, 100); =back =head1 多角形の新メソッド =begin comment The following methods are added to GD::Polygon, and thus can be used by polygons and polylines. =end comment 以下のメソッドは GD::Polygon に追加するもので、 よって多角形にも折れ線にも使えます。 =begin comment Don't forget: a polyline is a GD::Polygon, so GD::Polygon methods like offset() can be used, and they can be used in GD::Image methods like filledPolygon(). =end comment 折れ線は、GD::Polygon の一つであることを忘れないでください。 だから、offset() のような GD::Polygon のメソッドも使えますし、 filledPolygon() のような GD::Image のメソッドも使えます。 =over 5 =item C =begin comment C<$poly-Erotate($angle, $cx, $cy)> I =end comment C<$poly-Erotate($angle, $cx, $cy)> I<オブジェクトメソッド> =begin comment Rotate a polything through $angle (clockwise, in radians) about center point ($cx, $cy). =end comment これは、折れ線 (または多角形) を、点 ($cx, $cy) を中心にして、 $angle だけ回転 (時計回り、単位はラジアン) します。 =begin comment Center point ($cx, $cy) is optional -- if these are omitted, the function will rotate about the origin =end comment 中心点 ($cx, $cy) の指定は必須ではありません。 それが省略された場合は、この関数は原点を中心に回転します。 =begin comment In this function and other angle-oriented functions in GD::Polyline, positive $angle corrensponds to clockwise rotation. This is opposite of the usual Cartesian sense, but that is because the raster is opposite of the usual Cartesian sense in that the y-axis goes "down". =end comment この関数、および GD::Polyline の他の角度用の関数において、 正の $angle は時計回りの角を意味します。 これは通常のデカルト座標のやり方とは逆ですが、 それは、描画が通常のデカルト座標とは逆の "下向き" の y 軸であることに由来しています。 =item C =begin comment C<($cx, $cy) = $poly-Ecentroid($scale)> I =end comment C<($cx, $cy) = $poly-Ecentroid($scale)> I<オブジェクトメソッド> =begin comment Calculate and return ($cx, $cy), the centroid of the vertices of the polything. For example, to rotate something 180 degrees about it's centroid: =end comment これは、折れ線 (または多角形) の頂点の中心 ($cx, $cy) を計算して それを返します。例えば、その中心に関して 180 度回転するには 以下のようにします。 $poly->rotate(3.14159, $poly->centroid()); =begin comment $scale is optional; if supplied, $cx and $cy are multiplied by $scale before returning. The main use of this is to shift an polything to the origin like this: =end comment $scale の指定は必須ではありませんが、それを与えると、 $cx, $cy は $scale 倍されて返されます。 これは主に、例えば以下のように、折れ線 (または多角形) を 原点に関して移動する場合に使われます: $poly->offset($poly->centroid(-1)); =item C =begin comment C<@segLengths = $poly-EsegLength()> I =end comment C<@segLengths = $poly-EsegLength()> I<オブジェクトメソッド> =begin comment In array context, returns an array the lengths of the segments in the polything. Segment n is the segment from vertex n to vertex n+1. Polygons have as many segments as vertices; polylines have one fewer. =end comment 配列コンテキストでは、これは折れ線 (または多角形) に含まれる 線分の長さの配列を返します。 線分 n は、頂点 n から頂点 n+1 への線分を意味します。 多角形は、頂点数と同じだけの線分を持ちますが、 折れ線の線分数は頂点数より一つ少ないです。 =begin comment In a scalar context, returns the sum of the array that would have been returned in the array context. =end comment スカラーコンテキストでは、配列コンテキストで返される配列の和を 返します。 =item C =begin comment C<@segAngles = $poly-EsegAngle()> I =end comment C<@segAngles = $poly-EsegAngle()> I<オブジェクトメソッド> =begin comment Returns an array the angles of each segment from the x-axis. Segment n is the segment from vertex n to vertex n+1. Polygons have as many segments as vertices; polylines have one fewer. =end comment これは、各線分の、x 軸から測った角度を持つ配列を返します。 線分 n は、頂点 n から頂点 n+1 への線分を意味します。 多角形は、頂点数と同じだけの線分を持ちますが、 折れ線の線分数は頂点数より一つ少ないです。 =begin comment Returned angles will be on the interval 0 <= $angle < 2 * pi and angles increase in a clockwise direction. =end comment 返される角度は区間 0 <= $angle < 2π 内の値で、 角度は時計回りに増加します。 =item C =begin comment C<@vertexAngles = $poly-EvertexAngle()> I =end comment C<@vertexAngles = $poly-EvertexAngle()> I<オブジェクトメソッド> =begin comment Returns an array of the angles between the segment into and out of each vertex. For polylines, the vertex angle at vertex 0 and the last vertex are not defined; however $vertexAngle[0] will be undef so that $vertexAngle[1] will correspond to vertex 1. =end comment これは、各頂点での、2 辺の間の角度を持つ配列を返します。 折れ線では、頂点 0 と最後の頂点ではこの頂点角度は定義されません。 しかし、$vertexAngle[1] が頂点 1 に対応するように、 $vertexAngle[0] は undef とされます。 =begin comment Returned angles will be on the interval 0 <= $angle < 2 * pi and angles increase in a clockwise direction. =end comment 返される角度は区間 0 <= $angle < 2π 内の値で、 角度は時計回りに増加します。 =begin comment Note that this calculation does not attempt to figure out the "interior" angle with respect to "inside" or "outside" the polygon, but rather, just the angle between the adjacent segments in a clockwise sense. Thus a polygon with all right angles will have vertex angles of either pi/2 or 3*pi/2, depending on the way the polygon was "wound". =end comment この計算では、多角形の "内側" か "外側" に関して "内角" を見分けようとはせず、 むしろ時計方向に考えて隣接した線分の角を測ります。 よって、すべての角が直角である多角形の場合 その頂点角は π/2 か 3π/2で、 それは多角形がどちらに回っているのかによって変わります。 =item C =begin comment C<$poly-EtoSpline()> I =end comment C<$poly-EtoSpline()> I<オブジェクトメソッドかつ製造メソッド> =begin comment Create a new polything which is a reasonably smooth curve using cubic spline algorithms, often referred to as Bezier curves. The "source" polything is called the "control polything". If it is a polyline, the control polyline must have 4, 7, 10, or some number of vertices of equal to 3n+1. If it is a polygon, the control polygon must have 3, 6, 9, or some number of vertices of equal to 3n. =end comment これは、新しい折れ線 (または多角形) を作りますが、 それは 3 次スプラインアルゴリズムで計算される、 ベジェ曲線と呼ばれるかなり滑らかな曲線になります。 "元の" 折れ線 (または多角形) は、"制御折れ線 (または多角形)" と呼ばれます。 それが折れ線の場合、制御折れ線は 4, 7, 10, ... 等の 3n+1 個の 頂点を持つ必要があります。 それが多角形の場合、制御多角形は 3, 6, 9, ... 等の 3n 個の 頂点を持つ必要があります。 $spline = $poly->toSpline(); $image->polydraw($spline,$red); =begin comment In brief, groups of four points from the control polyline are considered "control points" for a given portion of the spline: the first and fourth are "anchor points", and the spline passes through them; the second and third are "director points". The spline does not pass through director points, however the spline is tangent to the line segment from anchor point to adjacent director point. =end comment 要約すると、制御折れ線からの 4 点ずつの組が スプラインの与えられた部分の "制御点" と見なされます。 最初の点と 4 つ目の点は "停泊点" といい、 このスプラインはこれらを通ります。 2 つ目の点と 3 つ目の点は "監視点" で、 このスプラインは監視点は通りませんが、 スプラインは、停泊点から隣接する監視点を結ぶ線分に接します。 =begin comment The next portion of the spline reuses the previous portion's last anchor point. The spline will have a cusp (non-continuous slope) at an anchor point, unless the anchor points and its adjacent director point are colinear. =end comment 次のスプライン部分では、前の部分の最後の停泊点が再び使われます。 このスプラインは、 停泊点とそれに隣接する監視点が共線でない場合、 ある停泊点で尖り (不連続な傾き) が出ることがあります。 =begin comment In the current implementation, toSpline() return a fixed number of segments in the returned polyline per set-of-four control points. In the future, this and other parameters of the algorithm may be configurable. =end comment 現在の実装では、toSpline() が返す 4 つの制御点毎の折れ線は、 決まった数の線分になります。 将来は、この数やこのアルゴリズムで使用される他のパラメータは、 設定できるようになるかもしれません。 =item C =begin comment C<$polyline-EaddControlPoints()> I =end comment C<$polyline-EaddControlPoints()> I<オブジェクトメソッドかつ製造メソッド> =begin comment So you say: "OK. Splines sound cool. But how can I get my anchor points and its adjacent director point to be colinear so that I have a nice smooth curves from my polyline?" Relax! For The Lazy: addControlPoints() to the rescue. =end comment 次のような言い分もあるだろう: "なるほど、確かにスプラインはいいんだけど、 じゃあどうやったら停泊点と監視点を共線にできて 私の折れ線を適当な滑らかな曲線にできるんだい ?" 大丈夫! それをサボるには addControlPoints() が使えます。 =begin comment addControlPoints() returns a polyline that can serve as the control polyline for toSpline(), which returns another polyline which is the spline. Is your head spinning yet? Think of it this way: =end comment addControlPoints() は toSpline() 用の制御折れ線として使えるような 折れ線を返し、toSpline() は、スプラインであるような 別の折れ線を返します。よくわかりませんか ? これは次のように考えてください。 =over 5 =item + =begin comment If you have a polyline, and you have already put your control points where you want them, call toSpline() directly. Remember, only every third vertex will be "on" the spline. =end comment 折れ線が一つあり、そして既にそれに必要な制御点を与えてある場合、 直接 toSpline() を呼び出してください。 全ての 3 番目の頂点のみがそのスプラインの "上" にあることを 忘れないでください。 =begin comment You get something that looks like the spline "inscribed" inside the control polyline. =end comment 制御折れ線の内側に "刻まれた" スプラインのようなものが 得られることになります。 =item + =begin comment If you have a polyline, and you want all of its vertices on the resulting spline, call addControlPoints() and then toSpline(): =end comment 折れ線が一つあり、その頂点全てが結果のスプラインの上に 乗って欲しい場合、addControlPoints() を呼んで、その次に toSpline() を呼んでください: $control = $polyline->addControlPoints(); $spline = $control->toSpline(); $image->polyline($spline,$red); =begin comment You get something that looks like the control polyline "inscribed" inside the spline. =end comment スプラインの内側に "刻まれた" 制御折れ線のようなものが 得られることになります。 =back =begin comment Adding "good" control points is subjective; this particular algorithm reveals its author's tastes. In the future, you may be able to alter the taste slightly via parameters to the algorithm. For The Hubristic: please build a better one! =end comment "良い" 制御点の追加法は多分に主観的で、この特定のアルゴリズムには その作者の好みが見えます。 将来は、そのアルゴリズムに対するパラメータを通して、 それらのわずかな癖を変更できるようになるかもしれません。 自信家の方へ: もっといいものを作ってみて! =begin comment And for The Impatient: note that addControlPoints() returns a polyline, so you can pile up the the call like this, if you'd like: =end comment せっかちな方へ: addControlPoints() は折れ線を返すことに注意して ください。よって、望むなら、これらの呼び出しを積み重ねて 以下のようにすることもできます: $image->polyline($polyline->addControlPoints()->toSpline(),$mauve); =back =head1 新しい GD::Image メソッド =over 5 =item C =begin comment C<$image-Epolyline(polyline,color)> I =end comment C<$image-Epolyline(polyline,color)> I<オブジェクトメソッド> $image->polyline($polyline,$black) =begin comment This draws a polyline with the specified color. Both real color indexes and the special colors gdBrushed, gdStyled and gdStyledBrushed can be specified. =end comment これは、指定された色の折れ線を描画します。色は、普通の色の他に、 特別な色指定である gdBrushed, gdStyled, gdStyledBrushed を 使うこともできます。 =begin comment Neither the polyline() method or the polygon() method are very picky: you can call either method with either a GD::Polygon or a GD::Polyline. The I determines if the shape is "closed" or "open" as drawn, I the object type. =end comment polyline メソッドと polygon() メソッドはいずれもほとんど えり好みをしないので、いずれのメソッドを GD::Polygon や GD::Polyline のいずれのオブジェクトにも呼びだせます。 この I<メソッド> はオブジェクトの型を決定するのではなく、 その形が "閉じた" ものとして描画されるか "開いた" ものとして 描画されるかを決定します。 =item C =begin comment C<$image-Epolydraw(polything,color)> I =end comment C<$image-Epolydraw(polything,color)> I<オブジェクトメソッド> $image->polydraw($poly,$black) =begin comment This method draws the polything as expected (polygons are closed, polylines are open) by simply checking the object type and calling either $image->polygon() or $image->polyline(). =end comment このメソッドは折れ線または多角形を、オブジェクト型、及び $image->polygon() か $image->polyline() のどちらが呼ばれたかを 簡単にチェックすることで、期待されるように (多角形なら閉曲線、 折れ線なら開曲線) 描画します。 =back =head1 例 =begin comment Please see file "polyline-examples.pl" that is included with the distribution. =end comment 配布物に含まれるファイル "polyline-examples.pl" を参照して ください。 =head1 参照 =begin comment For more info on Bezier splines, see http://www.webreference.com/dlab/9902/bezier.html. =end comment ベジェ曲線に関するさらなる情報については、 http://www.webreference.com/dlab/9902/bezier.html を参照して ください。 =head1 将来の機能 =begin comment On the drawing board are additional features such as: =end comment 以下のような追加機能をスケッチしています: =begin comment - polygon winding algorithms (to determine if a point is "inside" or "outside" the polygon) - new polygon from bounding box - find bounding polygon (tightest fitting simple convex polygon for a given set of vertices) - addPts() method to add many points at once - clone() method for polygon - functions to interwork GD with SVG =end comment - 多角形の曲線アルゴリズム (ある点が多角形の "内" にあるか "外" にあるかを決定するもの) - 箱に収まる新しい多角形 - 境界となる多角形の検索 (与えられた頂点集合を丁度含むような凸多角形) - たくさんの点を一度に追加する addPts() メソッド - 多角形の clone() メソッド - SVG とのやりとりを行える GD に対する関数 =begin comment Please provide input on other possible features you'd like to see. =end comment あなたが見たいと思う、可能な他の機能があればそれを教えてください。 =head1 著者 =begin comment This module has been written by Daniel J. Harasty. Please send questions, comments, complaints, and kudos to him at harasty@cpan.org. =end comment このモジュールは Daniel J. Harasty によって作られました。 質問、コメント、苦情、賞賛は彼 (harasty@cpan.org) に送って ください。 =begin comment Thanks to Lincoln Stein for input and patience with me and this, my first CPAN contribution. =end comment 私、及び CPAN への私の最初の寄与であるこのモジュールに対する、 Lincoln Stein の入力と忍耐に感謝します。 =head1 著作権情報 =begin comment The Polyline.pm module is copyright 2002, Daniel J. Harasty. 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 Polyline.pm モジュールは、2002 年に Daniel J. Harasty が著作権を 持っています。これは Perl と同じ条件の下で配布されます。 ライセンス条項に関しては、Perl のソースコード配布物に含まれる "Artistic License" を参照してください。 (訳注: この日本語訳は Shigeharu TAKENO に よります。) =begin comment The latest version of Polyline.pm is available at your favorite CPAN repository and/or along with GD.pm by Lincoln D. Stein at http://stein.cshl.org/WWW/software/GD. =end comment Polyline.pm の最新版は、好みの CPAN リポジトリ、あるいは Lincoln D. Stein による GD.pm と一緒に http://stein.cshl.org/WWW/software/GD にあります。 =cut