BRL-CAD
wavelet.h
Go to the documentation of this file.
1/* W A V E L E T . H
2 * BRL-CAD
3 *
4 * Copyright (c) 2004-2023 United States Government as represented by
5 * the U.S. Army Research Laboratory.
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public License
9 * version 2.1 as published by the Free Software Foundation.
10 *
11 * This library is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this file; see the file named COPYING for more
18 * information.
19 */
20
21/*----------------------------------------------------------------------*/
22/** @addtogroup bn_wavelet
23 *
24 * @brief
25 * This is a standard wavelet library that takes a given data buffer of some data
26 * type and then performs a wavelet transform on that data.
27 *
28 * The transform
29 * operations available are to either decompose or reconstruct a signal into its
30 * corresponding wavelet form based on the haar wavelet.
31 *
32 * Wavelet decompose/reconstruct operations
33 *
34 * - bn_wlt_haar_1d_double_decompose(tbuffer, buffer, dimen, channels, limit)
35 * - bn_wlt_haar_1d_float_decompose (tbuffer, buffer, dimen, channels, limit)
36 * - bn_wlt_haar_1d_char_decompose (tbuffer, buffer, dimen, channels, limit)
37 * - bn_wlt_haar_1d_short_decompose (tbuffer, buffer, dimen, channels, limit)
38 * - bn_wlt_haar_1d_int_decompose (tbuffer, buffer, dimen, channels, limit)
39 * - bn_wlt_haar_1d_long_decompose (tbuffer, buffer, dimen, channels, limit)
40 *
41 * - bn_wlt_haar_1d_double_reconstruct(tbuffer, buffer, dimen, channels, sub_sz, limit)
42 * - bn_wlt_haar_1d_float_reconstruct (tbuffer, buffer, dimen, channels, sub_sz, limit)
43 * - bn_wlt_haar_1d_char_reconstruct (tbuffer, buffer, dimen, channels, sub_sz, limit)
44 * - bn_wlt_haar_1d_short_reconstruct (tbuffer, buffer, dimen, channels, sub_sz, limit)
45 * - bn_wlt_haar_1d_int_reconstruct (tbuffer, buffer, dimen, channels, sub_sz, limit)
46 * - bn_wlt_haar_1d_long_reconstruct (tbuffer, buffer, dimen, channels, sub_sz, limit)
47 *
48 * - bn_wlt_haar_2d_double_decompose(tbuffer, buffer, dimen, channels, limit)
49 * - bn_wlt_haar_2d_float_decompose (tbuffer, buffer, dimen, channels, limit)
50 * - bn_wlt_haar_2d_char_decompose (tbuffer, buffer, dimen, channels, limit)
51 * - bn_wlt_haar_2d_short_decompose (tbuffer, buffer, dimen, channels, limit)
52 * - bn_wlt_haar_2d_int_decompose (tbuffer, buffer, dimen, channels, limit)
53 * - bn_wlt_haar_2d_long_decompose (tbuffer, buffer, dimen, channels, limit)
54 *
55 * - bn_wlt_haar_2d_double_reconstruct(tbuffer, buffer, dimen, channels, sub_sz, limit)
56 * - bn_wlt_haar_2d_float_reconstruct (tbuffer, buffer, dimen, channels, sub_sz, limit)
57 * - bn_wlt_haar_2d_char_reconstruct (tbuffer, buffer, dimen, channels, sub_sz, limit)
58 * - bn_wlt_haar_2d_short_reconstruct (tbuffer, buffer, dimen, channels, sub_sz, limit)
59 * - bn_wlt_haar_2d_int_reconstruct (tbuffer, buffer, dimen, channels, sub_sz, limit)
60 * - bn_wlt_haar_2d_long_reconstruct (tbuffer, buffer, dimen, channels, sub_sz, limit)
61 *
62 * - bn_wlt_haar_2d_double_decompose2(tbuffer, buffer, width, height, channels, limit)
63 * - bn_wlt_haar_2d_float_decompose2 (tbuffer, buffer, width, height, channels, limit)
64 * - bn_wlt_haar_2d_char_decompose2 (tbuffer, buffer, width, height, channels, limit)
65 * - bn_wlt_haar_2d_short_decompose2 (tbuffer, buffer, width, height, channels, limit)
66 * - bn_wlt_haar_2d_int_decompose2 (tbuffer, buffer, width, height, channels, limit)
67 * - bn_wlt_haar_2d_long_decompose2 (tbuffer, buffer, width, height, channels, limit)
68 *
69 * - bn_wlt_haar_2d_double_reconstruct2(tbuffer, buffer, width, height, channels, sub_sz, limit)
70 * - bn_wlt_haar_2d_float_reconstruct2 (tbuffer, buffer, width, height, channels, sub_sz, limit)
71 * - bn_wlt_haar_2d_char_reconstruct2 (tbuffer, buffer, width, height, channels, sub_sz, limit)
72 * - bn_wlt_haar_2d_short_reconstruct2 (tbuffer, buffer, width, height, channels, sub_sz, limit)
73 * - bn_wlt_haar_2d_int_reconstruct2 (tbuffer, buffer, width, height, channels, sub_sz, limit)
74 * - bn_wlt_haar_2d_long_reconstruct2 (tbuffer, buffer, width, height, channels, sub_sz, limit)
75 *
76 *
77 * For greatest accuracy, it is preferable to convert everything to "double"
78 * and decompose/reconstruct with that. However, there are useful
79 * properties to performing the decomposition and/or reconstruction in
80 * various data types (most notably char).
81 *
82 * Rather than define all of these routines explicitly, we define
83 * 2 macros "decompose" and "reconstruct" which embody the structure of
84 * the function (which is common to all of them). We then instantiate
85 * these macros once for each of the data types. It's ugly, but it
86 * assures that a change to the structure of one operation type
87 * (decompose or reconstruct) occurs for all data types.
88 *
89 *
90 *
91 *
92 * bn_wlt_haar_1d_*_decompose(tbuffer, buffer, dimen, channels, limit)
93 * @par Parameters:
94 * - tbuffer a temporary data buffer 1/2 as large as "buffer". See (1) below.
95 * - buffer pointer to the data to be decomposed
96 * - dimen the number of samples in the data buffer
97 * - channels the number of values per sample
98 * - limit the extent of the decomposition
99 *
100 * Perform a Haar wavelet decomposition on the data in buffer "buffer". The
101 * decomposition is done "in place" on the data, hence the values in "buffer"
102 * are not preserved, but rather replaced by their decomposition.
103 * The number of original samples in the buffer (parameter "dimen") and the
104 * decomposition limit ("limit") must both be a power of 2 (e.g. 512, 1024).
105 * The buffer is decomposed into "average" and "detail" halves until the
106 * size of the "average" portion reaches "limit". Simultaneous
107 * decomposition of multi-plane (e.g. pixel) data, can be performed by
108 * indicating the number of planes in the "channels" parameter.
109 *
110 * (1) The process requires a temporary buffer which is 1/2 the size of the
111 * longest span to be decomposed. If the "tbuffer" argument is non-null then
112 * it is a pointer to a temporary buffer. If the pointer is NULL, then a
113 * local temporary buffer will be allocated (and freed).
114 *
115 * @par Examples:
116 @code
117 double dbuffer[512], cbuffer[256];
118 ...
119 bn_wlt_haar_1d_double_decompose(cbuffer, dbuffer, 512, 1, 1);
120 @endcode
121 *
122 * performs complete decomposition on the data in array "dbuffer".
123 *
124 @code
125 double buffer[3][512]; /_* 512 samples, 3 values/sample (e.g. RGB?)*_/
126 double tbuffer[3][256]; /_* the temporary buffer *_/
127 ...
128 bn_wlt_haar_1d_double_decompose(tbuffer, buffer, 512, 3, 1);
129 @endcode
130 *
131 * This will completely decompose the data in buffer. The first sample will
132 * be the average of all the samples. Alternatively:
133 *
134 * bn_wlt_haar_1d_double_decompose(tbuffer, buffer, 512, 3, 64);
135 *
136 * decomposes buffer into a 64-sample "average image" and 3 "detail" sets.
137 *
138 * bn_wlt_haar_1d_*_reconstruct(tbuffer, buffer, dimen, channels, sub_sz, limit)
139 *
140 */
141/** @{ */
142/** @file wavelet.h */
143
144#ifndef BN_WAVELET_H
145#define BN_WAVELET_H
146
147#include "common.h"
148#include <stdio.h> /* For FILE */
149#include "bn/defines.h"
150
151__BEGIN_DECLS
152
153#define CK_POW_2(dimen) { \
154 register size_t j; \
155 register size_t ok; \
156 for (ok=0, j=0; j < sizeof(size_t) * 8; j++) { \
157 if ((size_t)(1<<j) == dimen) { ok = 1; break; } \
158 } \
159 if (! ok) { \
160 bu_log("%s:%d value %ld should be power of 2 (2^%ld)\n", \
161 __FILE__, __LINE__, (long)dimen, (long)j); \
162 bu_bomb("CK_POW_2"); \
163 } \
164 }
165
166BN_EXPORT extern void bn_wlt_haar_1d_double_decompose(double *tbuf,
167 double *buf,
168 size_t dimen,
169 size_t depth,
170 size_t limit);
171BN_EXPORT extern void bn_wlt_haar_1d_double_reconstruct(double *tbuf,
172 double *buf,
173 size_t dimen,
174 size_t depth,
175 size_t subimage_size,
176 size_t limit);
177
178BN_EXPORT extern void bn_wlt_haar_1d_float_decompose(float *tbuf,
179 float *buf,
180 size_t dimen,
181 size_t depth,
182 size_t limit);
183BN_EXPORT extern void bn_wlt_haar_1d_float_reconstruct(float *tbuf,
184 float *buf,
185 size_t dimen,
186 size_t depth,
187 size_t subimage_size,
188 size_t limit);
189
190BN_EXPORT extern void bn_wlt_haar_1d_char_decompose(char *tbuf,
191 char *buf,
192 size_t dimen,
193 size_t depth,
194 size_t limit);
195BN_EXPORT extern void bn_wlt_haar_1d_char_reconstruct(char *tbuf, char *buf,
196 size_t dimen,
197 size_t depth,
198 size_t subimage_size,
199 size_t limit);
200
201BN_EXPORT extern void bn_wlt_haar_1d_short_decompose(short *tbuf, short *buf,
202 size_t dimen,
203 size_t depth,
204 size_t limit);
205BN_EXPORT extern void bn_wlt_haar_1d_short_reconstruct(short *tbuf, short *buf,
206 size_t dimen,
207 size_t depth,
208 size_t subimage_size,
209 size_t limit);
210
211BN_EXPORT extern void bn_wlt_haar_1d_int_decompose(int *tbuf, int *buf,
212 size_t dimen,
213 size_t depth,
214 size_t limit);
215BN_EXPORT extern void bn_wlt_haar_1d_int_reconstruct(int *tbuf,
216 int *buf,
217 size_t dimen,
218 size_t depth,
219 size_t subimage_size,
220 size_t limit);
221
222BN_EXPORT extern void bn_wlt_haar_1d_long_decompose(long *tbuf, long *buf,
223 size_t dimen,
224 size_t depth,
225 size_t limit);
226BN_EXPORT extern void bn_wlt_haar_1d_long_reconstruct(long *tbuf, long *buf,
227 size_t dimen,
228 size_t depth,
229 size_t subimage_size,
230 size_t limit);
231
232
233BN_EXPORT extern void bn_wlt_haar_2d_double_decompose(double *tbuf,
234 double *buf,
235 size_t dimen,
236 size_t depth,
237 size_t limit);
238BN_EXPORT extern void bn_wlt_haar_2d_double_reconstruct(double *tbuf,
239 double *buf,
240 size_t dimen,
241 size_t depth,
242 size_t subimage_size,
243 size_t limit);
244
245BN_EXPORT extern void bn_wlt_haar_2d_float_decompose(float *tbuf,
246 float *buf,
247 size_t dimen,
248 size_t depth,
249 size_t limit);
250BN_EXPORT extern void bn_wlt_haar_2d_float_reconstruct(float *tbuf,
251 float *buf,
252 size_t dimen,
253 size_t depth,
254 size_t subimage_size,
255 size_t limit);
256
257BN_EXPORT extern void bn_wlt_haar_2d_char_decompose(char *tbuf,
258 char *buf,
259 size_t dimen,
260 size_t depth,
261 size_t limit);
262BN_EXPORT extern void bn_wlt_haar_2d_char_reconstruct(char *tbuf,
263 char *buf,
264 size_t dimen,
265 size_t depth,
266 size_t subimage_size,
267 size_t limit);
268
269BN_EXPORT extern void bn_wlt_haar_2d_short_decompose(short *tbuf,
270 short *buf,
271 size_t dimen,
272 size_t depth,
273 size_t limit);
274BN_EXPORT extern void bn_wlt_haar_2d_short_reconstruct(short *tbuf,
275 short *buf,
276 size_t dimen,
277 size_t depth,
278 size_t subimage_size,
279 size_t limit);
280
281BN_EXPORT extern void bn_wlt_haar_2d_int_decompose(int *tbuf,
282 int *buf,
283 size_t dimen,
284 size_t depth,
285 size_t limit);
286BN_EXPORT extern void bn_wlt_haar_2d_int_reconstruct(int *tbuf,
287 int *buf,
288 size_t dimen,
289 size_t depth,
290 size_t subimage_size,
291 size_t limit);
292
293BN_EXPORT extern void bn_wlt_haar_2d_long_decompose(long *tbuf,
294 long *buf,
295 size_t dimen,
296 size_t depth,
297 size_t limit);
298BN_EXPORT extern void bn_wlt_haar_2d_long_reconstruct(long *tbuf,
299 long *buf,
300 size_t dimen,
301 size_t depth,
302 size_t subimage_size,
303 size_t limit);
304
305
306BN_EXPORT extern void bn_wlt_haar_2d_double_decompose2(double *tbuf,
307 double *buf,
308 size_t dimen,
309 size_t width,
310 size_t height,
311 size_t limit);
312BN_EXPORT extern void bn_wlt_haar_2d_double_reconstruct2(double *tbuf,
313 double *buf,
314 size_t dimen,
315 size_t width,
316 size_t height,
317 size_t subimage_size,
318 size_t limit);
319
320BN_EXPORT extern void bn_wlt_haar_2d_float_decompose2(float *tbuf,
321 float *buf,
322 size_t dimen,
323 size_t width,
324 size_t height,
325 size_t limit);
326BN_EXPORT extern void bn_wlt_haar_2d_float_reconstruct2(float *tbuf,
327 float *buf,
328 size_t dimen,
329 size_t width,
330 size_t height,
331 size_t subimage_size,
332 size_t limit);
333
334BN_EXPORT extern void bn_wlt_haar_2d_char_decompose2(char *tbuf,
335 char *buf,
336 size_t dimen,
337 size_t width,
338 size_t height,
339 size_t limit);
340BN_EXPORT extern void bn_wlt_haar_2d_char_reconstruct2(char *tbuf,
341 char *buf,
342 size_t dimen,
343 size_t width,
344 size_t height,
345 size_t subimage_size,
346 size_t limit);
347
348BN_EXPORT extern void bn_wlt_haar_2d_short_decompose2(short *tbuf,
349 short *buf,
350 size_t dimen,
351 size_t width,
352 size_t height,
353 size_t limit);
354BN_EXPORT extern void bn_wlt_haar_2d_short_reconstruct2(short *tbuf,
355 short *buf,
356 size_t dimen,
357 size_t width,
358 size_t height,
359 size_t subimage_size,
360 size_t limit);
361
362BN_EXPORT extern void bn_wlt_haar_2d_int_decompose2(int *tbuf,
363 int *buf,
364 size_t dimen,
365 size_t width,
366 size_t height,
367 size_t limit);
368BN_EXPORT extern void bn_wlt_haar_2d_int_reconstruct2(int *tbuf,
369 int *buf,
370 size_t dimen,
371 size_t width,
372 size_t height,
373 size_t subimage_size,
374 size_t limit);
375
376BN_EXPORT extern void bn_wlt_haar_2d_long_decompose2(long *tbuf,
377 long *buf,
378 size_t dimen,
379 size_t width,
380 size_t height,
381 size_t limit);
382BN_EXPORT extern void bn_wlt_haar_2d_long_reconstruct2(long *tbuf,
383 long *buf,
384 size_t dimen,
385 size_t width,
386 size_t height,
387 size_t subimage_size,
388 size_t limit);
389
390__END_DECLS
391
392#endif /* BN_WAVELET_H */
393/** @} */
394/*
395 * Local Variables:
396 * mode: C
397 * tab-width: 8
398 * indent-tabs-mode: t
399 * c-file-style: "stroustrup"
400 * End:
401 * ex: shiftwidth=4 tabstop=8
402 */
common.h
Header file for the BRL-CAD common definitions.
bn_wlt_haar_2d_float_decompose
void bn_wlt_haar_2d_float_decompose(float *tbuf, float *buf, size_t dimen, size_t depth, size_t limit)
bn_wlt_haar_2d_double_decompose
void bn_wlt_haar_2d_double_decompose(double *tbuf, double *buf, size_t dimen, size_t depth, size_t limit)
bn_wlt_haar_2d_double_reconstruct
void bn_wlt_haar_2d_double_reconstruct(double *tbuf, double *buf, size_t dimen, size_t depth, size_t subimage_size, size_t limit)
bn_wlt_haar_2d_int_reconstruct
void bn_wlt_haar_2d_int_reconstruct(int *tbuf, int *buf, size_t dimen, size_t depth, size_t subimage_size, size_t limit)
bn_wlt_haar_1d_char_reconstruct
void bn_wlt_haar_1d_char_reconstruct(char *tbuf, char *buf, size_t dimen, size_t depth, size_t subimage_size, size_t limit)
bn_wlt_haar_1d_double_reconstruct
void bn_wlt_haar_1d_double_reconstruct(double *tbuf, double *buf, size_t dimen, size_t depth, size_t subimage_size, size_t limit)
bn_wlt_haar_2d_int_decompose2
void bn_wlt_haar_2d_int_decompose2(int *tbuf, int *buf, size_t dimen, size_t width, size_t height, size_t limit)
bn_wlt_haar_2d_float_reconstruct2
void bn_wlt_haar_2d_float_reconstruct2(float *tbuf, float *buf, size_t dimen, size_t width, size_t height, size_t subimage_size, size_t limit)
bn_wlt_haar_2d_char_reconstruct
void bn_wlt_haar_2d_char_reconstruct(char *tbuf, char *buf, size_t dimen, size_t depth, size_t subimage_size, size_t limit)
bn_wlt_haar_2d_long_reconstruct
void bn_wlt_haar_2d_long_reconstruct(long *tbuf, long *buf, size_t dimen, size_t depth, size_t subimage_size, size_t limit)
bn_wlt_haar_2d_double_reconstruct2
void bn_wlt_haar_2d_double_reconstruct2(double *tbuf, double *buf, size_t dimen, size_t width, size_t height, size_t subimage_size, size_t limit)
bn_wlt_haar_1d_float_reconstruct
void bn_wlt_haar_1d_float_reconstruct(float *tbuf, float *buf, size_t dimen, size_t depth, size_t subimage_size, size_t limit)
bn_wlt_haar_1d_char_decompose
void bn_wlt_haar_1d_char_decompose(char *tbuf, char *buf, size_t dimen, size_t depth, size_t limit)
bn_wlt_haar_2d_short_decompose2
void bn_wlt_haar_2d_short_decompose2(short *tbuf, short *buf, size_t dimen, size_t width, size_t height, size_t limit)
bn_wlt_haar_2d_short_reconstruct2
void bn_wlt_haar_2d_short_reconstruct2(short *tbuf, short *buf, size_t dimen, size_t width, size_t height, size_t subimage_size, size_t limit)
bn_wlt_haar_1d_long_reconstruct
void bn_wlt_haar_1d_long_reconstruct(long *tbuf, long *buf, size_t dimen, size_t depth, size_t subimage_size, size_t limit)
bn_wlt_haar_1d_short_reconstruct
void bn_wlt_haar_1d_short_reconstruct(short *tbuf, short *buf, size_t dimen, size_t depth, size_t subimage_size, size_t limit)
bn_wlt_haar_2d_short_reconstruct
void bn_wlt_haar_2d_short_reconstruct(short *tbuf, short *buf, size_t dimen, size_t depth, size_t subimage_size, size_t limit)
bn_wlt_haar_2d_long_reconstruct2
void bn_wlt_haar_2d_long_reconstruct2(long *tbuf, long *buf, size_t dimen, size_t width, size_t height, size_t subimage_size, size_t limit)
bn_wlt_haar_1d_int_reconstruct
void bn_wlt_haar_1d_int_reconstruct(int *tbuf, int *buf, size_t dimen, size_t depth, size_t subimage_size, size_t limit)
bn_wlt_haar_2d_short_decompose
void bn_wlt_haar_2d_short_decompose(short *tbuf, short *buf, size_t dimen, size_t depth, size_t limit)
bn_wlt_haar_2d_char_decompose
void bn_wlt_haar_2d_char_decompose(char *tbuf, char *buf, size_t dimen, size_t depth, size_t limit)
bn_wlt_haar_2d_double_decompose2
void bn_wlt_haar_2d_double_decompose2(double *tbuf, double *buf, size_t dimen, size_t width, size_t height, size_t limit)
bn_wlt_haar_2d_float_decompose2
void bn_wlt_haar_2d_float_decompose2(float *tbuf, float *buf, size_t dimen, size_t width, size_t height, size_t limit)
bn_wlt_haar_2d_float_reconstruct
void bn_wlt_haar_2d_float_reconstruct(float *tbuf, float *buf, size_t dimen, size_t depth, size_t subimage_size, size_t limit)
bn_wlt_haar_2d_char_reconstruct2
void bn_wlt_haar_2d_char_reconstruct2(char *tbuf, char *buf, size_t dimen, size_t width, size_t height, size_t subimage_size, size_t limit)
bn_wlt_haar_1d_short_decompose
void bn_wlt_haar_1d_short_decompose(short *tbuf, short *buf, size_t dimen, size_t depth, size_t limit)
bn_wlt_haar_2d_long_decompose
void bn_wlt_haar_2d_long_decompose(long *tbuf, long *buf, size_t dimen, size_t depth, size_t limit)
bn_wlt_haar_1d_long_decompose
void bn_wlt_haar_1d_long_decompose(long *tbuf, long *buf, size_t dimen, size_t depth, size_t limit)
bn_wlt_haar_1d_double_decompose
void bn_wlt_haar_1d_double_decompose(double *tbuf, double *buf, size_t dimen, size_t depth, size_t limit)
bn_wlt_haar_1d_int_decompose
void bn_wlt_haar_1d_int_decompose(int *tbuf, int *buf, size_t dimen, size_t depth, size_t limit)
bn_wlt_haar_2d_long_decompose2
void bn_wlt_haar_2d_long_decompose2(long *tbuf, long *buf, size_t dimen, size_t width, size_t height, size_t limit)
bn_wlt_haar_1d_float_decompose
void bn_wlt_haar_1d_float_decompose(float *tbuf, float *buf, size_t dimen, size_t depth, size_t limit)
bn_wlt_haar_2d_char_decompose2
void bn_wlt_haar_2d_char_decompose2(char *tbuf, char *buf, size_t dimen, size_t width, size_t height, size_t limit)
bn_wlt_haar_2d_int_reconstruct2
void bn_wlt_haar_2d_int_reconstruct2(int *tbuf, int *buf, size_t dimen, size_t width, size_t height, size_t subimage_size, size_t limit)
bn_wlt_haar_2d_int_decompose
void bn_wlt_haar_2d_int_decompose(int *tbuf, int *buf, size_t dimen, size_t depth, size_t limit)