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.