ImageND(3) User Contributed Perl Documentation ImageND(3)NAMEPDL::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); int adims(p); int 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.
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.
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.
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.
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.
perl v5.10.0 2008-08-29 ImageND(3)
