1ImageND(3) User Contributed Perl Documentation ImageND(3)
2
6 PDL::ImageND - useful image processing in N dimensions
7
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 ImageND is not a part of the PDL core (v2.4) and hence must be
15 explicitly loaded.
16
18 use PDL::ImageND;
19 $y = $x->convolveND($kernel,{bound=>'periodic'});
21 $y = $x->rebin(50,30,10);
22
24 convolve
25 Signature: (a(m); b(n); indx adims(p); indx bdims(q); [o]c(m))
26 N-dimensional convolution (Deprecated; use convolveND)
28 $new = convolve $x, $kernel
30 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 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 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 ninterpol()
44 N-dimensional interpolation routine
45 Signature: ninterpol(point(),data(n),[o]value())
47 $value = ninterpol($point, $data);
49 "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 See also interpND, which includes boundary conditions and allows you to
57 switch the method of interpolation, but which runs somewhat slower.
58 rebin
60 Signature: (a(m); [o]b(n); int ns => n)
61 N-dimensional rebinning algorithm
63 $new = rebin $x, $dim1, $dim2,..;.
65 $new = rebin $x, $template;
66 $new = rebin $x, $template, {Norm => 1};
67 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 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 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 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 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 $cmean=circ_mean_p($im);
90 $cmean=circ_mean_p($im,{Center => [10,10]});
91 circ_mean
93 Smooths an image by applying circular mean. Optionally takes the
94 center to be used.
95 circ_mean($im);
97 circ_mean($im,{Center => [10,10]});
98 kernctr
100 `centre' a kernel (auxiliary routine to fftconvolve)
101 $kernel = kernctr($image,$smallk);
103 fftconvolve($image,$kernel);
104 kernctr centres a small kernel to emulate the behaviour of the direct
106 convolution routines.
107 convolveND
109 Signature: (k0(); SV *k; SV *aa; SV *a)
110 Speed-optimized convolution with selectable boundary conditions
112 $new = convolveND($x, $kernel, [ {options} ]);
114 Conolve an array with a kernel, both of which are N-dimensional.
116 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 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 The kernel may be any size compared to the image, in any dimension.
128 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 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 OPTIONS
139 Options are parsed by PDL::Options, so unique abbreviations are
141 accepted.
142 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 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 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 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 The default method is 'auto', which chooses direct or fft
168 convolution based on the size of the input arrays.
169 NOTES
171 At the moment there's no way to thread over kernels. That could/should
173 be fixed.
174 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 The direct copying code uses PP primarily for the generic typing: it
181 includes its own threadloops.
182 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
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.
193perl v5.32.1 2021-02-15 ImageND(3)