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

AUTHORS

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