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

AUTHORS

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