Manpages

Image2D

NAME

DESCRIPTION

SYNOPSIS

 use PDL::Image2D;

FUNCTIONS

conv2d

  Signature: (a(m,n); kern(p,q); [o]b(m,n); int opt)

For large kernels, using a FFT routine, such as fftconvolve() in "PDL::FFT", will be quicker.

 $new = conv2d $old, $kernel, {OPTIONS}

 $smoothed = conv2d $image, ones(3,3), {Boundary => Reflect}

 Boundary - controls what values are assumed for the image when kernel
            crosses its edge:
            => Default  - periodic boundary conditions 
                          (i.e. wrap around axis)
            => Reflect  - reflect at boundary
            => Truncate - truncate at boundary

med2d

  Signature: (a(m,n); kern(p,q); [o]b(m,n); int opt)

Note: only points in the kernel >0 are included in the median, other points are weighted by the kernel value (medianing lots of zeroes is rather pointless)

 $new = med2d $old, $kernel, {OPTIONS}

 $smoothed = med2d $image, ones(3,3), {Boundary => Reflect}

 Boundary - controls what values are assumed for the image when kernel
            crosses its edge:
            => Default  - periodic boundary conditions (i.e. wrap around axis)
            => Reflect  - reflect at boundary
            => Truncate - truncate at boundary

med2df

  Signature: (a(m,n); [o]b(m,n); int __p_size; int __q_size; int opt)

Note: this routine does the median over all points in a rectangular
      window and is not quite as flexible as "med2d" in this regard
      but slightly faster instead

 $new = med2df $old, $xwidth, $ywidth, {OPTIONS}

 $smoothed = med2df $image, 3, 3, {Boundary => Reflect}

 Boundary - controls what values are assumed for the image when kernel
            crosses its edge:
            => Default  - periodic boundary conditions (i.e. wrap around axis)
            => Reflect  - reflect at boundary
            => Truncate - truncate at boundary

patch2d

  Signature: (a(m,n); int bad(m,n); [o]b(m,n))

 $patched = patch2d $data, $bad;

patchbad2d

  Signature: (a(m,n); [o]b(m,n))

 $patched = patchbad2d $data;

max2d_ind

  Signature: (a(m,n); [o]val(); int [o]x(); int[o]y())

Contributed by Tim Jeness  

centroid2d

  Signature: (im(m,n); x(); y(); box(); [o]xcen(); [o]ycen())

$box is the full-width of the box, i.e. the window is "+/- $box/2".  

cc8compt

  Signature: (a(m,n); [o]b(m,n))

Connected 8-component labeling of 0,1 image - i.e. find seperate segmented objects and fill object pixels with object number

 $segmented = cc8compt( $image > $threshold );

polyfill

  Signature: (int [o,nc] im(m,n); float ps(two=2,np); int col())

This function works inplace, i.e. modifies "im".  

polyfillv

  # increment intensity in area bounded by $poly
  $im->polyfillv($pol)++; # legal in perl >= 5.6
  # compute average intensity within area bounded by $poly
  $av = $im->polyfillv($poly)->avg;

rot2d

  Signature: (im(m,n); float angle(); bg(); int aa(); [o] om(p,q))

  # rotate by 10.5 degrees with antialiasing, set missing values to 7
  $rot = $im->rot2d(10.5,7,1);

Code modified from pnmrotate (Copyright Jef Poskanzer) with an algorithm based on ``A Fast Algorithm for General Raster Rotation'' by Alan Paeth, Graphics Interface '86, pp. 77-81.

Use the "rotnewsz" function to find out about the dimension of the newly created image

  ($newcols,$newrows) = rotnewsz $oldn, $oldm, $angle;

bilin2d

  Signature: (I(n,m); O(q,p))

rescale2d

  Signature: (I(n,m); O(q,p))

fitwarp2d

  ( $px, $py ) = fitwarp2d( $x, $y, $u, $v, $nf. { options } )

$px and $py are "np" by "np" element piddles which describe a polynomial mapping (of order "np-1") from the output "(u,v)" image to the input "(x,y)" image:

  x = sum(j=0,np-1) sum(i=0,np-1) px(i,j) * u^i * v^j
  y = sum(j=0,np-1) sum(i=0,np-1) py(i,j) * u^i * v^j

Options:

  FIT     - which terms to fit? default ones(byte,$nf,$nf)
  THRESH  - in svd, remove terms smaller than THRESH * max value
            default is 1.0e-5

FIT

"FIT" allows you to restrict which terms of the polynomial to fit: only those terms for which the FIT piddle evaluates to true will be evaluated. If a 2D piddle is sent in, then it is used for the x and y polynomials; otherwise "$fit->slice(":,:,(0)")" will be used for $px and "$fit->slice(":,:,(1)")" will be used for $py.

