NAME

       PDL::ImageND - useful image processing in N dimensions

DESCRIPTION

       These routines act on PDLs as N-dimensional objects, not as threaded sets of 0-D or 1-D
       objects.  The file is sort of a catch-all for broadly functional routines, most of which
       could legitimately be filed elsewhere (and probably will, one day).

       ImageND is not a part of the PDL core (v2.4) and hence must be explicitly loaded.

SYNOPSIS

        use PDL::ImageND;

        $b = $a->convolveND($kernel,{bound=>'periodic'});
        $b = $a->rebin(50,30,10);

FUNCTIONS

   convolve
         Signature: (a(m); b(n); indx adims(p); indx bdims(q); [o]c(m))

       N-dimensional convolution (Deprecated; use convolveND)

       $new = convolve $a, $kernel

       Convolve an array with a kernel, both of which are N-dimensional.  This routine does
       direct convolution (by copying) but uses quasi-periodic boundary conditions: each dim
       "wraps around" to the next higher row in the next dim.

       This routine is kept for backwards compatibility with earlier scripts; for most purposes
       you want convolveND instead: it runs faster and handles a variety of boundary conditions.

       convolve does not process bad values.  It will set the bad-value flag of all output
       piddles if the flag is set for any of the input piddles.

   ninterpol()
       N-dimensional interpolation routine

        Signature: ninterpol(point(),data(n),[o]value())

             $value = ninterpol($point, $data);

       "ninterpol" uses "interpol" to find a linearly interpolated value in N dimensions,
       assuming the data is spread on a uniform grid.  To use an arbitrary grid distribution,
       need to find the grid-space point from the indexing scheme, then call "ninterpol" -- this
       is far from trivial (and ill-defined in general).

       See also interpND, which includes boundary conditions and allows you to switch the method
       of interpolation, but which runs somewhat slower.

   rebin
         Signature: (a(m); [o]b(n); int ns => n)

       N-dimensional rebinning algorithm

       $new = rebin $a, $dim1, $dim2,..;.  $new = rebin $a, $template; $new = rebin $a,
       $template, {Norm => 1};

       Rebin an N-dimensional array to newly specified dimensions.  Specifying `Norm' keeps the
       sum constant, otherwise the intensities are kept constant.  If more template dimensions
       are given than for the input pdl, these dimensions are created; if less, the final
       dimensions are maintained as they were.

       So if $a is a 10 x 10 pdl, then "rebin($a,15)" is a 15 x 10 pdl, while
       "rebin($a,15,16,17)" is a 15 x 16 x 17 pdl (where the values along the final dimension are
       all identical).

       Expansion is performed by sampling; reduction is performed by averaging.  If you want
       different behavior, use PDL::Transform::map instead.  PDL::Transform::map runs slower but
       is more flexible.

       rebin does not process bad values.  It will set the bad-value flag of all output piddles
       if the flag is set for any of the input piddles.

   circ_mean_p
       Calculates the circular mean of an n-dim image and returns the projection. Optionally
       takes the center to be used.

          $cmean=circ_mean_p($im);
          $cmean=circ_mean_p($im,{Center => [10,10]});

   circ_mean
       Smooths an image by applying circular mean.  Optionally takes the center to be used.

          circ_mean($im);
          circ_mean($im,{Center => [10,10]});

   kernctr
       `centre' a kernel (auxiliary routine to fftconvolve)

               $kernel = kernctr($image,$smallk);
               fftconvolve($image,$kernel);

       kernctr centres a small kernel to emulate the behaviour of the direct convolution
       routines.

   convolveND
         Signature: (k0(); SV *k; SV *aa; SV *a)

       Speed-optimized convolution with selectable boundary conditions

       $new = convolveND($a, $kernel, [ {options} ]);

       Conolve an array with a kernel, both of which are N-dimensional.

       If the kernel has fewer dimensions than the array, then the extra array dimensions are
       threaded over.  There are options that control the boundary conditions and method used.

       The kernel's origin is taken to be at the kernel's center.  If your kernel has a dimension
       of even order then the origin's coordinates get rounded up to the next higher pixel (e.g.
       (1,2) for a 3x4 kernel).  This mimics the behavior of the earlier convolve and fftconvolve
       routines, so convolveND is a drop-in replacement for them.

       The kernel may be any size compared to the image, in any dimension.

       The kernel and the array are not quite interchangeable (as in mathematical convolution):
       the code is inplace-aware only for the array itself, and the only allowed boundary
       condition on the kernel is truncation.

       convolveND is inplace-aware: say "convolveND(inplace $a ,$k)" to modify a variable in-
       place.  You don't reduce the working memory that way -- only the final memory.

       OPTIONS

       Options are parsed by PDL::Options, so unique abbreviations are accepted.

       boundary (default: 'truncate')
          The boundary condition on the array, which affects any pixel closer to the edge than
          the half-width of the kernel.

          The boundary conditions are the same as those accepted by range, because this option is
          passed directly into range.  Useful options are 'truncate' (the default), 'extend', and
          'periodic'.  You can select different boundary conditions for different axes -- see
          range for more detail.

          The (default) truncate option marks all the near-boundary pixels as BAD if you have bad
          values compiled into your PDL and the array's badflag is set.

       method (default: 'auto')
          The method to use for the convolution.  Acceptable alternatives are 'direct', 'fft', or
          'auto'.  The direct method is an explicit copy-and-multiply operation; the fft method
          takes the Fourier transform of the input and output kernels.  The two methods give the
          same answer to within double-precision numerical roundoff.  The fft method is much
          faster for large kernels; the direct method is faster for tiny kernels.  The tradeoff
          occurs when the array has about 400x more pixels than the kernel.

          The default method is 'auto', which chooses direct or fft convolution based on the size
          of the input arrays.

       NOTES

       At the moment there's no way to thread over kernels.  That could/should be fixed.

       The threading over input is cheesy and should probably be fixed: currently the kernel just
       gets dummy dimensions added to it to match the input dims.  That does the right thing
       tersely but probably runs slower than a dedicated threadloop.

       The direct copying code uses PP primarily for the generic typing: it includes its own
       threadloops.

       convolveND does not process bad values.  It will set the bad-value flag of all output
       piddles if the flag is set for any of the input piddles.

AUTHORS

       Copyright (C) Karl Glazebrook and Craig DeForest, 1997, 2003 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.