1Image2D(3) User Contributed Perl Documentation Image2D(3)
2
6 PDL::Image2D - Miscellaneous 2D image processing functions
7
9 Miscellaneous 2D image processing functions - for want of anywhere else
10 to put them.
11
13 use PDL::Image2D;
14
16 conv2d
17 Signature: (a(m,n); kern(p,q); [o]b(m,n); int opt)
18 2D convolution of an array with a kernel (smoothing)
20 For large kernels, using a FFT routine, such as fftconvolve() in
22 "PDL::FFT", will be quicker.
23 $new = conv2d $old, $kernel, {OPTIONS}
25 $smoothed = conv2d $image, ones(3,3), {Boundary => Reflect}
27 Boundary - controls what values are assumed for the image when kernel
29 crosses its edge:
30 => Default - periodic boundary conditions
31 (i.e. wrap around axis)
32 => Reflect - reflect at boundary
33 => Truncate - truncate at boundary
34 => Replicate - repeat boundary pixel values
35 Unlike the FFT routines, conv2d is able to process bad values.
37 med2d
39 Signature: (a(m,n); kern(p,q); [o]b(m,n); double [t]tmp(pq); int opt)
40 2D median-convolution of an array with a kernel (smoothing)
42 Note: only points in the kernel >0 are included in the median, other
44 points are weighted by the kernel value (medianing lots of zeroes is
45 rather pointless)
46 $new = med2d $old, $kernel, {OPTIONS}
48 $smoothed = med2d $image, ones(3,3), {Boundary => Reflect}
50 Boundary - controls what values are assumed for the image when kernel
52 crosses its edge:
53 => Default - periodic boundary conditions (i.e. wrap around axis)
54 => Reflect - reflect at boundary
55 => Truncate - truncate at boundary
56 => Replicate - repeat boundary pixel values
57 Bad values are ignored in the calculation. If all elements within the
59 kernel are bad, the output is set bad.
60 med2df
62 Signature: (a(m,n); [o]b(m,n); int __p_size; int __q_size; int opt)
63 2D median-convolution of an array in a pxq window (smoothing)
65 Note: this routine does the median over all points in a rectangular
67 window and is not quite as flexible as "med2d" in this regard
68 but slightly faster instead
69 $new = med2df $old, $xwidth, $ywidth, {OPTIONS}
71 $smoothed = med2df $image, 3, 3, {Boundary => Reflect}
73 Boundary - controls what values are assumed for the image when kernel
75 crosses its edge:
76 => Default - periodic boundary conditions (i.e. wrap around axis)
77 => Reflect - reflect at boundary
78 => Truncate - truncate at boundary
79 => Replicate - repeat boundary pixel values
80 med2df does not process bad values. It will set the bad-value flag of
82 all output ndarrays if the flag is set for any of the input ndarrays.
83 box2d
85 Signature: (a(n,m); [o] b(n,m); int wx; int wy; int edgezero)
86 fast 2D boxcar average
88 $smoothim = $im->box2d($wx,$wy,$edgezero=1);
90 The edgezero argument controls if edge is set to zero (edgezero=1) or
92 just keeps the original (unfiltered) values.
93 "box2d" should be updated to support similar edge options as "conv2d"
95 and "med2d" etc.
96 Boxcar averaging is a pretty crude way of filtering. For serious stuff
98 better filters are around (e.g., use "conv2d" with the appropriate
99 kernel). On the other hand it is fast and computational cost grows only
100 approximately linearly with window size.
101 box2d does not process bad values. It will set the bad-value flag of
103 all output ndarrays if the flag is set for any of the input ndarrays.
104 patch2d
106 Signature: (a(m,n); int bad(m,n); [o]b(m,n))
107 patch bad pixels out of 2D images using a mask
109 $patched = patch2d $data, $bad;
111 $bad is a 2D mask array where 1=bad pixel 0=good pixel. Pixels are
113 replaced by the average of their non-bad neighbours; if all neighbours
114 are bad, the original data value is copied across.
115 This routine does not handle bad values - use "patchbad2d" instead
117 patchbad2d
119 Signature: (a(m,n); [o]b(m,n))
120 patch bad pixels out of 2D images containing bad values
122 $patched = patchbad2d $data;
124 Pixels are replaced by the average of their non-bad neighbours; if all
126 neighbours are bad, the output is set bad. If the input ndarray
127 contains no bad values, then a straight copy is performed (see
128 "patch2d").
129 patchbad2d handles bad values. The output ndarray may contain bad
131 values, depending on the pattern of bad values in the input ndarray.
132 max2d_ind
134 Signature: (a(m,n); [o]val(); int [o]x(); int[o]y())
135 Return value/position of maximum value in 2D image
137 Contributed by Tim Jeness
139 Bad values are excluded from the search. If all pixels are bad then the
141 output is set bad.
142 centroid2d
144 Signature: (im(m,n); x(); y(); box(); [o]xcen(); [o]ycen())
145 Refine a list of object positions in 2D image by centroiding in a box
147 $box is the full-width of the box, i.e. the window is "+/- $box/2".
149 Bad pixels are excluded from the centroid calculation. If all elements
151 are bad (or the pixel sum is 0 - but why would you be centroiding
152 something with negatives in...) then the output values are set bad.
153 crop
155 Return bounding box of given mask in an "indx" ndarray, so it can
156 broadcast. Use other operations (such as "isgood" in PDL::Bad, or
157 "eqvec" in PDL::Primitive with a colour vector) to create a mask
158 suitable for your application.
159 $x1x2y1y2 = crop($image);
161 cc8compt
163 Connected 8-component labeling of a binary image.
164 Connected 8-component labeling of 0,1 image - i.e. find separate
166 segmented objects and fill object pixels with object number.
167 8-component labeling includes all neighboring pixels. This is just a
168 front-end to ccNcompt. See also "cc4compt".
169 $segmented = cc8compt( $image > $threshold );
171 cc4compt
173 Connected 4-component labeling of a binary image.
174 Connected 4-component labeling of 0,1 image - i.e. find separate
176 segmented objects and fill object pixels with object number.
177 4-component labling does not include the diagonal neighbors. This is
178 just a front-end to ccNcompt. See also "cc8compt".
179 $segmented = cc4compt( $image > $threshold );
181 ccNcompt
183 Signature: (a(m,n); int+ [o]b(m,n); int con)
184 Connected component labeling of a binary image.
186 Connected component labeling of 0,1 image - i.e. find separate
188 segmented objects and fill object pixels with object number. See also
189 "cc4compt" and "cc8compt".
190 The connectivity parameter must be 4 or 8.
192 $segmented = ccNcompt( $image > $threshold, 4);
194 $segmented2 = ccNcompt( $image > $threshold, 8);
196 where the second parameter specifies the connectivity (4 or 8) of the
198 labeling.
199 ccNcompt ignores the bad-value flag of the input ndarrays. It will set
201 the bad-value flag of all output ndarrays if the flag is set for any of
202 the input ndarrays.
203 polyfill
205 fill the area of the given polygon with the given colour.
206 This function works inplace, i.e. modifies "im".
208 polyfill($im,$ps,$colour,[\%options]);
210 The default method of determining which points lie inside of the
212 polygon used is not as strict as the method used in "pnpoly". Often, it
213 includes vertices and edge points. Set the "Method" option to change
214 this behaviour.
215 Method - Set the method used to determine which points lie in the
217 polygon.
218 => Default - internal PDL algorithm
219 => pnpoly - use the "pnpoly" algorithm
220 # Make a convex 3x3 square of 1s in an image using the pnpoly algorithm
222 $ps = pdl([3,3],[3,6],[6,6],[6,3]);
223 polyfill($im,$ps,1,{'Method' =>'pnpoly'});
224 pnpoly
226 'points in a polygon' selection from a 2-D ndarray
227 $mask = $img->pnpoly($ps);
229 # Old style, do not use
231 $mask = pnpoly($x, $y, $px, $py);
232 For a closed polygon determined by the sequence of points in {$px,$py}
234 the output of pnpoly is a mask corresponding to whether or not each
235 coordinate (x,y) in the set of test points, {$x,$y}, is in the interior
236 of the polygon. This is the 'points in a polygon' algorithm from
237 <http://www.ecse.rpi.edu/Homepages/wrf/Research/Short_Notes/pnpoly.html>
238 and vectorized for PDL by Karl Glazebrook.
239 # define a 3-sided polygon (a triangle)
241 $ps = pdl([3, 3], [20, 20], [34, 3]);
242 # $tri is 0 everywhere except for points in polygon interior
244 $tri = $img->pnpoly($ps);
245 With the second form, the x and y coordinates must also be specified.
247 B< I<THIS IS MAINTAINED FOR BACKWARD COMPATIBILITY ONLY> >.
248 $px = pdl( 3, 20, 34 );
250 $py = pdl( 3, 20, 3 );
251 $x = $img->xvals; # get x pixel coords
252 $y = $img->yvals; # get y pixel coords
253 # $tri is 0 everywhere except for points in polygon interior
255 $tri = pnpoly($x,$y,$px,$py);
256 polyfillv
258 return the (dataflowed) area of an image described by a polygon
259 polyfillv($im,$ps,[\%options]);
261 The default method of determining which points lie inside of the
263 polygon used is not as strict as the method used in "pnpoly". Often, it
264 includes vertices and edge points. Set the "Method" option to change
265 this behaviour.
266 Method - Set the method used to determine which points lie in the
268 polygon.
269 => Default - internal PDL algorithm
270 => pnpoly - use the "pnpoly" algorithm
271 # increment intensity in area bounded by $poly using the pnpoly algorithm
273 $im->polyfillv($poly,{'Method'=>'pnpoly'})++; # legal in perl >= 5.6
274 # compute average intensity within area bounded by $poly using the default algorithm
276 $av = $im->polyfillv($poly)->avg;
277 rot2d
279 Signature: (im(m,n); float angle(); bg(); int aa(); [o] om(p,q))
280 rotate an image by given "angle"
282 # rotate by 10.5 degrees with antialiasing, set missing values to 7
284 $rot = $im->rot2d(10.5,7,1);
285 This function rotates an image through an "angle" between -90 and + 90
287 degrees. Uses/doesn't use antialiasing depending on the "aa" flag.
288 Pixels outside the rotated image are set to "bg".
289 Code modified from pnmrotate (Copyright Jef Poskanzer) with an
291 algorithm based on "A Fast Algorithm for General Raster Rotation" by
292 Alan Paeth, Graphics Interface '86, pp. 77-81.
293 Use the "rotnewsz" function to find out about the dimension of the
295 newly created image
296 ($newcols,$newrows) = rotnewsz $oldn, $oldm, $angle;
298 PDL::Transform offers a more general interface to distortions,
300 including rotation, with various types of sampling; but rot2d is
301 faster.
302 rot2d ignores the bad-value flag of the input ndarrays. It will set
304 the bad-value flag of all output ndarrays if the flag is set for any of
305 the input ndarrays.
306 bilin2d
308 Signature: (Int(n,m); O(q,p))
309 Bilinearly maps the first ndarray in the second. The interpolated
311 values are actually added to the second ndarray which is supposed to be
312 larger than the first one.
313 bilin2d ignores the bad-value flag of the input ndarrays. It will set
315 the bad-value flag of all output ndarrays if the flag is set for any of
316 the input ndarrays.
317 rescale2d
319 Signature: (Int(m,n); O(p,q))
320 The first ndarray is rescaled to the dimensions of the second
322 (expanding or meaning values as needed) and then added to it in place.
323 Nothing useful is returned.
324 If you want photometric accuracy or automatic FITS header metadata
326 tracking, consider using PDL::Transform::map instead: it does these
327 things, at some speed penalty compared to rescale2d.
328 rescale2d ignores the bad-value flag of the input ndarrays. It will
330 set the bad-value flag of all output ndarrays if the flag is set for
331 any of the input ndarrays.
332 fitwarp2d
334 Find the best-fit 2D polynomial to describe a coordinate
335 transformation.
336 ( $px, $py ) = fitwarp2d( $x, $y, $u, $v, $nf, { options } )
338 Given a set of points in the output plane ("$u,$v"), find the best-fit
340 (using singular-value decomposition) 2D polynomial to describe the
341 mapping back to the image plane ("$x,$y"). The order of the fit is
342 controlled by the $nf parameter (the maximum power of the polynomial is
343 "$nf - 1"), and you can restrict the terms to fit using the "FIT"
344 option.
345 $px and $py are "np" by "np" element ndarrays which describe a
347 polynomial mapping (of order "np-1") from the output "(u,v)" image to
348 the input "(x,y)" image:
349 x = sum(j=0,np-1) sum(i=0,np-1) px(i,j) * u^i * v^j
351 y = sum(j=0,np-1) sum(i=0,np-1) py(i,j) * u^i * v^j
352 The transformation is returned for the reverse direction (ie output to
354 input image) since that is what is required by the warp2d() routine.
355 The applywarp2d() routine can be used to convert a set of "$u,$v"
356 points given $px and $py.
357 Options:
359 FIT - which terms to fit? default ones(byte,$nf,$nf)
361 FIT "FIT" allows you to restrict which terms of the polynomial to fit:
363 only those terms for which the FIT ndarray evaluates to true will
364 be evaluated. If a 2D ndarray is sent in, then it is used for the
365 x and y polynomials; otherwise "$fit->slice(":,:,(0)")" will be
366 used for $px and "$fit->slice(":,:,(1)")" will be used for $py.
367 The number of points must be at least equal to the number of terms to
369 fit ("$nf*$nf" points for the default value of "FIT").
370 # points in original image
372 $x = pdl( 0, 0, 100, 100 );
373 $y = pdl( 0, 100, 100, 0 );
374 # get warped to these positions
375 $u = pdl( 10, 10, 90, 90 );
376 $v = pdl( 10, 90, 90, 10 );
377 #
378 # shift of origin + scale x/y axis only
379 $fit = byte( [ [1,1], [0,0] ], [ [1,0], [1,0] ] );
380 ( $px, $py ) = fitwarp2d( $x, $y, $u, $v, 2, { FIT => $fit } );
381 print "px = ${px}py = $py";
382 px =
383 [
384 [-12.5 1.25]
385 [ 0 0]
386 ]
387 py =
388 [
389 [-12.5 0]
390 [ 1.25 0]
391 ]
392 #
393 # Compared to allowing all 4 terms
394 ( $px, $py ) = fitwarp2d( $x, $y, $u, $v, 2 );
395 print "px = ${px}py = $py";
396 px =
397 [
398 [ -12.5 1.25]
399 [ 1.110223e-16 -1.1275703e-17]
400 ]
401 py =
402 [
403 [ -12.5 1.6653345e-16]
404 [ 1.25 -5.8546917e-18]
405 ]
406 # A higher-degree polynomial should not affect the answer much, but
408 # will require more control points
409 $x = $x->glue(0,pdl(50,12.5, 37.5, 12.5, 37.5));
411 $y = $y->glue(0,pdl(50,12.5, 37.5, 37.5, 12.5));
412 $u = $u->glue(0,pdl(73,20,40,20,40));
413 $v = $v->glue(0,pdl(29,20,40,40,20));
414 ( $px3, $py3 ) = fitwarp2d( $x, $y, $u, $v, 3 );
415 print "px3 =${px3}py3 =$py3";
416 px3 =
417 [
418 [-6.4981162e+08 71034917 -726498.95]
419 [ 49902244 -5415096.7 55945.388]
420 [ -807778.46 88457.191 -902.51612]
421 ]
422 py3 =
423 [
424 [-6.2732159e+08 68576392 -701354.77]
425 [ 48175125 -5227679.8 54009.114]
426 [ -779821.18 85395.681 -871.27997]
427 ]
428 #This illustrates an important point about singular value
430 #decompositions that are used in fitwarp2d: like all SVDs, the
431 #rotation matrices are not unique, and so the $px and $py returned
432 #by fitwarp2d are not guaranteed to be the "simplest" solution.
433 #They do still work, though:
434 ($x3,$y3) = applywarp2d($px3,$py3,$u,$v);
436 print approx $x3,$x,1e-4;
437 [1 1 1 1 1 1 1 1 1]
438 print approx $y3,$y;
439 [1 1 1 1 1 1 1 1 1]
440 applywarp2d
442 Transform a set of points using a 2-D polynomial mapping
443 ( $x, $y ) = applywarp2d( $px, $py, $u, $v )
445 Convert a set of points (stored in 1D ndarrays "$u,$v") to "$x,$y"
447 using the 2-D polynomial with coefficients stored in $px and $py. See
448 fitwarp2d() for more information on the format of $px and $py.
449 warp2d
451 Signature: (img(m,n); double px(np,np); double py(np,np); [o] warp(m,n); { options })
452 Warp a 2D image given a polynomial describing the reverse mapping.
454 $out = warp2d( $img, $px, $py, { options } );
456 Apply the polynomial transformation encoded in the $px and $py ndarrays
458 to warp the input image $img into the output image $out.
459 The format for the polynomial transformation is described in the
461 documentation for the fitwarp2d() routine.
462 At each point "x,y", the closest 16 pixel values are combined with an
464 interpolation kernel to calculate the value at "u,v". The
465 interpolation is therefore done in the image, rather than Fourier,
466 domain. By default, a "tanh" kernel is used, but this can be changed
467 using the "KERNEL" option discussed below (the choice of kernel depends
468 on the frequency content of the input image).
469 The routine is based on the "warping" command from the Eclipse data-
471 reduction package - see http://www.eso.org/eclipse/ - and for further
472 details on image resampling see Wolberg, G., "Digital Image Warping",
473 1990, IEEE Computer Society Press ISBN 0-8186-8944-7).
474 Currently the output image is the same size as the input one, which
476 means data will be lost if the transformation reduces the pixel scale.
477 This will (hopefully) be changed soon.
478 $img = rvals(byte,501,501);
480 imag $img, { JUSTIFY => 1 };
481 #
482 # use a not-particularly-obvious transformation:
483 # x = -10 + 0.5 * $u - 0.1 * $v
484 # y = -20 + $v - 0.002 * $u * $v
485 #
486 $px = pdl( [ -10, 0.5 ], [ -0.1, 0 ] );
487 $py = pdl( [ -20, 0 ], [ 1, 0.002 ] );
488 $wrp = warp2d( $img, $px, $py );
489 #
490 # see the warped image
491 imag $warp, { JUSTIFY => 1 };
492 The options are:
494 KERNEL - default value is tanh
496 NOVAL - default value is 0
497 "KERNEL" is used to specify which interpolation kernel to use (to see
499 what these kernels look like, use the warp2d_kernel() routine). The
500 options are:
501 tanh
503 Hyperbolic tangent: the approximation of an ideal box filter by the
504 product of symmetric tanh functions.
505 sinc
507 For a correctly sampled signal, the ideal filter in the fourier
508 domain is a rectangle, which produces a "sinc" interpolation kernel
509 in the spatial domain:
510 sinc(x) = sin(pi * x) / (pi * x)
512 However, it is not ideal for the "4x4" pixel region used here.
514 sinc2
516 This is the square of the sinc function.
517 lanczos
519 Although defined differently to the "tanh" kernel, the result is
520 very similar in the spatial domain. The Lanczos function is
521 defined as
522 L(x) = sinc(x) * sinc(x/2) if abs(x) < 2
524 = 0 otherwise
525 hann
527 This kernel is derived from the following function:
528 H(x) = a + (1-a) * cos(2*pi*x/(N-1)) if abs(x) < 0.5*(N-1)
530 = 0 otherwise
531 with "a = 0.5" and N currently equal to 2001.
533 hamming
535 This kernel uses the same H(x) as the Hann filter, but with "a =
536 0.54".
537 "NOVAL" gives the value used to indicate that a pixel in the output
539 image does not map onto one in the input image.
540 warp2d_kernel
542 Return the specified kernel, as used by "warp2d"
543 ( $x, $k ) = warp2d_kernel( $name )
545 The valid values for $name are the same as the "KERNEL" option of
547 warp2d().
548 line warp2d_kernel( "hamming" );
550
552 Copyright (C) Karl Glazebrook 1997 with additions by Robin Williams
553 (rjrw@ast.leeds.ac.uk), Tim Jeness (timj@jach.hawaii.edu), and Doug
554 Burke (burke@ifa.hawaii.edu).
555 All rights reserved. There is no warranty. You are allowed to
557 redistribute this software / documentation under certain conditions.
558 For details, see the file COPYING in the PDL distribution. If this file
559 is separated from the PDL distribution, the copyright notice should be
560 included in the file.
561perl v5.36.0 2022-07-22 Image2D(3)