THRESH

Remove all singular values whose valus is less than "THRESH" times the largest singular value.

The number of points must be at least equal to the number of terms to fit ("$nf*$nf" points for the default value of "FIT").

  # points in original image
  $x = pdl( 0,   0, 100, 100 );
  $y = pdl( 0, 100, 100,   0 );
  # get warped to these positions
  $u = pdl( 10, 10, 90, 90 );
  $v = pdl( 10, 90, 90, 10 );
  # 
  # shift of origin + scale x/y axis only
  $fit = byte( [ [1,1], [0,0] ], [ [1,0], [1,0] ] );
  ( $px, $py ) = fitwarp2d( $x, $y, $u, $v, 2, { FIT => $fit } );
  print "px = ${px}py = $py";
  px = 
  [
   [-12.5  1.25]
   [    0     0]
  ]
  py = 
  [
   [-12.5     0]
   [ 1.25     0]
  ]
  #
  # Compared to allowing all 4 terms
  ( $px, $py ) = fitwarp2d( $x, $y, $u, $v, 2 );
  print "px = ${px}py = $py";
  px = 
  [
   [         -12.5           1.25]
   [  1.110223e-16 -1.1275703e-17]
  ]
  py = 
  [
   [         -12.5  1.6653345e-16]
   [          1.25 -5.8546917e-18]
  ]

applywarp2d

  ( $x, $y ) = applywarp2d( $px, $py, $u, $v )

warp2d

  Signature: (img(m,n); double px(np,np); double py(np,np); [o] warp(m,n); { options })

  $out = warp2d( $img, $px, $py, { options } );

The format for the polynomial transformation is described in the documentation for the fitwarp2d() routine.

At each point "x,y", the closest 16 pixel values are combined with an interpolation kernel to calculate the value at "u,v". The interpolation is therefore done in the image, rather than Fourier, domain. By default, a "tanh" kernel is used, but this can be changed using the "KERNEL" option discussed below (the choice of kernel depends on the frequency content of the input image).

The routine is based on the "warping" command from the Eclipse data-reduction package - see http://www.eso.org/eclipse/ - and for further details on image resampling see Wolberg, G., ``Digital Image Warping'', 1990, IEEE Computer Society Press ISBN 0-8186-8944-7).

Currently the output image is the same size as the input one, which means data will be lost if the transformation reduces the pixel scale. This will (hopefully) be changed soon.

  $img = rvals(byte,501,501);
  imag $img, { JUSTIFY => 1 };
  # 
  # use a not-particularly-obvious transformation:
  #   x = -10 + 0.5 * $u - 0.1 * $v 
  #   y = -20 + $v - 0.002 * $u * $v
  #
  $px  = pdl( [ -10, 0.5 ], [ -0.1, 0 ] );
  $py  = pdl( [ -20, 0 ], [ 1, 0.002 ] );
  $wrp = warp2d( $img, $px, $py );
  #
  # see the warped image
  imag $warp, { JUSTIFY => 1 };

  KERNEL - default value is tanh
  NOVAL  - default value is 0

tanh

Hyperbolic tangent: the approximation of an ideal box filter by the product of symmetric tanh functions.

sinc

For a correctly sampled signal, the ideal filter in the fourier domain is a rectangle, which produces a "sinc" interpolation kernel in the spatial domain:

  sinc(x) = sin(pi * x) / (pi * x)

However, it is not ideal for the "4x4" pixel region used here.

sinc2

This is the square of the sinc function.

lanczos

Although defined differently to the "tanh" kernel, the result is very similar in the spatial domain. The Lanczos function is defined as

  L(x) = sinc(x) * sinc(x/2)  if abs(x) < 2
       = 0                       otherwise

hann

This kernel is derived from the following function:

  H(x) = a + (1-a) * cos(2*pi*x/(N-1))  if abs(x) < 0.5*(N-1)
       = 0                                 otherwise

with "a = 0.5" and N currently equal to 2001.

hamming

This kernel uses the same H(x) as the Hann filter, but with "a = 0.54".

"NOVAL" gives the value used to indicate that a pixel in the output image does not map onto one in the input image.  

warp2d_kernel

  ( $x, $k ) = warp2d_kernel( $name )

  line warp2d_kernel( "hamming" );

AUTHORS

All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.

Index

NAME

DESCRIPTION

SYNOPSIS

FUNCTIONS

conv2d

med2d

med2df

patch2d

patchbad2d

max2d_ind

centroid2d

cc8compt

polyfill

polyfillv

rot2d

bilin2d

rescale2d

fitwarp2d

applywarp2d

warp2d

warp2d_kernel

AUTHORS