NAME
PDLA::ImageND  useful image processing in N dimensions
DESCRIPTION
These routines act on PDLAs as Ndimensional objects, not as threaded sets of 0D or 1D objects. The file is sort of a catchall for broadly functional routines, most of which could legitimately be filed elsewhere (and probably will, one day).
ImageND is not a part of the PDLA core (v2.4) and hence must be explicitly loaded.
SYNOPSIS
use PDLA::ImageND;
$y = $x>convolveND($kernel,{bound=>'periodic'});
$y = $x>rebin(50,30,10);
FUNCTIONS
convolve
Signature: (a(m); b(n); indx adims(p); indx bdims(q); [o]c(m))
Ndimensional convolution (Deprecated; use convolveND)
$new = convolve $x, $kernel
Convolve an array with a kernel, both of which are Ndimensional. This routine does direct convolution (by copying) but uses quasiperiodic 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 badvalue flag of all output piddles if the flag is set for any of the input piddles.
ninterpol()
Ndimensional 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 gridspace point from the indexing scheme, then call ninterpol
 this is far from trivial (and illdefined 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)
Ndimensional rebinning algorithm
$new = rebin $x, $dim1, $dim2,..;.
$new = rebin $x, $template;
$new = rebin $x, $template, {Norm => 1};
Rebin an Ndimensional 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 $x
is a 10 x 10 pdl, then rebin($x,15)
is a 15 x 10 pdl, while rebin($x,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 PDLA::Transform::map instead. PDLA::Transform::map runs slower but is more flexible.
rebin does not process bad values. It will set the badvalue 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 ndim 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)
Speedoptimized convolution with selectable boundary conditions
$new = convolveND($x, $kernel, [ {options} ]);
Conolve an array with a kernel, both of which are Ndimensional.
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 dropin 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 inplaceaware only for the array itself, and the only allowed boundary condition on the kernel is truncation.
convolveND is inplaceaware: say convolveND(inplace $x ,$k)
to modify a variable inplace. You don't reduce the working memory that way  only the final memory.
OPTIONS
Options are parsed by PDLA::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 halfwidth 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 nearboundary pixels as BAD if you have bad values compiled into your PDLA 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 copyandmultiply operation; the fft method takes the Fourier transform of the input and output kernels. The two methods give the same answer to within doubleprecision 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 badvalue 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 PDLA distribution. If this file is separated from the PDLA distribution, the copyright notice should be included in the file.