1Image2D(3) User Contributed Perl Documentation Image2D(3)
2
3
4
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
19 2D convolution of an array with a kernel (smoothing)
20
21 For large kernels, using a FFT routine, such as fftconvolve() in
22 "PDL::FFT", will be quicker.
23
24 $new = conv2d $old, $kernel, {OPTIONS}
25
26 $smoothed = conv2d $image, ones(3,3), {Boundary => Reflect}
27
28 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
36 Unlike the FFT routines, conv2d is able to process bad values.
37
38 med2d
39 Signature: (a(m,n); kern(p,q); [o]b(m,n); int opt)
40
41 2D median-convolution of an array with a kernel (smoothing)
42
43 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
47 $new = med2d $old, $kernel, {OPTIONS}
48
49 $smoothed = med2d $image, ones(3,3), {Boundary => Reflect}
50
51 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
58 Bad values are ignored in the calculation. If all elements within the
59 kernel are bad, the output is set bad.
60
61 med2df
62 Signature: (a(m,n); [o]b(m,n); int __p_size; int __q_size; int opt)
63
64 2D median-convolution of an array in a pxq window (smoothing)
65
66 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
70 $new = med2df $old, $xwidth, $ywidth, {OPTIONS}
71
72 $smoothed = med2df $image, 3, 3, {Boundary => Reflect}
73
74 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
81 med2df does not process bad values. It will set the bad-value flag of
82 all output piddles if the flag is set for any of the input piddles.
83
84 box2d
85 Signature: (a(n,m); [o] b(n,m); int wx; int wy; int edgezero)
86
87 fast 2D boxcar average
88
89 $smoothim = $im->box2d($wx,$wy,$edgezero=1);
90
91 The edgezero argument controls if edge is set to zero (edgezero=1) or
92 just keeps the original (unfiltered) values.
93
94 "box2d" should be updated to support similar edge options as "conv2d"
95 and "med2d" etc.
96
97 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
102 box2d does not process bad values. It will set the bad-value flag of
103 all output piddles if the flag is set for any of the input piddles.
104
105 patch2d
106 Signature: (a(m,n); int bad(m,n); [o]b(m,n))
107
108 patch bad pixels out of 2D images using a mask
109
110 $patched = patch2d $data, $bad;
111
112 $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
116 This routine does not handle bad values - use patchbad2d instead
117
118 patchbad2d
119 Signature: (a(m,n); [o]b(m,n))
120
121 patch bad pixels out of 2D images containing bad values
122
123 $patched = patchbad2d $data;
124
125 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 piddle
127 contains no bad values, then a straight copy is performed (see
128 patch2d).
129
130 patchbad2d handles bad values. The output piddle may contain bad
131 values, depending on the pattern of bad values in the input piddle.
132
133 max2d_ind
134 Signature: (a(m,n); [o]val(); int [o]x(); int[o]y())
135
136 Return value/position of maximum value in 2D image
137
138 Contributed by Tim Jeness
139
140 Bad values are excluded from the search. If all pixels are bad then the
141 output is set bad.
142
143 centroid2d
144 Signature: (im(m,n); x(); y(); box(); [o]xcen(); [o]ycen())
145
146 Refine a list of object positions in 2D image by centroiding in a box
147
148 $box is the full-width of the box, i.e. the window is "+/- $box/2".
149
150 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
154 cc8compt
155 Connected 8-component labeling of a binary image.
156
157 Connected 8-component labeling of 0,1 image - i.e. find separate
158 segmented objects and fill object pixels with object number.
159 8-component labeling includes all neighboring pixels. This is just a
160 front-end to ccNcompt. See also cc4compt.
161
162 $segmented = cc8compt( $image > $threshold );
163
164 cc4compt
165 Connected 4-component labeling of a binary image.
166
167 Connected 4-component labeling of 0,1 image - i.e. find separate
168 segmented objects and fill object pixels with object number.
169 4-component labling does not include the diagonal neighbors. This is
170 just a front-end to ccNcompt. See also cc8compt.
171
172 $segmented = cc4compt( $image > $threshold );
173
174 ccNcompt
175 Signature: (a(m,n); int+ [o]b(m,n); int con)
176
177 Connected component labeling of a binary image.
178
179 Connected component labeling of 0,1 image - i.e. find separate
180 segmented objects and fill object pixels with object number. See also
181 cc4compt and cc8compt.
182
183 The connectivity parameter must be 4 or 8.
184
185 $segmented = ccNcompt( $image > $threshold, 4);
186
187 $segmented2 = ccNcompt( $image > $threshold, 8);
188
189 where the second parameter specifies the connectivity (4 or 8) of the
190 labeling.
191
192 ccNcompt ignores the bad-value flag of the input piddles. It will set
193 the bad-value flag of all output piddles if the flag is set for any of
194 the input piddles.
195
196 polyfill
197 fill the area of the given polygon with the given colour.
198
199 This function works inplace, i.e. modifies "im".
200
201 polyfill($im,$ps,$colour,[\%options]);
202
203 The default method of determining which points lie inside of the
204 polygon used is not as strict as the method used in pnpoly. Often, it
205 includes vertices and edge points. Set the "Method" option to change
206 this behaviour.
207
208 Method - Set the method used to determine which points lie in the
209 polygon.
210 => Default - internal PDL algorithm
211 => pnpoly - use the pnpoly algorithm
212
213 # Make a convex 3x3 square of 1s in an image using the pnpoly algorithm
214 $ps = pdl([3,3],[3,6],[6,6],[6,3]);
215 polyfill($im,$ps,1,{'Method' =>'pnpoly'});
216
217 pnpoly
218 'points in a polygon' selection from a 2-D piddle
219
220 $mask = $img->pnpoly($ps);
221
222 # Old style, do not use
223 $mask = pnpoly($x, $y, $px, $py);
224
225 For a closed polygon determined by the sequence of points in {$px,$py}
226 the output of pnpoly is a mask corresponding to whether or not each
227 coordinate (x,y) in the set of test points, {$x,$y}, is in the interior
228 of the polygon. This is the 'points in a polygon' algorithm from
229 <http://www.ecse.rpi.edu/Homepages/wrf/Research/Short_Notes/pnpoly.html>
230 and vectorized for PDL by Karl Glazebrook.
231
232 # define a 3-sided polygon (a triangle)
233 $ps = pdl([3, 3], [20, 20], [34, 3]);
234
235 # $tri is 0 everywhere except for points in polygon interior
236 $tri = $img->pnpoly($ps);
237
238 With the second form, the x and y coordinates must also be specified.
239 B< I<THIS IS MAINTAINED FOR BACKWARD COMPATIBILITY ONLY> >.
240
241 $px = pdl( 3, 20, 34 );
242 $py = pdl( 3, 20, 3 );
243 $x = $img->xvals; # get x pixel coords
244 $y = $img->yvals; # get y pixel coords
245
246 # $tri is 0 everywhere except for points in polygon interior
247 $tri = pnpoly($x,$y,$px,$py);
248
249 polyfillv
250 return the (dataflown) area of an image described by a polygon
251
252 polyfillv($im,$ps,[\%options]);
253
254 The default method of determining which points lie inside of the
255 polygon used is not as strict as the method used in pnpoly. Often, it
256 includes vertices and edge points. Set the "Method" option to change
257 this behaviour.
258
259 Method - Set the method used to determine which points lie in the
260 polygon.
261 => Default - internal PDL algorithm
262 => pnpoly - use the pnpoly algorithm
263
264 # increment intensity in area bounded by $poly using the pnpoly algorithm
265 $im->polyfillv($poly,{'Method'=>'pnpoly'})++; # legal in perl >= 5.6
266
267 # compute average intensity within area bounded by $poly using the default algorithm
268 $av = $im->polyfillv($poly)->avg;
269
270 rot2d
271 Signature: (im(m,n); float angle(); bg(); int aa(); [o] om(p,q))
272
273 rotate an image by given "angle"
274
275 # rotate by 10.5 degrees with antialiasing, set missing values to 7
276 $rot = $im->rot2d(10.5,7,1);
277
278 This function rotates an image through an "angle" between -90 and + 90
279 degrees. Uses/doesn't use antialiasing depending on the "aa" flag.
280 Pixels outside the rotated image are set to "bg".
281
282 Code modified from pnmrotate (Copyright Jef Poskanzer) with an
283 algorithm based on "A Fast Algorithm for General Raster Rotation" by
284 Alan Paeth, Graphics Interface '86, pp. 77-81.
285
286 Use the "rotnewsz" function to find out about the dimension of the
287 newly created image
288
289 ($newcols,$newrows) = rotnewsz $oldn, $oldm, $angle;
290
291 PDL::Transform offers a more general interface to distortions,
292 including rotation, with various types of sampling; but rot2d is
293 faster.
294
295 rot2d ignores the bad-value flag of the input piddles. It will set the
296 bad-value flag of all output piddles if the flag is set for any of the
297 input piddles.
298
299 bilin2d
300 Signature: (I(n,m); O(q,p))
301
302 Bilinearly maps the first piddle in the second. The interpolated values
303 are actually added to the second piddle which is supposed to be larger
304 than the first one.
305
306 bilin2d ignores the bad-value flag of the input piddles. It will set
307 the bad-value flag of all output piddles if the flag is set for any of
308 the input piddles.
309
310 rescale2d
311 Signature: (I(m,n); O(p,q))
312
313 The first piddle is rescaled to the dimensions of the second (expanding
314 or meaning values as needed) and then added to it in place. Nothing
315 useful is returned.
316
317 If you want photometric accuracy or automatic FITS header metadata
318 tracking, consider using PDL::Transform::map instead: it does these
319 things, at some speed penalty compared to rescale2d.
320
321 rescale2d ignores the bad-value flag of the input piddles. It will set
322 the bad-value flag of all output piddles if the flag is set for any of
323 the input piddles.
324
325 fitwarp2d
326 Find the best-fit 2D polynomial to describe a coordinate
327 transformation.
328
329 ( $px, $py ) = fitwarp2d( $x, $y, $u, $v, $nf, { options } )
330
331 Given a set of points in the output plane ("$u,$v"), find the best-fit
332 (using singular-value decomposition) 2D polynomial to describe the
333 mapping back to the image plane ("$x,$y"). The order of the fit is
334 controlled by the $nf parameter (the maximum power of the polynomial is
335 "$nf - 1"), and you can restrict the terms to fit using the "FIT"
336 option.
337
338 $px and $py are "np" by "np" element piddles which describe a
339 polynomial mapping (of order "np-1") from the output "(u,v)" image to
340 the input "(x,y)" image:
341
342 x = sum(j=0,np-1) sum(i=0,np-1) px(i,j) * u^i * v^j
343 y = sum(j=0,np-1) sum(i=0,np-1) py(i,j) * u^i * v^j
344
345 The transformation is returned for the reverse direction (ie output to
346 input image) since that is what is required by the warp2d() routine.
347 The applywarp2d() routine can be used to convert a set of "$u,$v"
348 points given $px and $py.
349
350 Options:
351
352 FIT - which terms to fit? default ones(byte,$nf,$nf)
353
354 FIT "FIT" allows you to restrict which terms of the polynomial to fit:
355 only those terms for which the FIT piddle evaluates to true will be
356 evaluated. If a 2D piddle is sent in, then it is used for the x
357 and y polynomials; otherwise "$fit->slice(":,:,(0)")" will be used
358 for $px and "$fit->slice(":,:,(1)")" will be used for $py.
359
360 The number of points must be at least equal to the number of terms to
361 fit ("$nf*$nf" points for the default value of "FIT").
362
363 # points in original image
364 $x = pdl( 0, 0, 100, 100 );
365 $y = pdl( 0, 100, 100, 0 );
366 # get warped to these positions
367 $u = pdl( 10, 10, 90, 90 );
368 $v = pdl( 10, 90, 90, 10 );
369 #
370 # shift of origin + scale x/y axis only
371 $fit = byte( [ [1,1], [0,0] ], [ [1,0], [1,0] ] );
372 ( $px, $py ) = fitwarp2d( $x, $y, $u, $v, 2, { FIT => $fit } );
373 print "px = ${px}py = $py";
374 px =
375 [
376 [-12.5 1.25]
377 [ 0 0]
378 ]
379 py =
380 [
381 [-12.5 0]
382 [ 1.25 0]
383 ]
384 #
385 # Compared to allowing all 4 terms
386 ( $px, $py ) = fitwarp2d( $x, $y, $u, $v, 2 );
387 print "px = ${px}py = $py";
388 px =
389 [
390 [ -12.5 1.25]
391 [ 1.110223e-16 -1.1275703e-17]
392 ]
393 py =
394 [
395 [ -12.5 1.6653345e-16]
396 [ 1.25 -5.8546917e-18]
397 ]
398
399 # A higher-degree polynomial should not affect the answer much, but
400 # will require more control points
401
402 $x = $x->glue(0,pdl(50,12.5, 37.5, 12.5, 37.5));
403 $y = $y->glue(0,pdl(50,12.5, 37.5, 37.5, 12.5));
404 $u = $u->glue(0,pdl(73,20,40,20,40));
405 $v = $v->glue(0,pdl(29,20,40,40,20));
406 ( $px3, $py3 ) = fitwarp2d( $x, $y, $u, $v, 3 );
407 print "px3 =${px3}py3 =$py3";
408 px3 =
409 [
410 [-6.4981162e+08 71034917 -726498.95]
411 [ 49902244 -5415096.7 55945.388]
412 [ -807778.46 88457.191 -902.51612]
413 ]
414 py3 =
415 [
416 [-6.2732159e+08 68576392 -701354.77]
417 [ 48175125 -5227679.8 54009.114]
418 [ -779821.18 85395.681 -871.27997]
419 ]
420
421 #This illustrates an important point about singular value
422 #decompositions that are used in fitwarp2d: like all SVDs, the
423 #rotation matrices are not unique, and so the $px and $py returned
424 #by fitwarp2d are not guaranteed to be the "simplest" solution.
425 #They do still work, though:
426
427 ($x3,$y3) = applywarp2d($px3,$py3,$u,$v);
428 print approx $x3,$x,1e-4;
429 [1 1 1 1 1 1 1 1 1]
430 print approx $y3,$y;
431 [1 1 1 1 1 1 1 1 1]
432
433 applywarp2d
434 Transform a set of points using a 2-D polynomial mapping
435
436 ( $x, $y ) = applywarp2d( $px, $py, $u, $v )
437
438 Convert a set of points (stored in 1D piddles "$u,$v") to "$x,$y" using
439 the 2-D polynomial with coefficients stored in $px and $py. See
440 fitwarp2d() for more information on the format of $px and $py.
441
442 warp2d
443 Signature: (img(m,n); double px(np,np); double py(np,np); [o] warp(m,n); { options })
444
445 Warp a 2D image given a polynomial describing the reverse mapping.
446
447 $out = warp2d( $img, $px, $py, { options } );
448
449 Apply the polynomial transformation encoded in the $px and $py piddles
450 to warp the input image $img into the output image $out.
451
452 The format for the polynomial transformation is described in the
453 documentation for the fitwarp2d() routine.
454
455 At each point "x,y", the closest 16 pixel values are combined with an
456 interpolation kernel to calculate the value at "u,v". The
457 interpolation is therefore done in the image, rather than Fourier,
458 domain. By default, a "tanh" kernel is used, but this can be changed
459 using the "KERNEL" option discussed below (the choice of kernel depends
460 on the frequency content of the input image).
461
462 The routine is based on the "warping" command from the Eclipse data-
463 reduction package - see http://www.eso.org/eclipse/ - and for further
464 details on image resampling see Wolberg, G., "Digital Image Warping",
465 1990, IEEE Computer Society Press ISBN 0-8186-8944-7).
466
467 Currently the output image is the same size as the input one, which
468 means data will be lost if the transformation reduces the pixel scale.
469 This will (hopefully) be changed soon.
470
471 $img = rvals(byte,501,501);
472 imag $img, { JUSTIFY => 1 };
473 #
474 # use a not-particularly-obvious transformation:
475 # x = -10 + 0.5 * $u - 0.1 * $v
476 # y = -20 + $v - 0.002 * $u * $v
477 #
478 $px = pdl( [ -10, 0.5 ], [ -0.1, 0 ] );
479 $py = pdl( [ -20, 0 ], [ 1, 0.002 ] );
480 $wrp = warp2d( $img, $px, $py );
481 #
482 # see the warped image
483 imag $warp, { JUSTIFY => 1 };
484
485 The options are:
486
487 KERNEL - default value is tanh
488 NOVAL - default value is 0
489
490 "KERNEL" is used to specify which interpolation kernel to use (to see
491 what these kernels look like, use the warp2d_kernel() routine). The
492 options are:
493
494 tanh
495 Hyperbolic tangent: the approximation of an ideal box filter by the
496 product of symmetric tanh functions.
497
498 sinc
499 For a correctly sampled signal, the ideal filter in the fourier
500 domain is a rectangle, which produces a "sinc" interpolation kernel
501 in the spatial domain:
502
503 sinc(x) = sin(pi * x) / (pi * x)
504
505 However, it is not ideal for the "4x4" pixel region used here.
506
507 sinc2
508 This is the square of the sinc function.
509
510 lanczos
511 Although defined differently to the "tanh" kernel, the result is
512 very similar in the spatial domain. The Lanczos function is
513 defined as
514
515 L(x) = sinc(x) * sinc(x/2) if abs(x) < 2
516 = 0 otherwise
517
518 hann
519 This kernel is derived from the following function:
520
521 H(x) = a + (1-a) * cos(2*pi*x/(N-1)) if abs(x) < 0.5*(N-1)
522 = 0 otherwise
523
524 with "a = 0.5" and N currently equal to 2001.
525
526 hamming
527 This kernel uses the same H(x) as the Hann filter, but with "a =
528 0.54".
529
530 "NOVAL" gives the value used to indicate that a pixel in the output
531 image does not map onto one in the input image.
532
533 warp2d_kernel
534 Return the specified kernel, as used by warp2d
535
536 ( $x, $k ) = warp2d_kernel( $name )
537
538 The valid values for $name are the same as the "KERNEL" option of
539 warp2d().
540
541 line warp2d_kernel( "hamming" );
542
544 Copyright (C) Karl Glazebrook 1997 with additions by Robin Williams
545 (rjrw@ast.leeds.ac.uk), Tim Jeness (timj@jach.hawaii.edu), and Doug
546 Burke (burke@ifa.hawaii.edu).
547
548 All rights reserved. There is no warranty. You are allowed to
549 redistribute this software / documentation under certain conditions.
550 For details, see the file COPYING in the PDL distribution. If this file
551 is separated from the PDL distribution, the copyright notice should be
552 included in the file.
553
554
555
556perl v5.28.1 2019-02-14 Image2D(3)