1Transform(3) User Contributed Perl Documentation Transform(3)
2
6 PDL::Transform - Coordinate transforms, image warping, and N-D func‐
7 tions
8
10 use PDL::Transform;
11 my $t = new PDL::Transform::<type>(<opt>)
13 $out = $t->apply($in) # Apply transform to some N-vectors (Transform method)
15 $out = $in->apply($t) # Apply transform to some N-vectors (PDL method)
16 $im1 = $t->map($im); # Transform image coordinates (Transform method)
18 $im1 = $im->map($t); # Transform image coordinates (PDL method)
19 $t2 = $t->compose($t1); # compose two transforms
21 $t2 = $t x $t1; # compose two transforms (by analogy to matrix mult.)
22 $t3 = $t2->inverse(); # invert a transform
24 $t3 = !$t2; # invert a transform (by analogy to logical "not")
25
27 PDL::Transform is a convenient way to represent coordinate transforma‐
28 tions and resample images. It embodies functions mapping R^N -> R^M,
29 both with and without inverses. Provision exists for parametrizing
30 functions, and for composing them. You can use this part of the Trans‐
31 form object to keep track of arbitrary functions mapping R^N -> R^M
32 with or without inverses.
33 The simplest way to use a Transform object is to transform vector data
35 between coordinate systems. The apply method accepts a PDL whose 0th
36 dimension is coordinate index (all other dimensions are threaded over)
37 and transforms the vectors into the new coordinate system.
38 Transform also includes image resampling, via the map method. You
40 define a coordinate transform using a Transform object, then use it to
41 remap an image PDL. The output is a remapped, resampled image.
42 You can define and compose several transformations, then apply them all
44 at once to an image. The image is interpolated only once, when all the
45 composed transformations are applied.
46 In keeping with standard practice, but somewhat counterintuitively, the
48 map engine uses the inverse transform to map coordinates FROM the des‐
49 tination dataspace (or image plane) TO the source dataspace; hence
50 PDL::Transform keeps track of both the forward and inverse transform.
51 For terseness and convenience, most of the constructors are exported
53 into the current package with the name "t_\<transform\">, so the fol‐
54 lowing (for example) are synonyms:
55 $t = new PDL::Transform::Radial(); # Long way
57 $t = t_radial(); # Short way
59 Several math operators are overloaded, so that you can compose and
61 invert functions with expression syntax instead of method syntax (see
62 below).
63
65 Coordinate transformations and mappings are a little counterintuitive
66 at first. Here are some examples of transforms in action:
67 use PDL::Transform;
69 $a = rfits('m51.fits'); # Substitute path if necessary!
70 $ts = t_linear(Scale=>3); # Scaling transform
71 $w = pgwin(xs);
73 $w->imag($a);
74 ## Grow m51 by a factor of 3; origin is at lower left.
76 $b = $ts->map($a,{pix=>1}); # pix option uses direct pixel coord system
77 $w->imag($b);
78 ## Shrink m51 by a factor of 3; origin still at lower left.
80 $c = $ts->unmap($a, {pix=>1});
81 $w->imag($c);
82 ## Grow m51 by a factor of 3; origin is at scientific origin.
84 $d = $ts->map($a,$a->hdr); # FITS hdr template prevents autoscaling
85 $w->imag($d);
86 ## Shrink m51 by a factor of 3; origin is still at sci. origin.
88 $e = $ts->unmap($a,$a->hdr);
89 $w->imag($e);
90 ## A no-op: shrink m51 by a factor of 3, then autoscale back to size
92 $f = $ts->map($a); # No template causes autoscaling of output
93
95 '!'
96 The bang is a unary inversion operator. It binds exactly as tightly
97 as the normal bang operator.
98 'x'
100 By analogy to matrix multiplication, 'x' is the compose operator, so
101 these two expressions are equivalent:
102 $f->inverse()->compose($g)->compose($f) # long way
104 !$f x $g x $f # short way
105 Both of those expressions are equivalent to the mathematical expres‐
107 sion f^-1 o g o f, or f^-1(g(f(x))).
108 '**'
110 By analogy to numeric powers, you can apply an operator a positive
111 integer number of times with the ** operator:
112 $f->compose($f)->compose($f) # long way
114 $f**3 # short way
115
117 Transforms are perl hashes. Here's a list of the meaning of each key:
118 func
120 Ref to a subroutine that evaluates the transformed coordinates.
121 It's called with the input coordinate, and the "params" hash. This
122 springboarding is done via explicit ref rather than by subclassing,
123 for convenience both in coding new transforms (just add the appro‐
124 priate sub to the module) and in adding custom transforms at
125 run-time. Note that, if possible, new "func"s should support inplace
126 operation to save memory when the data are flagged inplace. But
127 "func" should always return its result even when flagged to compute
128 in-place.
129 "func" should treat the 0th dimension of its input as a dimensional
131 index (running 0..N-1 for R^N operation) and thread over all other
132 input dimensions.
133 inv
135 Ref to an inverse method that reverses the transformation. It must
136 accept the same "params" hash that the forward method accepts. This
137 key can be left undefined in cases where there is no inverse.
138 idim, odim
140 Number of useful dimensions for indexing on the input and output
141 sides (ie the order of the 0th dimension of the coordinates to be
142 fed in or that come out). If this is set to 0, then as many are
143 allocated as needed.
144 name
146 A shorthand name for the transformation (convenient for debugging).
147 You should plan on using UNIVERAL::isa to identify classes of trans‐
148 formation, e.g. all linear transformations should be subclasses of
149 PDL::Transform::Linear. That makes it easier to add smarts to,
150 e.g., the compose() method.
151 itype
153 An array containing the name of the quantity that is expected from
154 the input piddle for the transform, for each dimension. This field
155 is advisory, and can be left blank if there's no obvious quantity
156 associated with the transform. This is analogous to the CTYPEn
157 field used in FITS headers.
158 oname
160 Same as itype, but reporting what quantity is delivered for each
161 dimension.
162 iunit
164 The units expected on input, if a specific unit (e.g. degrees) is
165 expected. This field is advisory, and can be left blank if there's
166 no obvious unit associated with the transform.
167 ounit
169 Same as iunit, but reporting what quantity is delivered for each
170 dimension.
171 params
173 Hash ref containing relevant parameters or anything else the func
174 needs to work right.
175 is_inverse
177 Bit indicating whether the transform has been inverted. That is
178 useful for some stringifications (see the PDL::Transform::Linear
179 stringifier), and may be useful for other things.
180 Transforms should be inplace-aware where possible, to prevent excessive
182 memory usage.
183 If you define a new type of transform, consider generating a new
185 stringify method for it. Just define the sub "stringify" in the sub‐
186 class package. It should call SUPER::stringify to generate the first
187 line (though the PDL::Transform::Composition bends this rule by tweak‐
188 ing the top-level line), then output (indented) additional lines as
189 necessary to fully describe the transformation.
190
192 Transforms have a mechanism for labeling the units and type of each
193 coordinate, but it is just advisory. A routine to identify and, if
194 necessary, modify units by scaling would be a good idea. Currently, it
195 just assumes that the coordinates are correct for (e.g.) FITS scien‐
196 tific-to-pixel transformations.
197 Composition works OK but should probably be done in a more sophisti‐
199 cated way so that, for example, linear transformations are combined at
200 the matrix level instead of just strung together pixel-to-pixel.
201
203 There are both operators and constructors. The constructors are all
204 exported, all begin with "t_", and all return objects that are sub‐
205 classes of PDL::Transform.
206 The apply, invert, map, and unmap methods are also exported to the
208 "PDL" package: they are both Transform methods and PDL methods.
209
211 apply
212 Signature: (data(); PDL::Transform t)
214 $out = $data->apply($t);
216 $out = $t->apply($data);
217 Apply a transformation to some input coordinates.
219 In the example, $t is a PDL::Transform and $data is a PDL to be inter‐
221 preted as a collection of N-vectors (with index in the 0th dimension).
222 The output is a similar but transformed PDL.
223 For convenience, this is both a PDL method and a Transform method.
225 invert
227 Signature: (data(); PDL::Transform t)
229 $out = $t->invert($data);
231 $out = $data->invert($t);
232 Apply an inverse transformation to some input coordinates.
234 In the example, $t is a PDL::Transform and $data is a piddle to be
236 interpreted as a collection of N-vectors (with index in the 0th dimen‐
237 sion). The output is a similar piddle.
238 For convenience this is both a PDL method and a PDL::Transform method.
240 map
242 Signature: (k0(); SV *in; SV *out; SV *map; SV *boundary; SV *method;
244 SV *big; SV *blur; SV *sv_min; SV *flux)
245 PDL::match
247 $b = $a->match($c);
249 Resample a scientific image to the same coordinate system as another.
251 The example above is syntactic sugar for
253 $b = $a->map(t_identity, $c, ...);
255 it resamples the input PDL with the identity transformation in scien‐
257 tific coordinates, and matches the pixel coordinate system to $c's FITS
258 header.
259 map
261 $b = $a->map($xform,[<template>],[\%opt]); # Distort $a with tranform $xform
263 $b = $a->map(t_identity,[$pdl],[\%opt]); # rescale $a to match $pdl's dims.
264 Resample an image or N-D dataset using a coordinate transform.
266 The data are resampled so that the new pixel indices are proportional
268 to the transformed coordinates rather than the original ones.
269 The operation uses the inverse transform: each output pixel location is
271 inverse-transformed back to a location in the original dataset, and the
272 value is interpolated or sampled appropriately and copied into the out‐
273 put domain. A variety of sampling options are available, trading off
274 speed and mathematical correctness.
275 For convenience, this is both a PDL method and a PDL::Transform method.
277 "map" is FITS-aware: if there is a FITS header in the input data, then
279 the coordinate transform acts on the scientific coordinate system
280 rather than the pixel coordinate system.
281 By default, the output coordinates are separated from pixel coordinates
283 by a single layer of indirection. You can specify the mapping between
284 output transform (scientific) coordinates to pixel coordinates using
285 the "orange" and "irange" options (see below), or by supplying a FITS
286 header in the template.
287 If you don't specify an output transform, then the output is
289 autoscaled: "map" transforms a few vectors in the forward direction to
290 generate a mapping that will put most of the data on the image plane,
291 for most transformations. The calculated mapping gets stuck in the
292 output's FITS header.
293 Autoscaling is especially useful for rescaling images -- if you specify
295 the identity transform and allow autoscaling, you duplicate the func‐
296 tionality of rescale2d, but with more options for interpolation.
297 You can operate in pixel space, and avoid autoscaling of the output, by
299 setting the "nofits" option (see below).
300 The output has the same data type as the input. This is a feature, but
302 it can lead to strange-looking banding behaviors if you use interpola‐
303 tion on an integer input variable.
304 The "template" can be one of:
306 * a PDL
308 The PDL and its header are copied to the output array, which is then
309 populated with data. If the PDL has a FITS header, then the FITS
310 transform is automatically applied so that $t applies to the output
311 scientific coordinates and not to the output pixel coordinates. In
312 this case the NAXIS fields of the FITS header are ignored.
313 * a FITS header stored as a hash ref
315 The FITS NAXIS fields are used to define the output array, and the
316 FITS transformation is applied to the coordinates so that $t applies
317 to the output scientific coordinates.
318 * a list ref
320 This is a list of dimensions for the output array. The code esti‐
321 mates appropriate pixel scaling factors to fill the available space.
322 The scaling factors are placed in the output FITS header.
323 * nothing
325 In this case, the input image size is used as a template, and scal‐
326 ing is done as with the list ref case (above).
327 OPTIONS:
329 The following options are interpreted:
331 b, bound, boundary, Boundary (default = 'truncate')
333 This is the boundary condition to be applied to the input image; it
334 is passed verbatim to range or interpND in the sampling or interpo‐
335 lating stage. Other values are 'forbid','extend', and 'periodic'.
336 You can abbreviate this to a single letter. The default 'truncate'
337 causes the entire notional space outside the original image to be
338 filled with 0.
339 p, pix, Pixel, nf, nofits, NoFITS (default = 0)
341 If you set this to a true value, then FITS headers and interpreta‐
342 tion are ignored; the transformation is treated as being in raw
343 pixel coordinates.
344 j, J, just, justify, Justify (default = 0)
346 If you set this to 1, then output pixels are autoscaled to have unit
347 aspect ratio in the output coordinates. If you set it to a non-1
348 value, then it is the aspect ratio between the first dimension and
349 all subsequent dimensions -- or, for a 2-D transformation, the sci‐
350 entific pixel aspect ratio. Values less than 1 shrink the scale in
351 the first dimension compared to the other dimensions; values greater
352 than 1 enlarge it compared to the other dimensions. (This is the
353 same sense as in the PGPLOTinterface.)
354 ir, irange, input_range, Input_Range
356 This is a way to modify the autoscaling. It specifies the range of
357 input scientific (not necessarily pixel) coordinates that you want
358 to be mapped to the output image. It can be either a nested array
359 ref or a piddle. The 0th dim (outside coordinate in the array ref)
360 is dimension index in the data; the 1st dim should have order 2.
361 For example, passing in either [[-1,2],[3,4]] or pdl([[-1,2],[3,4]])
362 limites the map to the quadrilateral in input space defined by the
363 four points (-1,3), (-1,4), (2,4), and (2,3).
364 As with plain autoscaling, the quadrilateral gets sparsely sampled
366 by the autoranger, so pathological transformations can give you
367 strange results.
368 This parameter is overridden by "orange", below.
370 or, orange, output_range, Output_Range
372 This sets the window of output space that is to be sampled onto the
373 output array. It works exactly like "irange", except that it speci‐
374 fies a quadrilateral in output space. Since the output pixel array
375 is itself a quadrilateral, you get pretty much exactly what you
376 asked for.
377 This parameter overrides "irange", if both are specified.
379 m, method, Method
381 This option controls the interpolation method to be used. Interpo‐
382 lation greatly affects both speed and quality of output. For most
383 cases the option is directly passed to interpND for interpolation.
384 Possible options, in order from fastest to slowest, are:
385 * s, sample (default for ints)
387 Pixel values in the output plane are sampled from the closest
388 data value in the input plane. This is very fast but not very
389 accurate for either magnification or decimation (shrinking). It
390 is the default for templates of integer type.
391 * l, linear (default for floats)
393 Pixel values are linearly interpolated from the closest data
394 value in the input plane. This is reasonably fast but only accu‐
395 rate for magnification. Decimation (shrinking) of the image
396 causes aliasing and loss of photometry as features fall between
397 the samples. It is the default for floating-point templates.
398 * c, cubic
400 Pixel values are interpolated using an N-cubic scheme from a
401 4-pixel N-cube around each coordinate value. As with linear
402 interpolation, this is only accurate for magnification.
403 * f, fft
405 Pixel values are interpolated using the term coefficients of the
406 Fourier transform of the original data. This is the most appro‐
407 priate technique for some kinds of data, but can yield undesired
408 "ringing" for expansion of normal images. Best suited to study‐
409 ing images with repetitive or wavelike features.
410 * h, hanning
412 Pixel values are filtered through a spatially-variable filter
413 tuned to the computed Jacobian of the transformation, with han‐
414 ning-window (cosine) pixel rolloff in each dimension. This pre‐
415 vents aliasing in the case where the image is distorted or
416 shrunk, but allows small amounts of aliasing at pixel edges wher‐
417 ever the image is enlarged.
418 * g, gaussian, j, jacobian
420 Pixel values are filtered through a spatially-variable filter
421 tuned to the computed Jacobian of the transformation, with radial
422 Gaussian rolloff. This is the most accurate resampling method,
423 in the sense of introducing the fewest artifacts into a properly
424 sampled data set.
425 blur, Blur (default = 1.0)
427 This value scales the input-space footprint of each output pixel in
428 the gaussian and hanning methods. It's retained for historical rea‐
429 sons. Larger values yield blurrier images; values significantly
430 smaller than unity cause aliasing.
431 sv, SV (default = 1.0)
433 This value lets you set the lower limit of the transformation's sin‐
434 gular values in the hanning and gaussian methods, limiting the mini‐
435 mum radius of influence associated with each output pixel. Large
436 numbers yield smoother interpolation in magnified parts of the image
437 but don't affect reduced parts of the image.
438 big, Big (default = 0.2)
440 This is the largest allowable input spot size which may be mapped to
441 a single output pixel by the hanning and gaussian methods, in units
442 of the largest non-thread input dimension. (i.e. the default won't
443 let you reduce the original image to less than 5 pixels across).
444 This places a limit on how long the processing can take for patho‐
445 logical transformations. Smaller numbers keep the code from hanging
446 for a long time; larger numbers provide for photometric accuracy in
447 more pathological cases. Numbers larer than 1.0 are silly, because
448 they allow the entire input array to be compressed into a region
449 smaller than a single pixel.
450 Wherever an output pixel would require averaging over an area that
452 is too big in input space, it instead gets NaN or the equivalent
453 (bad values are not yet supported).
454 p, phot, photometry, Photometry
456 This lets you set the style of photometric conversion to be used in
457 the hanning or gaussian methods. You may choose:
458 * 0, s, surf, surface, Surface (default)
460 (this is the default): surface brightness is preserved over the
461 transformation, so features maintain their original intensity.
462 This is what the sampling and interpolation methods do.
463 * 1, f, flux, Flux
465 Total flux is preserved over the transformation, so that the
466 brightness integral over image regions is preserved. Parts of
467 the image that are shrunk wind up brighter; parts that are
468 enlarged end up fainter.
469 VARIABLE FILTERING:
471 The 'hanning' and 'gaussian' methods of interpolation give photometri‐
473 cally accurate resampling of the input data for arbitrary transforma‐
474 tions. At each pixel, the code generates a linear approximation to the
475 input transformation, and uses that linearization to estimate the
476 "footprint" of the output pixel in the input space. The output value
477 is a weighted average of the appropriate input spaces.
478 A caveat about these methods is that they assume the transformation is
480 continuous. Transformations that contain discontinuities will give
481 incorrect results near the discontinuity. In particular, the 180th
482 meridian isn't handled well in lat/lon mapping transformations (see
483 PDL::Transform::Cartography) -- pixels along the 180th meridian get the
484 average value of everything along the parallel occupied by the pixel.
485 This flaw is inherent in the assumptions that underly creating a Jaco‐
486 bian matrix. Maybe someone will write code to work around it. Maybe
487 that someone is you.
488 PDL::Transform::unmap
490 Signature: (data(); PDL::Transform a; template(); \%opt)
492 $out_image = $in_image->unmap($t,[<options>],[<template>]);
494 $out_image = $t->unmap($in_image,[<options>],[<template>]);
495 Map an image or N-D dataset using the inverse as a coordinate trans‐
497 form.
498 This convenience function just inverts $t and calls map on the inverse;
500 everything works the same otherwise. For convenience, it is both a PDL
501 method and a PDL::Transform method.
502 t_inverse
504 $t2 = t_inverse($t);
506 $t2 = $t->inverse;
507 $t2 = $t ** -1;
508 $t2 = !$t;
509 Return the inverse of a PDL::Transform. This just reverses the
511 func/inv, idim/odim, itype/otype, and iunit/ounit pairs. Note that
512 sometimes you end up with a transform that cannot be applied or mapped,
513 because either the mathematical inverse doesn't exist or the inverse
514 func isn't implemented.
515 You can invert a transform by raising it to a negative power, or by
517 negating it with '!'.
518 The inverse transform remains connected to the main transform because
520 they both point to the original parameters hash. That turns out to be
521 useful.
522 t_compose
524 $f2 = t_compose($f, $g,[...]);
526 $f2 = $f->compose($g[,$h,$i,...]);
527 $f2 = $f x $g x ...;
528 Function composition: f(g(x)), f(g(h(x))), ...
530 You can also compose transforms using the overloaded matrix-multiplica‐
532 tion (nee repeat) operator 'x'.
533 This is accomplished by inserting a splicing code ref into the "func"
535 and "inv" slots. It combines multiple compositions into a single list
536 of transforms to be executed in order, fram last to first (in keeping
537 with standard mathematical notation). If one of the functions is
538 itself a composition, it is interpolated into the list rather than left
539 separate. Ultimately, linear transformations may also be combined
540 within the list.
541 No checking is done that the itype/otype and iunit/ounit fields are
543 compatible -- that may happen later, or you can implement it yourself
544 if you like.
545 t_wrap
547 $g1fg = $f->wrap($g);
549 $g1fg = t_wrap($f,$g);
550 Shift a transform into a different space by 'wrapping' it with a sec‐
552 ond.
553 This is just a convenience function for two compose calls.
555 "$a-"wrap($b)> is the same as "(!$b) x $a x $b": the resulting trans‐
556 form first hits the data with $b, then with $a, then with the inverse
557 of $b.
558 For example, to shift the origin of rotation, do this:
560 $im = rfits('m51.fits');
562 $tf = t_fits($im);
563 $tr = t_linear({rot=>30});
564 $im1 = $tr->map($tr); # Rotate around pixel origin
565 $im2 = $tr->map($tr->wrap($tf)); # Rotate round FITS scientific origin
566 t_identity
568 my $xform = t_identity
570 my $xform = new PDL::Transform;
571 Generic constructor generates the identity transform.
573 This constructor really is trivial -- it is mainly used by the other
575 transform constructors. It takes no parameters and returns the iden‐
576 tity transform.
577 t_lookup
579 $f = t_lookup($lookup, {<options>});
581 Transform by lookup into an explicit table.
583 You specify an N+1-D PDL that is interpreted as an N-D lookup table of
585 column vectors (vector index comes last). The last dimension has order
586 equal to the output dimensionality of the transform.
587 For added flexibility in data space, You can specify pre-lookup linear
589 scaling and offset of the data. Of course you can specify the interpo‐
590 lation method to be used. The linear scaling stuff is a little primi‐
591 tive; if you want more, try composing the linear transform with this
592 one.
593 The prescribed values in the lookup table are treated as pixel-cen‐
595 tered: that is, if your input array has N elements per row then valid
596 data exist between the locations (-0.5) and (N-0.5) in lookup pixel
597 space, because the pixels (which are numbered from 0 to N-1) are cen‐
598 tered on their locations.
599 Lookup is done using interpND, so the boundary conditions and threading
601 behaviour follow from that.
602 The indexed-over dimensions come first in the table, followed by a sin‐
604 gle dimension containing the column vector to be output for each set of
605 other dimensions -- ie to output 2-vectors from 2 input parameters,
606 each of which can range from 0 to 49, you want an index that has dimen‐
607 sion list (50,50,2). For the identity lookup table you could use
608 "cat(xvals(50,50),yvals(50,50))".
609 If you want to output a single value per input vector, you still need
611 that last index threading dimension -- if necessary, use "dummy(-1,1)".
612 The lookup index scaling is: out = lookup[ (scale * data) + offset ].
614 The inverse transform is calculated.
616 Options are listed below; there are several synonyms for each.
618 s, scale, Scale
620 (default 1.0) Specifies the linear amount of scaling to be done
621 before lookup. You can feed in a scalar or an N-vector; other val‐
622 ues may cause trouble. If you want to save space in your table,
623 then specify smaller scale numbers.
624 o, offset, Offset
626 (default 0.0) Specifies the linear amount of offset before lookup.
627 This is only a scalar, because it is intended to let you switch to
628 corner-centered coordinates if you want to (just feed in o=-0.25).
629 b, bound, boundary, Boundary
631 Boundary condition to be fed to interpND
632 m, method, Method
634 Interpolation method to be fed to interpND
635 EXAMPLE
637 To scale logarithmically the Y axis of m51, try:
639 $a = rfits('m51.fits');
641 $lookup = xvals(256,256) -> cat( 10**(yvals(256,256)/100) * 256/10**2.55 );
642 $t = t_lookup($lookup);
643 $b = $t->map($a);
644 To do the same thing but with a smaller lookup table, try:
646 $lookup = 16 * xvals(17,17)->cat(10**(yvals(17,17)/(100/16)) * 16/10**2.55);
648 $t = t_lookup($lookup,{scale=>1/16.0});
649 $b = $t->map($a);
650 (Notice that, although the lookup table coordinates are is divided by
652 16, it is a 17x17 -- so linear interpolation works right to the edge of
653 the original domain.)
654 NOTES
656 Inverses are not yet implemented -- the best way to do it might be by
658 judicious use of map() on the forward transformation.
659 the type/unit fields are ignored.
661 t_linear
663 $f = t_linear({options});
665 Linear (affine) transformations with optional offset
667 t_linear implements simple matrix multiplication with offset, also
669 known as the affine transformations.
670 You specify the linear transformation with pre-offset, a mixing matrix,
672 and a post-offset. That overspecifies the transformation, so you can
673 choose your favorite method to specify the transform you want. The
674 inverse transform is automagically generated, provided that it actually
675 exists (the transform matrix is invertible). Otherwise, the inverse
676 transform just croaks.
677 Extra dimensions in the input vector are ignored, so if you pass a 3xN
679 vector into a 3-D linear transformation, the final dimension is passed
680 through unchanged.
681 The options you can usefully pass in are:
683 s, scale, Scale
685 A scaling scalar (heh), vector, or matrix. If you specify a vector
686 it is treated as a diagonal matrix (for convenience). It gets left-
687 multiplied with the transformation matrix you specify (or the iden‐
688 tity), so that if you specify both a scale and a matrix the scaling
689 is done after the rotation or skewing or whatever.
690 r, rot, rota, rotation, Rotation
692 A rotation angle in degrees -- useful for 2-D and 3-D data only. If
693 you pass in a scalar, it specifies a rotation from the 0th axis
694 toward the 1st axis. If you pass in a 3-vector as either a PDL or
695 an array ref (as in "rot=>[3,4,5]"), then it is treated as a set of
696 Euler angles in three dimensions, and a rotation matrix is generated
697 that does the following, in order:
698 * Rotate by rot->(2) degrees from 0th to 1st axis
700 * Rotate by rot->(1) degrees from the 2nd to the 0th axis
701 * Rotate by rot->(0) degrees from the 1st to the 2nd axis
702 The rotation matrix is left-multiplied with the transformation
704 matrix you specify, so that if you specify both rotation and a gen‐
705 eral matrix the rotation happens after the more general operation --
706 though that is deprecated.
707 Of course, you can duplicate this functionality -- and get more gen‐
709 eral -- by generating your own rotation matrix and feeding it in
710 with the "matrix" option.
711 m, matrix, Matrix
713 The transformation matrix. It does not even have to be square, if
714 you want to change the dimensionality of your input. If it is
715 invertible (note: must be square for that), then you automagically
716 get an inverse transform too.
717 pre, preoffset, offset, Offset
719 The vector to be added to the data before they get multiplied by the
720 matrix (equivalent of CRVAL in FITS, if you are converting from sci‐
721 entific to pixel units).
722 post, postoffset, shift, Shift
724 The vector to be added to the data after it gets multiplied by the
725 matrix (equivalent of CRPIX-1 in FITS, if youre converting from sci‐
726 entific to pixel units).
727 d, dim, dims, Dims
729 Most of the time it is obvious how many dimensions you want to deal
730 with: if you supply a matrix, it defines the transformation; if you
731 input offset vectors in the "pre" and "post" options, those define
732 the number of dimensions. But if you only supply scalars, there is
733 no way to tell and the default number of dimensions is 2. This pro‐
734 vides a way to do, e.g., 3-D scaling: just set "{s="<scale-factor>,
735 dims=>3}> and you are on your way.
736 NOTES
738 the type/unit fields are currently ignored by t_linear.
740 t_scale
742 $f = t_scale(<scale>)
744 Convenience interface to t_linear.
746 t_scale produces a tranform that scales around the origin by a fixed
748 amount. It acts exactly the same as "t_linear(Scale="\<scale\>)>.
749 t_offset
751 $f = t_offset(<shift>)
753 Convenience interface to t_linear.
755 t_offset produces a transform that shifts the origin to a new location.
757 It acts exactly the same as "t_linear(Pre="\<shift\>)>.
758 t_rot
760 $f = t_rot(<rotation-in-degrees>)
762 Convenience interface to t_linear.
764 t_rot produces a rotation transform in 2-D (scalar), 3-D (3-vector), or
766 N-D (matrix). It acts exactly the same as "t_linear(Rot="\<shift\>)>.
767 t_fits
769 $f = t_fits($fits,[option]);
771 FITS pixel-to-scientific transformation with inverse
773 You feed in a hash ref or a PDL with one of those as a header, and you
775 get back a transform that converts 0-originated, pixel-centered coordi‐
776 nates into scientific coordinates via the transformation in the FITS
777 header. For most FITS headers, the transform is reversible, so apply‐
778 ing the inverse goes the other way. This is just a convenience sub‐
779 class of PDL::Transform::Linear, but with unit/type support using the
780 FITS header you supply.
781 For now, this transform is rather limited -- it really ought to accept
783 units differences and stuff like that, but they are just ignored for
784 now. Probably that would require putting units into the whole trans‐
785 form framework.
786 This transform implements the linear transform part of the WCS FITS
788 standard outlined in Greisen & Calabata 2002 (A&A in press; find it at
789 "http://arxiv.org/abs/astro-ph/0207407").
790 As a special case, you can pass in the boolean option "ignore_rgb"
792 (default 0), and if you pass in a 3-D FITS header in which the last
793 dimension has exactly 3 elements, it will be ignored in the output
794 transformation. That turns out to be handy for handling rgb images.
795 t_code
797 $f = t_code(<func>,[<inv>],[options]);
799 Transform implementing arbitrary perl code.
801 This is a way of getting quick-and-dirty new transforms. You pass in
803 anonymous (or otherwise) code refs pointing to subroutines that imple‐
804 ment the forward and, optionally, inverse transforms. The subroutines
805 should accept a data PDL followed by a parameter hash ref, and return
806 the transformed data PDL. The parameter hash ref can be set via the
807 options, if you want to.
808 Options that are accepted are:
810 p,params
812 The parameter hash that will be passed back to your code (defaults
813 to the empty hash).
814 n,name
816 The name of the transform (defaults to "code").
817 i, idim (default 2)
819 The number of input dimensions (additional ones should be passed
820 through unchanged)
821 o, odim (default 2)
823 The number of output dimensions
824 itype
826 The type of the input dimensions, in an array ref (optional and
827 advisiory)
828 otype
830 The type of the output dimension, in an array ref (optional and
831 advisory)
832 iunit
834 The units that are expected for the input dimensions (optional and
835 advisory)
836 ounit
838 The units that are returned in the output (optional and advisory).
839 The code variables are executable perl code, either as a code ref or as
841 a string that will be eval'ed to produce code refs. If you pass in a
842 string, it gets eval'ed at call time to get a code ref. If it compiles
843 OK but does not return a code ref, then it gets re-evaluated with "sub
844 { ... }" wrapped around it, to get a code ref.
845 Note that code callbacks like this can be used to do really weird
847 things and generate equally weird results -- caveat scriptor!
848 t_cylindrical
850 t_radial
852 $f = t_radial(<options>);
854 Convert Cartesian to radial/cylindrical coordinates. (2-D/3-D; with
856 inverse)
857 Converts 2-D Cartesian to radial (theta,r) coordinates. You can choose
859 direct or conformal conversion. Direct conversion preserves radial
860 distance from the origin; conformal conversion preserves local angles,
861 so that each small-enough part of the image only appears to be scaled
862 and rotated, not stretched. Conformal conversion puts the radius on a
863 logarithmic scale, so that scaling of the original image plane is
864 equivalent to a simple offset of the transformed image plane.
865 If you use three or more dimensions, the higher dimensions are ignored,
867 yielding a conversion from Cartesian to cylindrical coordinates, which
868 is why there are two aliases for the same transform. If you use higher
869 dimensionality than 2, you must manually specify the origin or you will
870 get dimension mismatch errors when you apply the transform.
871 Theta runs clockwise instead of the more usual counterclockwise; that
873 is to preserve the mirror sense of small structures.
874 OPTIONS:
876 d, direct, Direct
878 Generate (theta,r) coordinates out (this is the default); incompati‐
879 ble with Conformal. Theta is in radians, and the radial coordinate
880 is in the units of distance in the input plane.
881 r0, c, conformal, Conformal
883 If defined, this floating-point value causes t_radial to generate
884 (theta, ln(r/r0)) coordinates out. Theta is in radians, and the
885 radial coordinate varies by 1 for each e-folding of the r0-scaled
886 distance from the input origin. The logarithmic scaling is useful
887 for viewing both large and small things at the same time, and for
888 keeping shapes of small things preserved in the image.
889 o, origin, Origin [default (0,0,0)]
891 This is the origin of the expansion. Pass in a PDL or an array ref.
892 u, unit, Unit [default 'radians']
894 This is the angular unit to be used for the azimuth.
895 EXAMPLES
897 These examples do transformations back into the same size image as they
899 started from; by suitable use of the "transform" option to unmap you
900 can send them to any size array you like.
901 Examine radial structure in M51: Here, we scale the output to stretch
903 2*pi radians out to the full image width in the horizontal direction,
904 and to stretch 1 radius out to a diameter in the vertical direction.
905 $a = rfits('m51.fits');
907 $ts = t_linear(s => [250/2.0/3.14159, 2]); # Scale to fill orig. image
908 $tu = t_radial(o => [130,130]); # Expand around galactic core
909 $b = $a->map($ts x $tu);
910 Examine radial structure in M51 (conformal): Here, we scale the output
912 to stretch 2*pi radians out to the full image width in the horizontal
913 direction, and scale the vertical direction by the exact same amount to
914 preserve conformality of the operation. Notice that each piece of the
915 image looks "natural" -- only scaled and not stretched.
916 $a = rfits('m51.fits')
918 $ts = t_linear(s=> 250/2.0/3.14159); # Note scalar (heh) scale.
919 $tu = t_radial(o=> [130,130], r0=>5); # 5 pix. radius -> bottom of image
920 $b = $ts->compose($tu)->unmap($a);
921 t_quadratic
923 $t = t_quadratic(<options>);
925 Quadratic scaling -- cylindrical pincushion (n-d; with inverse)
927 Quadratic scaling emulates pincushion in a cylindrical optical system:
929 separate quadratic scaling is applied to each axis. You can apply sep‐
930 arate distortion along any of the principal axes. If you want differ‐
931 ent axes, use wrap and t_linear to rotate them to the correct angle.
932 The scaling options may be scalars or vectors; if they are scalars then
933 the expansion is isotropic.
934 The formula for the expansion is:
936 f(a) = ( <a> + <strength> * a^2/<L_0> ) / (abs(<strength>) + 1)
938 where <strength> is a scaling coefficient and <L_0> is a fundamental
940 length scale. Negative values of <strength> result in a pincushion
941 contraction.
942 OPTIONS
944 o,origin,Origin
946 The origin of the pincushion. (default is the, er, origin).
947 l,l0,length,Length,r0
949 The fundamental scale of the transformation -- the radius that
950 remains unchanged. (default=1)
951 s,str,strength,Strength
953 The relative strength of the pincushion. (default = 0.1)
954 d, dim, dims, Dims
956 The number of dimensions to quadratically scale (default is the
957 dimensionality of your input vectors)
958 t_spherical
960 $t = t_spherical(<options>);
962 Convert Cartesian to spherical coordinates. (3-D; with inverse)
964 Convert 3-D Cartesian to spherical (theta, phi, r) coordinates. Theta
966 is longitude, centered on 0, and phi is latitude, also centered on 0.
967 Unless you specify Euler angles, the pole points in the +Z direction
968 and the prime meridian is in the +X direction. The default is for
969 theta and phi to be in radians; you can select degrees if you want
970 them.
971 Just as the t_radial 2-D transform acts like a 3-D cylindrical trans‐
973 form by ignoring third and higher dimensions, Spherical acts like a
974 hypercylindrical transform in four (or higher) dimensions. Also as
975 with t_radial, you must manually specify the origin if you want to use
976 more dimensions than 3.
977 To deal with latitude & longitude on the surface of a sphere (rather
979 than full 3-D coordinates), see t_unitsphere.
980 OPTIONS:
982 o, origin, Origin [default (0,0,0)]
984 This is the Cartesian origin of the spherical expansion. Pass in a
985 PDL or an array ref.
986 e, euler, Euler [default (0,0,0)]
988 This is a 3-vector containing Euler angles to change the angle of
989 the pole and ordinate. The first two numbers are the (theta, phi)
990 angles of the pole in a (+Z,+X) spherical expansion, and the last is
991 the angle that the new prime meridian makes with the meridian of a
992 simply tilted sphere. This is implemented by composing the output
993 transform with a PDL::Transform::Linear object.
994 u, unit, Unit (default radians)
996 This option sets the angular unit to be used. Acceptable values are
997 "degrees","radians", or reasonable substrings thereof (e.g. "deg",
998 and "rad", but "d" and "r" are deprecated). Once genuine unit pro‐
999 cessing comes online (a la Math::Units) any angular unit should be
1000 OK.
1001 t_projective
1003 $t = t_projective(<options>);
1005 Projective transformation
1007 Projective transforms are simple quadratic, quasi-linear transforma‐
1009 tions. They are the simplest transformation that can continuously warp
1010 an image plane so that four arbitrarily chosen points exactly map to
1011 four other arbitrarily chosen points. They have the property that
1012 straight lines remain straight after transformation.
1013 You can specify your projective transformation directly in homogeneous
1015 coordinates, or (in 2 dimensions only) as a set of four unique points
1016 that are mapped one to the other by the transformation.
1017 Projective transforms are quasi-linear because they are most easily
1019 described as a linear transformation in homogeneous coordinates (e.g.
1020 (x',y',w) where w is a normalization factor: x = x'/w, etc.). In those
1021 coordinates, an N-D projective transformation is represented as simple
1022 multiplication of an N+1-vector by an N+1 x N+1 matrix, whose lower-
1023 right corner value is 1.
1024 If the bottom row of the matrix consists of all zeroes, then the trans‐
1026 formation reduces to a linear affine transformation (as in t_linear).
1027 If the bottom row of the matrix contains nonzero elements, then the
1029 transformed x,y,z,etc. coordinates are related to the original coordi‐
1030 nates by a quadratic polynomial, because the normalization factor 'w'
1031 allows a second factor of x,y, and/or z to enter the equations.
1032 OPTIONS:
1034 m, mat, matrix, Matrix
1036 If specified, this is the homogeneous-coordinate matrix to use. It
1037 must be N+1 x N+1, for an N-dimensional transformation.
1038 p, point, points, Points
1040 If specified, this is the set of four points that should be mapped
1041 one to the other. The homogeneous-coordinate matrix is calculated
1042 from them. You should feed in a 2x2x4 PDL, where the 0 dimension
1043 runs over coordinate, the 1 dimension runs between input and output,
1044 and the 2 dimension runs over point. For example, specifying
1045 p=> pdl([ [[0,1],[0,1]], [[5,9],[5,8]], [[9,4],[9,3]], [[0,0],[0,0]] ])
1047 maps the origin and the point (0,1) to themselves, the point (5,9)
1049 to (5,8), and the point (9,4) to (9,3).
1050 This is similar to the behavior of fitwarp2d with a quadratic poly‐
1052 nomial.
1053
1055 Copyright 2002, 2003 Craig DeForest. There is no warranty. You are
1056 allowed to redistribute this software under certain conditions. For
1057 details, see the file COPYING in the PDL distribution. If this file is
1058 separated from the PDL distribution, the copyright notice should be
1059 included in the file.
1060perl v5.8.8 2006-12-02 Transform(3)