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 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 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 ndarrays if the flag is set for any of the input
42 ndarrays.
43 ninterpol()
45 N-dimensional interpolation routine
46 Signature: ninterpol(point(),data(n),[o]value())
48 $value = ninterpol($point, $data);
50 "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 See also interpND, which includes boundary conditions and allows you to
58 switch the method of interpolation, but which runs somewhat slower.
59 rebin
61 Signature: (a(m); [o]b(n); int ns => n)
62 N-dimensional rebinning algorithm
64 $new = rebin $x, $dim1, $dim2,..;.
66 $new = rebin $x, $template;
67 $new = rebin $x, $template, {Norm => 1};
68 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 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 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 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 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 $cmean=circ_mean_p($im);
91 $cmean=circ_mean_p($im,{Center => [10,10]});
92 circ_mean
94 Smooths an image by applying circular mean. Optionally takes the
95 center to be used.
96 circ_mean($im);
98 circ_mean($im,{Center => [10,10]});
99 kernctr
101 `centre' a kernel (auxiliary routine to fftconvolve)
102 $kernel = kernctr($image,$smallk);
104 fftconvolve($image,$kernel);
105 kernctr centres a small kernel to emulate the behaviour of the direct
107 convolution routines.
108 convolveND
110 Signature: (k0(); SV *k; SV *aa; SV *a)
111 Speed-optimized convolution with selectable boundary conditions
113 $new = convolveND($x, $kernel, [ {options} ]);
115 Conolve an array with a kernel, both of which are N-dimensional.
117 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 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 The kernel may be any size compared to the image, in any dimension.
129 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 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 OPTIONS
140 Options are parsed by PDL::Options, so unique abbreviations are
142 accepted.
143 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 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 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 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 The default method is 'auto', which chooses direct or fft
169 convolution based on the size of the input arrays.
170 NOTES
172 At the moment there's no way to broadcast over kernels. That
174 could/should be fixed.
175 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 The direct copying code uses PP primarily for the generic typing: it
182 includes its own broadcastloops.
183 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
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.
195perl v5.36.0 2023-01-20 ImageND(3)