.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "ImageND 3pm"
.TH ImageND 3pm "2023-06-17" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PDL::ImageND \- useful image processing in N dimensions
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
These routines act on PDLs as N\-dimensional objects, not as broadcasted
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).
.PP
ImageND is not a part of the \s-1PDL\s0 core (v2.4) and hence must be explicitly
loaded.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use PDL::ImageND;
\&
\& $y = $x\->convolveND($kernel,{bound=>\*(Aqperiodic\*(Aq});
\& $y = $x\->rebin(50,30,10);
.Ve
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "convolve"
.IX Subsection "convolve"
.Vb 1
\&  Signature: (a(m); b(n); indx adims(p); indx bdims(q); [o]c(m))
.Ve
.PP
N\-dimensional convolution (Deprecated; use convolveND)
.PP
.Vb 1
\&  $new = convolve $x, $kernel
.Ve
.PP
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 \*(L"wraps around\*(R" to the next higher row in
the next dim.
.PP
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.
.PP
convolve does not process bad values.
It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
.SS "\fBninterpol()\fP"
.IX Subsection "ninterpol()"
N\-dimensional interpolation routine
.PP
.Vb 1
\& Signature: ninterpol(point(),data(n),[o]value())
.Ve
.PP
.Vb 1
\&      $value = ninterpol($point, $data);
.Ve
.PP
\&\f(CW\*(C`ninterpol\*(C'\fR uses \f(CW\*(C`interpol\*(C'\fR 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 \f(CW\*(C`ninterpol\*(C'\fR \*(-- this is far from
trivial (and ill-defined in general).
.PP
See also interpND, which includes boundary 
conditions and allows you to switch the method of interpolation, but
which runs somewhat slower.
.SS "rebin"
.IX Subsection "rebin"
.Vb 1
\&  Signature: (a(m); [o]b(n); int ns => n)
.Ve
.PP
N\-dimensional rebinning algorithm
.PP
.Vb 3
\&  $new = rebin $x, $dim1, $dim2,..;.
\&  $new = rebin $x, $template;
\&  $new = rebin $x, $template, {Norm => 1};
.Ve
.PP
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.
.PP
So if \f(CW$x\fR is a 10 x 10 pdl, then \f(CW\*(C`rebin($x,15)\*(C'\fR is a 15 x 10 pdl,
while \f(CW\*(C`rebin($x,15,16,17)\*(C'\fR is a 15 x 16 x 17 pdl (where the values
along the final dimension are all identical).
.PP
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.
.PP
rebin does not process bad values.
It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
.SS "circ_mean_p"
.IX Subsection "circ_mean_p"
Calculates the circular mean of an n\-dim image and returns
the projection. Optionally takes the center to be used.
.PP
.Vb 2
\&   $cmean=circ_mean_p($im);
\&   $cmean=circ_mean_p($im,{Center => [10,10]});
.Ve
.SS "circ_mean"
.IX Subsection "circ_mean"
Smooths an image by applying circular mean.
Optionally takes the center to be used.
.PP
.Vb 2
\&   circ_mean($im);
\&   circ_mean($im,{Center => [10,10]});
.Ve
.SS "kernctr"
.IX Subsection "kernctr"
`centre' a kernel (auxiliary routine to fftconvolve)
.PP
.Vb 2
\&        $kernel = kernctr($image,$smallk);
\&        fftconvolve($image,$kernel);
.Ve
.PP
kernctr centres a small kernel to emulate the behaviour of the direct
convolution routines.
.SS "convolveND"
.IX Subsection "convolveND"
.Vb 1
\&  Signature: (k0(); pdl *k; pdl *aa; pdl *a)
.Ve
.PP
Speed-optimized convolution with selectable boundary conditions
.PP
.Vb 1
\&  $new = convolveND($x, $kernel, [ {options} ]);
.Ve
.PP
Conolve an array with a kernel, both of which are N\-dimensional.
.PP
If the kernel has fewer dimensions than the array, then the extra array
dimensions are broadcasted over.  There are options that control the boundary
conditions and method used.
.PP
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 \*(L"convolve\*(R" and
fftconvolve routines, so convolveND is a drop-in
replacement for them.
.PP
The kernel may be any size compared to the image, in any dimension.
.PP
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.
.PP
convolveND is inplace-aware: say \f(CW\*(C`convolveND(inplace $x ,$k)\*(C'\fR to modify
a variable in-place.  You don't reduce the working memory that way \*(-- only
the final memory.
.PP
\&\s-1OPTIONS\s0
.PP
Options are parsed by PDL::Options, so unique abbreviations are accepted.
.IP "boundary (default: 'truncate')" 3
.IX Item "boundary (default: 'truncate')"
The boundary condition on the array, which affects any pixel closer
to the edge than the half-width of the kernel.
.Sp
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.
.Sp
The (default) truncate option marks all the near-boundary pixels as \s-1BAD\s0 if
you have bad values compiled into your \s-1PDL\s0 and the array's badflag is set.
.IP "method (default: 'auto')" 3
.IX Item "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.
.Sp
The default method is 'auto', which chooses direct or fft convolution
based on the size of the input arrays.
.PP
\&\s-1NOTES\s0
.PP
At the moment there's no way to broadcast over kernels.  That could/should
be fixed.
.PP
The broadcasting 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 broadcastloop.
.PP
The direct copying code uses \s-1PP\s0 primarily for the generic typing: it includes
its own broadcastloops.
.PP
convolveND does not process bad values.
It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
.SH "AUTHORS"
.IX Header "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 \s-1COPYING\s0 in the \s-1PDL\s0
distribution. If this file is separated from the \s-1PDL\s0 distribution,
the copyright notice should be included in the file.