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-2024 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 
166 BN_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);
171 BN_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 
178 BN_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);
183 BN_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 
190 BN_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);
195 BN_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 
201 BN_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);
205 BN_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 
211 BN_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);
215 BN_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 
222 BN_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);
226 BN_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 
233 BN_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);
238 BN_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 
245 BN_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);
250 BN_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 
257 BN_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);
262 BN_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 
269 BN_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);
274 BN_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 
281 BN_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);
286 BN_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 
293 BN_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);
298 BN_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 
306 BN_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);
312 BN_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 
320 BN_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);
326 BN_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 
334 BN_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);
340 BN_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 
348 BN_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);
354 BN_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 
362 BN_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);
368 BN_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 
376 BN_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);
382 BN_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)