1 package Imager::Matrix2d;
4 use Scalar::Util qw(reftype looks_like_number);
7 our $VERSION = "1.013";
11 Imager::Matrix2d - simple wrapper for matrix construction
16 $m1 = Imager::Matrix2d->identity;
17 $m2 = Imager::Matrix2d->rotate(radians=>$angle, x=>$cx, y=>$cy);
18 $m3 = Imager::Matrix2d->translate(x=>$dx, y=>$dy);
19 $m4 = Imager::Matrix2d->shear(x=>$sx, y=>$sy);
20 $m5 = Imager::Matrix2d->reflect(axis=>$axis);
21 $m6 = Imager::Matrix2d->scale(x=>$xratio, y=>$yratio);
22 $m8 = Imager::Matric2d->matrix($v11, $v12, $v13,
27 use Imager::Matrix2d qw(:handy);
28 # various m2d_* functions imported
29 # where m2d_(.*) calls Imager::Matrix2d->$1()
33 This class provides a simple wrapper around a reference to an array of
34 9 coefficients, treated as a matrix:
40 Most of the methods in this class are constructors. The others are
43 Note that since Imager represents images with y increasing from top to
44 bottom, rotation angles are clockwise, rather than counter-clockwise.
50 our @ISA = 'Exporter';
52 our @EXPORT_OK = qw(m2d_rotate m2d_identity m2d_translate m2d_shear
53 m2d_reflect m2d_scale);
56 handy=> [ qw(m2d_rotate m2d_identity m2d_translate m2d_shear
57 m2d_reflect m2d_scale) ],
68 Returns the identity matrix.
73 return bless [ 1, 0, 0,
78 =item rotate(radians=>$angle)
80 =item rotate(degrees=>$angle)
82 Creates a matrix that rotates around the origin, or around the point
83 (x,y) if the 'x' and 'y' parameters are provided.
88 my ($class, %opts) = @_;
91 if (defined $opts{radians}) {
92 $angle = $opts{radians};
94 elsif (defined $opts{degrees}) {
95 $angle = $opts{degrees} * 3.1415926535 / 180;
98 $Imager::ERRSTR = "degrees or radians parameter required";
102 if ($opts{'x'} || $opts{'y'}) {
105 return $class->translate('x'=>$opts{'x'}, 'y'=>$opts{'y'})
106 * $class->rotate(radians=>$angle)
107 * $class->translate('x'=>-$opts{'x'}, 'y'=>-$opts{'y'});
110 my $sin = sin($angle);
111 my $cos = cos($angle);
112 return bless [ $cos, -$sin, 0,
118 =item translate(x=>$dx, y=>$dy)
120 =item translate(x=>$dx)
122 =item translate(y=>$dy)
124 Translates by the specify amounts.
129 my ($class, %opts) = @_;
131 if (defined $opts{'x'} || defined $opts{'y'}) {
132 my $x = $opts{'x'} || 0;
133 my $y = $opts{'y'} || 0;
134 return bless [ 1, 0, $x,
139 $Imager::ERRSTR = 'x or y parameter required';
143 =item shear(x=>$sx, y=>$sy)
149 Shear by the given amounts.
153 my ($class, %opts) = @_;
155 if (defined $opts{'x'} || defined $opts{'y'}) {
156 return bless [ 1, $opts{'x'}||0, 0,
160 $Imager::ERRSTR = 'x and y parameters required';
164 =item reflect(axis=>$axis)
166 Reflect around the given axis, either 'x' or 'y'.
168 =item reflect(radians=>$angle)
170 =item reflect(degrees=>$angle)
172 Reflect around a line drawn at the given angle from the origin.
177 my ($class, %opts) = @_;
179 if (defined $opts{axis}) {
180 my $result = $class->identity;
181 if ($opts{axis} eq "y") {
182 $result->[0] = -$result->[0];
184 elsif ($opts{axis} eq "x") {
185 $result->[4] = -$result->[4];
188 $Imager::ERRSTR = 'axis must be x or y';
195 if (defined $opts{radians}) {
196 $angle = $opts{radians};
198 elsif (defined $opts{degrees}) {
199 $angle = $opts{degrees} * 3.1415926535 / 180;
202 $Imager::ERRSTR = 'axis, degrees or radians parameter required';
207 return $class->rotate(radians=>-$angle) * $class->reflect(axis=>'x')
208 * $class->rotate(radians=>$angle);
211 =item scale(x=>$xratio, y=>$yratio)
213 Scales at the given ratios.
215 You can also specify a center for the scaling with the C<cx> and C<cy>
221 my ($class, %opts) = @_;
223 if (defined $opts{'x'} || defined $opts{'y'}) {
224 $opts{'x'} = 1 unless defined $opts{'x'};
225 $opts{'y'} = 1 unless defined $opts{'y'};
226 if ($opts{cx} || $opts{cy}) {
227 return $class->translate('x'=>-$opts{cx}, 'y'=>-$opts{cy})
228 * $class->scale('x'=>$opts{'x'}, 'y'=>$opts{'y'})
229 * $class->translate('x'=>$opts{cx}, 'y'=>$opts{cy});
232 return bless [ $opts{'x'}, 0, 0,
238 $Imager::ERRSTR = 'x or y parameter required';
243 =item matrix($v11, $v12, $v13, $v21, $v22, $v23, $v31, $v32, $v33)
245 Create a matrix with custom coefficients.
250 my ($class, @self) = @_;
253 return bless \@self, $class;
256 $Imager::ERRSTR = "9 coefficients required";
261 =item transform($x, $y)
263 Transform a point the same way matrix_transform does.
268 my ($self, $x, $y) = @_;
270 my $sz = $x * $self->[6] + $y * $self->[7] + $self->[8];
272 if (abs($sz) > 0.000001) {
273 $sx = ($x * $self->[0] + $y * $self->[1] + $self->[2]) / $sz;
274 $sy = ($x * $self->[3] + $y * $self->[4] + $self->[5]) / $sz;
283 =item compose(matrix...)
285 Compose several matrices together for use in transformation.
287 For example, for three matrices:
289 my $out = Imager::Matrix2d->compose($m1, $m2, $m3);
293 my $out = $m3 * $m2 * $m1;
295 Returns the identity matrix if no parameters are supplied.
297 May return the supplied matrix if only one matrix is supplied.
302 my ($class, @in) = @_;
305 or return $class->identity;
308 for my $m (reverse @in) {
317 Implements the overloaded '*' operator. Internal use.
319 Currently both the left and right-hand sides of the operator must be
322 When composing a matrix for transformation you should multiply the
323 matrices in the reverse order of the transformations:
325 my $shear = Imager::Matrix2d->shear(x => 0.1);
326 my $rotate = Imager::Matrix2d->rotate(degrees => 45);
327 my $shear_then_rotate = $rotate * $shear;
329 or use the compose method:
331 my $shear_then_rotate = Imager::Matrix2d->compose($shear, $rotate);
336 my ($left, $right, $order) = @_;
339 if (reftype($right) eq "ARRAY") {
341 or croak "9 elements required in array ref";
343 ($left, $right) = ($right, $left);
350 $accum += $left->[3*$i + $k] * $right->[3*$k + $j];
352 $result[3*$i+$j] = $accum;
355 return bless \@result, __PACKAGE__;
358 croak "multiply by array ref or number";
361 elsif (defined $right && looks_like_number($right)) {
362 my @result = map $_ * $right, @$left;
364 return bless \@result, __PACKAGE__;
367 # something we don't handle
368 croak "multiply by array ref or number";
374 Implements the overloaded binary '+' operator.
376 Currently both the left and right sides of the operator must be
377 Imager::Matrix2d objects.
381 my ($left, $right, $order) = @_;
383 if (ref($right) && UNIVERSAL::isa($right, __PACKAGE__)) {
386 push @result, $left->[$_] + $right->[$_];
389 return bless \@result, __PACKAGE__;
398 Implements the overloaded stringification operator.
400 This returns a string containing 3 lines of text with no terminating
403 I tried to make it fairly nicely formatted. You might disagree :)
412 if (length() > $maxlen) {
416 $maxlen <= 9 or $maxlen = 9;
418 my @left = ('[ ', ' ', ' ');
419 my @right = ("\n", "\n", ']');
421 my $width = $maxlen+2;
425 my $val = $m->[$i*3+$j];
426 if (length $val > 9) {
427 $val = sprintf("%9f", $val);
428 if ($val =~ /\./ && $val !~ /e/i) {
434 $out .= sprintf("%-${width}s", "$val, ");
444 Implement the overloaded equality operator.
446 Provided for older perls that don't handle magic auto generation of eq
452 my ($left, $right) = @_;
454 return $left . "" eq $right . "";
459 The following functions are shortcuts to the various constructors.
461 These are not methods.
463 You can import these methods with:
465 use Imager::Matrix2d ':handy';
473 =item m2d_translate()
486 return __PACKAGE__->identity;
490 return __PACKAGE__->rotate(@_);
494 return __PACKAGE__->translate(@_);
498 return __PACKAGE__->shear(@_);
502 return __PACKAGE__->reflect(@_);
506 return __PACKAGE__->scale(@_);
513 Tony Cook <tony@develop-help.com>
517 Needs a way to invert a matrix.
521 Imager(3), Imager::Font(3)
523 http://imager.perl.org/