1ImageND(3)            User Contributed Perl Documentation           ImageND(3)
2
3
4

NAME

6       PDL::ImageND - useful image processing in N dimensions
7

DESCRIPTION

9       These routines act on PDLs as N-dimensional objects, not as threaded
10       sets of 0-D or 1-D objects.  The file is sort of a catch-all for
11       broadly functional routines, most of which could legitimately be filed
12       elsewhere (and probably will, one day).
13
14       ImageND is not a part of the PDL core (v2.4) and hence must be
15       explicitly loaded.
16

SYNOPSIS

18        use PDL::ImageND;
19
20        $b = $a->convolveND($kernel,{bound=>'periodic'});
21        $b = $a->rebin(50,30,10);
22

FUNCTIONS

24   convolve
25         Signature: (a(m); b(n); indx adims(p); indx bdims(q); [o]c(m))
26
27       N-dimensional convolution (Deprecated; use convolveND)
28
29       $new = convolve $a, $kernel
30
31       Convolve an array with a kernel, both of which are N-dimensional.  This
32       routine does direct convolution (by copying) but uses quasi-periodic
33       boundary conditions: each dim "wraps around" to the next higher row in
34       the next dim.
35
36       This routine is kept for backwards compatibility with earlier scripts;
37       for most purposes you want convolveND instead: it runs faster and
38       handles a variety of boundary conditions.
39
40       convolve does not process bad values.  It will set the bad-value flag
41       of all output piddles if the flag is set for any of the input piddles.
42
43   ninterpol()
44       N-dimensional interpolation routine
45
46        Signature: ninterpol(point(),data(n),[o]value())
47
48             $value = ninterpol($point, $data);
49
50       "ninterpol" uses "interpol" to find a linearly interpolated value in N
51       dimensions, assuming the data is spread on a uniform grid.  To use an
52       arbitrary grid distribution, need to find the grid-space point from the
53       indexing scheme, then call "ninterpol" -- this is far from trivial (and
54       ill-defined in general).
55
56       See also interpND, which includes boundary conditions and allows you to
57       switch the method of interpolation, but which runs somewhat slower.
58
59   rebin
60         Signature: (a(m); [o]b(n); int ns => n)
61
62       N-dimensional rebinning algorithm
63
64       $new = rebin $a, $dim1, $dim2,..;.  $new = rebin $a, $template; $new =
65       rebin $a, $template, {Norm => 1};
66
67       Rebin an N-dimensional array to newly specified dimensions.  Specifying
68       `Norm' keeps the sum constant, otherwise the intensities are kept
69       constant.  If more template dimensions are given than for the input
70       pdl, these dimensions are created; if less, the final dimensions are
71       maintained as they were.
72
73       So if $a is a 10 x 10 pdl, then "rebin($a,15)" is a 15 x 10 pdl, while
74       "rebin($a,15,16,17)" is a 15 x 16 x 17 pdl (where the values along the
75       final dimension are all identical).
76
77       Expansion is performed by sampling; reduction is performed by
78       averaging.  If you want different behavior, use PDL::Transform::map
79       instead.  PDL::Transform::map runs slower but is more flexible.
80
81       rebin does not process bad values.  It will set the bad-value flag of
82       all output piddles if the flag is set for any of the input piddles.
83
84   circ_mean_p
85       Calculates the circular mean of an n-dim image and returns the
86       projection. Optionally takes the center to be used.
87
88          $cmean=circ_mean_p($im);
89          $cmean=circ_mean_p($im,{Center => [10,10]});
90
91   circ_mean
92       Smooths an image by applying circular mean.  Optionally takes the
93       center to be used.
94
95          circ_mean($im);
96          circ_mean($im,{Center => [10,10]});
97
98   kernctr
99       `centre' a kernel (auxiliary routine to fftconvolve)
100
101               $kernel = kernctr($image,$smallk);
102               fftconvolve($image,$kernel);
103
104       kernctr centres a small kernel to emulate the behaviour of the direct
105       convolution routines.
106
107   convolveND
108         Signature: (k0(); SV *k; SV *aa; SV *a)
109
110       Speed-optimized convolution with selectable boundary conditions
111
112       $new = convolveND($a, $kernel, [ {options} ]);
113
114       Conolve an array with a kernel, both of which are N-dimensional.
115
116       If the kernel has fewer dimensions than the array, then the extra array
117       dimensions are threaded over.  There are options that control the
118       boundary conditions and method used.
119
120       The kernel's origin is taken to be at the kernel's center.  If your
121       kernel has a dimension of even order then the origin's coordinates get
122       rounded up to the next higher pixel (e.g. (1,2) for a 3x4 kernel).
123       This mimics the behavior of the earlier convolve and fftconvolve
124       routines, so convolveND is a drop-in replacement for them.
125
126       The kernel may be any size compared to the image, in any dimension.
127
128       The kernel and the array are not quite interchangeable (as in
129       mathematical convolution): the code is inplace-aware only for the array
130       itself, and the only allowed boundary condition on the kernel is
131       truncation.
132
133       convolveND is inplace-aware: say "convolveND(inplace $a ,$k)" to modify
134       a variable in-place.  You don't reduce the working memory that way --
135       only the final memory.
136
137       OPTIONS
138
139       Options are parsed by PDL::Options, so unique abbreviations are
140       accepted.
141
142       boundary (default: 'truncate')
143          The boundary condition on the array, which affects any pixel closer
144          to the edge than the half-width of the kernel.
145
146          The boundary conditions are the same as those accepted by range,
147          because this option is passed directly into range.  Useful options
148          are 'truncate' (the default), 'extend', and 'periodic'.  You can
149          select different boundary conditions for different axes -- see range
150          for more detail.
151
152          The (default) truncate option marks all the near-boundary pixels as
153          BAD if you have bad values compiled into your PDL and the array's
154          badflag is set.
155
156       method (default: 'auto')
157          The method to use for the convolution.  Acceptable alternatives are
158          'direct', 'fft', or 'auto'.  The direct method is an explicit copy-
159          and-multiply operation; the fft method takes the Fourier transform
160          of the input and output kernels.  The two methods give the same
161          answer to within double-precision numerical roundoff.  The fft
162          method is much faster for large kernels; the direct method is faster
163          for tiny kernels.  The tradeoff occurs when the array has about 400x
164          more pixels than the kernel.
165
166          The default method is 'auto', which chooses direct or fft
167          convolution based on the size of the input arrays.
168
169       NOTES
170
171       At the moment there's no way to thread over kernels.  That could/should
172       be fixed.
173
174       The threading over input is cheesy and should probably be fixed:
175       currently the kernel just gets dummy dimensions added to it to match
176       the input dims.  That does the right thing tersely but probably runs
177       slower than a dedicated threadloop.
178
179       The direct copying code uses PP primarily for the generic typing: it
180       includes its own threadloops.
181
182       convolveND does not process bad values.  It will set the bad-value flag
183       of all output piddles if the flag is set for any of the input piddles.
184

AUTHORS

186       Copyright (C) Karl Glazebrook and Craig DeForest, 1997, 2003 All rights
187       reserved. There is no warranty. You are allowed to redistribute this
188       software / documentation under certain conditions. For details, see the
189       file COPYING in the PDL distribution. If this file is separated from
190       the PDL distribution, the copyright notice should be included in the
191       file.
192
193
194
195perl v5.28.0                      2018-07-23                        ImageND(3)
Impressum