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 Unlike the FFT routines, conv2d is able to process bad values.
36 med2d
38 Signature: (a(m,n); kern(p,q); [o]b(m,n); int opt)
39 2D median-convolution of an array with a kernel (smoothing)
41 Note: only points in the kernel >0 are included in the median, other
43 points are weighted by the kernel value (medianing lots of zeroes is
44 rather pointless)
45 $new = med2d $old, $kernel, {OPTIONS}
47 $smoothed = med2d $image, ones(3,3), {Boundary => Reflect}
49 Boundary - controls what values are assumed for the image when kernel
51 crosses its edge:
52 => Default - periodic boundary conditions (i.e. wrap around axis)
53 => Reflect - reflect at boundary
54 => Truncate - truncate at boundary
55 Bad values are ignored in the calculation. If all elements within the
57 kernel are bad, the output is set bad.
58 med2df
60 Signature: (a(m,n); [o]b(m,n); int __p_size; int __q_size; int opt)
61 2D median-convolution of an array in a pxq window (smoothing)
63 Note: this routine does the median over all points in a rectangular
65 window and is not quite as flexible as "med2d" in this regard
66 but slightly faster instead
67 $new = med2df $old, $xwidth, $ywidth, {OPTIONS}
69 $smoothed = med2df $image, 3, 3, {Boundary => Reflect}
71 Boundary - controls what values are assumed for the image when kernel
73 crosses its edge:
74 => Default - periodic boundary conditions (i.e. wrap around axis)
75 => Reflect - reflect at boundary
76 => Truncate - truncate at boundary
77 med2df does not process bad values. It will set the bad-value flag of
79 all output piddles if the flag is set for any of the input piddles.
80 box2d
82 Signature: (a(n,m); [o] b(n,m); int wx; int wy; int edgezero)
83 fast 2D boxcar average
85 $smoothim = $im->box2d($wx,$wy,$edgezero=1);
87 The edgezero argument controls if edge is set to zero (edgezero=1) or
89 just keeps the original (unfiltered) values.
90 "box2d" should be updated to support similar edge options as "conv2d"
92 and "med2d" etc.
93 Boxcar averaging is a pretty crude way of filtering. For serious stuff
95 better filters are around (e.g., use conv2d with the appropriate
96 kernel). On the other hand it is fast and computational cost grows only
97 approximately linearly with window size.
98 box2d does not process bad values. It will set the bad-value flag of
100 all output piddles if the flag is set for any of the input piddles.
101 patch2d
103 Signature: (a(m,n); int bad(m,n); [o]b(m,n))
104 patch bad pixels out of 2D images using a mask
106 $patched = patch2d $data, $bad;
108 $bad is a 2D mask array where 1=bad pixel 0=good pixel. Pixels are
110 replaced by the average of their non-bad neighbours; if all neighbours
111 are bad, the original data value is copied across.
112 This routine does not handle bad values - use patchbad2d instead
114 patchbad2d
116 Signature: (a(m,n); [o]b(m,n))
117 patch bad pixels out of 2D images containing bad values
119 $patched = patchbad2d $data;
121 Pixels are replaced by the average of their non-bad neighbours; if all
123 neighbours are bad, the output is set bad. If the input piddle
124 contains no bad values, then a straight copy is performed (see
125 patch2d).
126 patchbad2d handles bad values. The output piddle may contain bad
128 values, depending on the pattern of bad values in the input piddle.
129 max2d_ind
131 Signature: (a(m,n); [o]val(); int [o]x(); int[o]y())
132 Return value/position of maximum value in 2D image
134 Contributed by Tim Jeness
136 Bad values are excluded from the search. If all pixels are bad then the
138 output is set bad.
139 centroid2d
141 Signature: (im(m,n); x(); y(); box(); [o]xcen(); [o]ycen())
142 Refine a list of object positions in 2D image by centroiding in a box
144 $box is the full-width of the box, i.e. the window is "+/- $box/2".
146 Bad pixels are excluded from the centroid calculation. If all elements
148 are bad (or the pixel sum is 0 - but why would you be centroiding
149 something with negatives in...) then the output values are set bad.
150 cc8compt
152 Signature: (a(m,n); [o]b(m,n))
153 Connected 8-component labeling of a binary image.
155 Connected 8-component labeling of 0,1 image - i.e. find seperate
157 segmented objects and fill object pixels with object number
158 $segmented = cc8compt( $image > $threshold );
160 cc8compt ignores the bad-value flag of the input piddles. It will set
162 the bad-value flag of all output piddles if the flag is set for any of
163 the input piddles.
164 polyfill
166 Signature: (int [o,nc] im(m,n); float ps(two=2,np); int col())
167 fill the area inside the given polygon with a given colour
169 This function works inplace, i.e. modifies "im".
171 polyfill ignores the bad-value flag of the input piddles. It will set
173 the bad-value flag of all output piddles if the flag is set for any of
174 the input piddles.
175 polyfillv
177 return the (dataflown) area of an image within a polygon
178 # increment intensity in area bounded by $poly
180 $im->polyfillv($pol)++; # legal in perl >= 5.6
181 # compute average intensity within area bounded by $poly
182 $av = $im->polyfillv($poly)->avg;
183 rot2d
185 Signature: (im(m,n); float angle(); bg(); int aa(); [o] om(p,q))
186 rotate an image by given "angle"
188 # rotate by 10.5 degrees with antialiasing, set missing values to 7
190 $rot = $im->rot2d(10.5,7,1);
191 This function rotates an image through an "angle" between -90 and + 90
193 degrees. Uses/doesn't use antialiasing depending on the "aa" flag.
194 Pixels outside the rotated image are set to "bg".
195 Code modified from pnmrotate (Copyright Jef Poskanzer) with an
197 algorithm based on "A Fast Algorithm for General Raster Rotation" by
198 Alan Paeth, Graphics Interface '86, pp. 77-81.
199 Use the "rotnewsz" function to find out about the dimension of the
201 newly created image
202 ($newcols,$newrows) = rotnewsz $oldn, $oldm, $angle;
204 PDL::Transform offers a more general interface to distortions,
206 including rotation, with various types of sampling; but rot2d is
207 faster.
208 rot2d ignores the bad-value flag of the input piddles. It will set the
210 bad-value flag of all output piddles if the flag is set for any of the
211 input piddles.
212 bilin2d
214 Signature: (I(n,m); O(q,p))
215 Bilinearly maps the first piddle in the second. The interpolated values
217 are actually added to the second piddle which is supposed to be larger
218 than the first one.
219 bilin2d ignores the bad-value flag of the input piddles. It will set
221 the bad-value flag of all output piddles if the flag is set for any of
222 the input piddles.
223 rescale2d
225 Signature: (I(m,n); O(p,q))
226 The first piddle is rescaled to the dimensions of the second (expanding
228 or meaning values as needed) and then added to it in place. Nothing
229 useful is returned.
230 If you want photometric accuracy or automatic FITS header metadata
232 tracking, consider using PDL::Transform::map instead: it does these
233 things, at some speed penalty compared to rescale2d.
234 rescale2d ignores the bad-value flag of the input piddles. It will set
236 the bad-value flag of all output piddles if the flag is set for any of
237 the input piddles.
238 fitwarp2d
240 Find the best-fit 2D polynomial to describe a coordinate
241 transformation.
242 ( $px, $py ) = fitwarp2d( $x, $y, $u, $v, $nf. { options } )
244 Given a set of points in the output plane ("$u,$v"), find the best-fit
246 (using singular-value decomposition) 2D polynomial to describe the
247 mapping back to the image plane ("$x,$y"). The order of the fit is
248 controlled by the $nf parameter (the maximum power of the polynomial is
249 "$nf - 1"), and you can restrict the terms to fit using the "FIT"
250 option.
251 $px and $py are "np" by "np" element piddles which describe a
253 polynomial mapping (of order "np-1") from the output "(u,v)" image to
254 the input "(x,y)" image:
255 x = sum(j=0,np-1) sum(i=0,np-1) px(i,j) * u^i * v^j
257 y = sum(j=0,np-1) sum(i=0,np-1) py(i,j) * u^i * v^j
258 The transformation is returned for the reverse direction (ie output to
260 input image) since that is what is required by the warp2d() routine.
261 The applywarp2d() routine can be used to convert a set of "$u,$v"
262 points given $px and $py.
263 Options:
265 FIT - which terms to fit? default ones(byte,$nf,$nf)
267 THRESH - in svd, remove terms smaller than THRESH * max value
268 default is 1.0e-5
269 FIT "FIT" allows you to restrict which terms of the polynomial to fit:
271 only those terms for which the FIT piddle evaluates to true will be
272 evaluated. If a 2D piddle is sent in, then it is used for the x
273 and y polynomials; otherwise "$fit->slice(":,:,(0)")" will be used
274 for $px and "$fit->slice(":,:,(1)")" will be used for $py.
275 THRESH
277 Remove all singular values whose valus is less than "THRESH" times
278 the largest singular value.
279 The number of points must be at least equal to the number of terms to
281 fit ("$nf*$nf" points for the default value of "FIT").
282 # points in original image
284 $x = pdl( 0, 0, 100, 100 );
285 $y = pdl( 0, 100, 100, 0 );
286 # get warped to these positions
287 $u = pdl( 10, 10, 90, 90 );
288 $v = pdl( 10, 90, 90, 10 );
289 #
290 # shift of origin + scale x/y axis only
291 $fit = byte( [ [1,1], [0,0] ], [ [1,0], [1,0] ] );
292 ( $px, $py ) = fitwarp2d( $x, $y, $u, $v, 2, { FIT => $fit } );
293 print "px = ${px}py = $py";
294 px =
295 [
296 [-12.5 1.25]
297 [ 0 0]
298 ]
299 py =
300 [
301 [-12.5 0]
302 [ 1.25 0]
303 ]
304 #
305 # Compared to allowing all 4 terms
306 ( $px, $py ) = fitwarp2d( $x, $y, $u, $v, 2 );
307 print "px = ${px}py = $py";
308 px =
309 [
310 [ -12.5 1.25]
311 [ 1.110223e-16 -1.1275703e-17]
312 ]
313 py =
314 [
315 [ -12.5 1.6653345e-16]
316 [ 1.25 -5.8546917e-18]
317 ]
318 applywarp2d
320 Transform a set of points using a 2-D polynomial mapping
321 ( $x, $y ) = applywarp2d( $px, $py, $u, $v )
323 Convert a set of points (stored in 1D piddles "$u,$v") to "$x,$y" using
325 the 2-D polynomial with coefficients stored in $px and $py. See
326 fitwarp2d() for more information on the format of $px and $py.
327 warp2d
329 Signature: (img(m,n); double px(np,np); double py(np,np); [o] warp(m,n); { options })
330 Warp a 2D image given a polynomial describing the reverse mapping.
332 $out = warp2d( $img, $px, $py, { options } );
334 Apply the polynomial transformation encoded in the $px and $py piddles
336 to warp the input image $img into the output image $out.
337 The format for the polynomial transformation is described in the
339 documentation for the fitwarp2d() routine.
340 At each point "x,y", the closest 16 pixel values are combined with an
342 interpolation kernel to calculate the value at "u,v". The
343 interpolation is therefore done in the image, rather than Fourier,
344 domain. By default, a "tanh" kernel is used, but this can be changed
345 using the "KERNEL" option discussed below (the choice of kernel depends
346 on the frequency content of the input image).
347 The routine is based on the "warping" command from the Eclipse data-
349 reduction package - see http://www.eso.org/eclipse/ - and for further
350 details on image resampling see Wolberg, G., "Digital Image Warping",
351 1990, IEEE Computer Society Press ISBN 0-8186-8944-7).
352 Currently the output image is the same size as the input one, which
354 means data will be lost if the transformation reduces the pixel scale.
355 This will (hopefully) be changed soon.
356 $img = rvals(byte,501,501);
358 imag $img, { JUSTIFY => 1 };
359 #
360 # use a not-particularly-obvious transformation:
361 # x = -10 + 0.5 * $u - 0.1 * $v
362 # y = -20 + $v - 0.002 * $u * $v
363 #
364 $px = pdl( [ -10, 0.5 ], [ -0.1, 0 ] );
365 $py = pdl( [ -20, 0 ], [ 1, 0.002 ] );
366 $wrp = warp2d( $img, $px, $py );
367 #
368 # see the warped image
369 imag $warp, { JUSTIFY => 1 };
370 The options are:
372 KERNEL - default value is tanh
374 NOVAL - default value is 0
375 "KERNEL" is used to specify which interpolation kernel to use (to see
377 what these kernels look like, use the warp2d_kernel() routine). The
378 options are:
379 tanh
381 Hyperbolic tangent: the approximation of an ideal box filter by the
382 product of symmetric tanh functions.
383 sinc
385 For a correctly sampled signal, the ideal filter in the fourier
386 domain is a rectangle, which produces a "sinc" interpolation kernel
387 in the spatial domain:
388 sinc(x) = sin(pi * x) / (pi * x)
390 However, it is not ideal for the "4x4" pixel region used here.
392 sinc2
394 This is the square of the sinc function.
395 lanczos
397 Although defined differently to the "tanh" kernel, the result is
398 very similar in the spatial domain. The Lanczos function is
399 defined as
400 L(x) = sinc(x) * sinc(x/2) if abs(x) < 2
402 = 0 otherwise
403 hann
405 This kernel is derived from the following function:
406 H(x) = a + (1-a) * cos(2*pi*x/(N-1)) if abs(x) < 0.5*(N-1)
408 = 0 otherwise
409 with "a = 0.5" and N currently equal to 2001.
411 hamming
413 This kernel uses the same H(x) as the Hann filter, but with "a =
414 0.54".
415 "NOVAL" gives the value used to indicate that a pixel in the output
417 image does not map onto one in the input image.
418 warp2d_kernel
420 Return the specified kernel, as used by warp2d
421 ( $x, $k ) = warp2d_kernel( $name )
423 The valid values for $name are the same as the "KERNEL" option of
425 warp2d().
426 line warp2d_kernel( "hamming" );
428
430 Copyright (C) Karl Glazebrook 1997 with additions by Robin Williams
431 (rjrw@ast.leeds.ac.uk), Tim Jeness (timj@jach.hawaii.edu), and Doug
432 Burke (burke@ifa.hawaii.edu).
433 All rights reserved. There is no warranty. You are allowed to
435 redistribute this software / documentation under certain conditions.
436 For details, see the file COPYING in the PDL distribution. If this file
437 is separated from the PDL distribution, the copyright notice should be
438 included in the file.
439perl v5.12.3 2011-03-31 Image2D(3)