BRL-CAD
tabdata.h
Go to the documentation of this file.
1 /* T A B D A T A . H
2  * BRL-CAD
3  *
4  * Copyright (c) 2004-2014 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 /* @file tabdata.h */
23 /** @addtogroup tabdata */
24 /** @{ */
25 
26 /**
27  * Data structures to assist with recording many sets of data sampled
28  * along the same set of independent variables.
29  *
30  * The overall notion is that each sample should be as compact as
31  * possible (an array of measurements), with all the context stored in
32  * one place.
33  *
34  * These structures and support routines apply to any measured "curve"
35  * or "function" or "table" with one independent variable and one or
36  * more scalar dependent variable(s).
37  *
38  * The context is kept in an 'bn_table' structure, and the data for
39  * one particular sample are kept in an 'bn_tabdata' structure.
40  *
41  * The contents of the sample in val[j] are interpreted in the
42  * interval (wavel[j]..wavel[j+1]). This value could be power,
43  * albedo, absorption, refractive index, or any other
44  * wavelength-specific parameter.
45  *
46  * For example, if the val[] array contains power values, then val[j]
47  * contains the integral of the power from wavel[j] to wavel[j+1]
48  *
49  * As an example, assume nwave=2, wavel[0]=500, wavel[1]=600, wavel[2]=700.
50  * Then val[0] would contain data for the 500 to 600nm interval,
51  * and val[1] would contain data for the 600 to 700nm interval.
52  * There would be no storage allocated for val[2] -- don't use it!
53  * There are several interpretations of this:
54  * 1) val[j] stores the total (integral, area) value for the interval, or
55  * 2) val[j] stores the average value across the interval.
56  *
57  * The intervals need not be uniformly spaced; it is acceptable to
58  * increase wavelength sampling density around "important"
59  * frequencies.
60  *
61  */
62 
63 #ifndef BN_TABDATA_H
64 #define BN_TABDATA_H
65 
66 #include "common.h"
67 #include "bn/defines.h"
68 #include "bu/magic.h"
69 #include "bu/vls.h"
70 
72 
73 struct bn_table {
74  uint32_t magic;
75  size_t nx;
76  fastf_t x[1]; /**< @brief array of nx+1 wavelengths, dynamically sized */
77 };
78 
79 #define BN_CK_TABLE(_p) BU_CKMAG(_p, BN_TABLE_MAGIC, "bn_table")
80 #define BN_TABLE_NULL ((struct bn_table *)NULL)
81 
82 /* Gets an bn_table, with x[] having size _nx+1 */
83 #ifndef NO_BOMBING_MACROS
84 # define BN_GET_TABLE(_table, _nx) { \
85  if ((_nx) < 1) bu_bomb("RT_GET_TABLE() _nx < 1\n"); \
86  _table = (struct bn_table *)bu_calloc(1, \
87  sizeof(struct bn_table) + sizeof(fastf_t)*(_nx), \
88  "struct bn_table"); \
89  _table->magic = BN_TABLE_MAGIC; \
90  _table->nx = (_nx); }
91 #else
92 # define BN_GET_TABLE(_table, _nx) { \
93  _table = (struct bn_table *)bu_calloc(1, \
94  sizeof(struct bn_table) + sizeof(fastf_t)*(_nx), \
95  "struct bn_table"); \
96  _table->magic = BN_TABLE_MAGIC; \
97  _table->nx = (_nx); }
98 #endif
99 
100 struct bn_tabdata {
101  uint32_t magic;
102  size_t ny;
103  const struct bn_table *table; /**< @brief Up pointer to definition of X axis */
104  fastf_t y[1]; /**< @brief array of ny samples, dynamically sized */
105 };
106 #define BN_CK_TABDATA(_p) BU_CKMAG(_p, BN_TABDATA_MAGIC, "bn_tabdata")
107 #define BN_TABDATA_NULL ((struct bn_tabdata *)NULL)
108 
109 #define BN_SIZEOF_TABDATA_Y(_tabdata) sizeof(fastf_t)*((_tabdata)->ny)
110 #define BN_SIZEOF_TABDATA(_table) (sizeof(struct bn_tabdata) + \
111  sizeof(fastf_t)*((_table)->nx-1))
112 
113 /* Gets an bn_tabdata, with y[] having size _ny */
114 #define BN_GET_TABDATA(_data, _table) { \
115  BN_CK_TABLE(_table);\
116  _data = (struct bn_tabdata *)bu_calloc(1, \
117  BN_SIZEOF_TABDATA(_table), "struct bn_tabdata"); \
118  _data->magic = BN_TABDATA_MAGIC; \
119  _data->ny = (_table)->nx; \
120  _data->table = (_table); }
121 
122 /*
123  * Routines
124  */
125 
126 
127 BN_EXPORT extern void bn_table_free(struct bn_table *tabp);
128 
129 BN_EXPORT extern void bn_tabdata_free(struct bn_tabdata *data);
130 
131 BN_EXPORT extern void bn_ck_table(const struct bn_table *tabp);
132 
133 /*
134  *@brief
135  * Set up an independent "table margin" from 'first' to 'last',
136  * inclusive, using 'num' uniformly spaced samples. Num >= 1.
137  */
138 BN_EXPORT extern struct bn_table *bn_table_make_uniform(size_t num,
139  double first,
140  double last);
141 
142 /*
143  *@brief
144  * Sum the values from two data tables.
145  */
146 BN_EXPORT extern void bn_tabdata_add(struct bn_tabdata *out,
147  const struct bn_tabdata *in1,
148  const struct bn_tabdata *in2);
149 
150 /*
151  *@brief
152  * Element-by-element multiply the values from two data tables.
153  */
154 BN_EXPORT extern void bn_tabdata_mul(struct bn_tabdata *out,
155  const struct bn_tabdata *in1,
156  const struct bn_tabdata *in2);
157 
158 /*
159  *@brief
160  * Element-by-element multiply the values from three data tables.
161  */
162 BN_EXPORT extern void bn_tabdata_mul3(struct bn_tabdata *out,
163  const struct bn_tabdata *in1,
164  const struct bn_tabdata *in2,
165  const struct bn_tabdata *in3);
166 
167 /*
168  *@brief
169  * Element-by-element multiply the values from three data tables and a scalar.
170  *
171  * out += in1 * in2 * in3 * scale
172  */
173 BN_EXPORT extern void bn_tabdata_incr_mul3_scale(struct bn_tabdata *out,
174  const struct bn_tabdata *in1,
175  const struct bn_tabdata *in2,
176  const struct bn_tabdata *in3,
177  double scale);
178 
179 /*
180  *@brief
181  * Element-by-element multiply the values from two data tables and a scalar.
182  *
183  * out += in1 * in2 * scale
184  */
185 BN_EXPORT extern void bn_tabdata_incr_mul2_scale(struct bn_tabdata *out,
186  const struct bn_tabdata *in1,
187  const struct bn_tabdata *in2,
188  double scale);
189 
190 /*
191  *@brief
192  * Multiply every element in a data table by a scalar value 'scale'.
193  */
194 BN_EXPORT extern void bn_tabdata_scale(struct bn_tabdata *out,
195  const struct bn_tabdata *in1,
196  double scale);
197 
198 /*
199  *@brief
200  * Scale the independent axis of a table by 'scale'.
201  */
202 BN_EXPORT extern void bn_table_scale(struct bn_table *tabp,
203  double scale);
204 
205 /*
206  *@brief
207  * Multiply every element in data table in2 by a scalar value 'scale',
208  * add it to the element in in1, and store in 'out'.
209  * 'out' may overlap in1 or in2.
210  */
211 BN_EXPORT extern void bn_tabdata_join1(struct bn_tabdata *out,
212  const struct bn_tabdata *in1,
213  double scale,
214  const struct bn_tabdata *in2);
215 
216 /*
217  *@brief
218  * Multiply every element in data table in2 by a scalar value 'scale2',
219  * plus in3 * scale3, and
220  * add it to the element in in1, and store in 'out'.
221  * 'out' may overlap in1 or in2.
222  */
223 BN_EXPORT extern void bn_tabdata_join2(struct bn_tabdata *out,
224  const struct bn_tabdata *in1,
225  double scale2,
226  const struct bn_tabdata *in2,
227  double scale3,
228  const struct bn_tabdata *in3);
229 
230 BN_EXPORT extern void bn_tabdata_blend2(struct bn_tabdata *out,
231  double scale1,
232  const struct bn_tabdata *in1,
233  double scale2,
234  const struct bn_tabdata *in2);
235 
236 BN_EXPORT extern void bn_tabdata_blend3(struct bn_tabdata *out,
237  double scale1,
238  const struct bn_tabdata *in1,
239  double scale2,
240  const struct bn_tabdata *in2,
241  double scale3,
242  const struct bn_tabdata *in3);
243 
244 /*
245  *@brief
246  * Following interpretation #1, where y[j] stores the total (integral
247  * or area) value within the interval, return the area under the whole curve.
248  * This is simply totaling up the areas from each of the intervals.
249  */
250 BN_EXPORT extern double bn_tabdata_area1(const struct bn_tabdata *in);
251 
252 /*
253  *@brief
254  * Following interpretation #2, where y[j] stores the average
255  * value for the interval, return the area under
256  * the whole curve. Since the interval spacing need not be uniform,
257  * sum the areas of the rectangles.
258  */
259 BN_EXPORT extern double bn_tabdata_area2(const struct bn_tabdata *in);
260 
261 /*
262  *@brief
263  * Following interpretation #1, where y[j] stores the total (integral
264  * or area) value within the interval, return the area under the whole curve.
265  * This is simply totaling up the areas from each of the intervals.
266  * The curve value is found by multiplying corresponding entries from
267  * in1 and in2.
268  */
269 BN_EXPORT extern double bn_tabdata_mul_area1(const struct bn_tabdata *in1,
270  const struct bn_tabdata *in2);
271 
272 /*
273  *@brief
274  * Following interpretation #2,
275  * return the area under the whole curve.
276  * The curve value is found by multiplying corresponding entries from
277  * in1 and in2.
278  */
279 BN_EXPORT extern double bn_tabdata_mul_area2(const struct bn_tabdata *in1,
280  const struct bn_tabdata *in2);
281 
282 /*
283  *@brief
284  * Return the value of the curve at independent parameter value 'wl'.
285  * Linearly interpolate between values in the input table.
286  * Zero is returned for values outside the sampled range.
287  */
288 BN_EXPORT extern fastf_t bn_table_lin_interp(const struct bn_tabdata *samp,
289  double wl);
290 
291 /*
292  *@brief
293  * Given a set of sampled data 'olddata', resample it for different
294  * spacing, by linearly interpolating the values when an output span
295  * is entirely contained within an input span, and by taking the
296  * maximum when an output span covers more than one input span.
297  *
298  * This assumes interpretation (2) of the data, i.e. that the values
299  * are the average value across the interval.
300  */
301 BN_EXPORT extern struct bn_tabdata *bn_tabdata_resample_max(const struct bn_table *newtable,
302  const struct bn_tabdata *olddata);
303 
304 /*
305  *@brief
306  * Given a set of sampled data 'olddata', resample it for different
307  * spacing, by linearly interpolating the values when an output span
308  * is entirely contained within an input span, and by taking the
309  * average when an output span covers more than one input span.
310  *
311  * This assumes interpretation (2) of the data, i.e. that the values
312  * are the average value across the interval.
313  */
314 BN_EXPORT extern struct bn_tabdata *bn_tabdata_resample_avg(const struct bn_table *newtable,
315  const struct bn_tabdata *olddata);
316 
317 /*
318  *@brief
319  * Write out the table structure in an ASCII file,
320  * giving the number of values (minus 1), and the
321  * actual values.
322  */
323 BN_EXPORT extern int bn_table_write(const char *filename,
324  const struct bn_table *tabp);
325 
326 /*
327  *@brief
328  * Allocate and read in the independent variable values from an ASCII file,
329  * giving the number of samples (minus 1), and the
330  * actual values.
331  */
332 BN_EXPORT extern struct bn_table *bn_table_read(const char *filename);
333 
334 BN_EXPORT extern void bn_pr_table(const char *title,
335  const struct bn_table *tabp);
336 
337 BN_EXPORT extern void bn_pr_tabdata(const char *title,
338  const struct bn_tabdata *data);
339 
340 /*
341  *@brief
342  * Write out a given data table into an ASCII file,
343  * suitable for input to GNUPLOT.
344  *
345  * (set term postscript)
346  * (set output "|print-postscript")
347  * (plot "filename" with lines)
348  */
349 BN_EXPORT extern int bn_print_table_and_tabdata(const char *filename,
350  const struct bn_tabdata *data);
351 
352 /*
353  *@brief
354  * Read in a file which contains two columns of numbers, the first
355  * column being the wavelength, the second column being the sample value
356  * at that wavelength.
357  *
358  * A new bn_table structure and one bn_tabdata structure
359  * are created, a pointer to the bn_tabdata structure is returned.
360  * The final wavelength is guessed at.
361  */
362 BN_EXPORT extern struct bn_tabdata *bn_read_table_and_tabdata(const char *filename);
363 
364 BN_EXPORT extern struct bn_tabdata *bn_tabdata_binary_read(const char *filename,
365  size_t num,
366  const struct bn_table *tabp);
367 
368 /*
369  *@brief
370  * Allocate storage for, and initialize, an array of 'num' data table
371  * structures.
372  * This subroutine is provided because the bn_tabdata structures
373  * are variable length.
374  */
375 BN_EXPORT extern struct bn_tabdata *bn_tabdata_malloc_array(const struct bn_table *tabp,
376  size_t num);
377 
378 BN_EXPORT extern void bn_tabdata_copy(struct bn_tabdata *out,
379  const struct bn_tabdata *in);
380 
381 BN_EXPORT extern struct bn_tabdata *bn_tabdata_dup(const struct bn_tabdata *in);
382 
383 /*
384  *@brief
385  * For a given table, allocate and return a tabdata structure
386  * with all elements initialized to 'val'.
387  */
388 BN_EXPORT extern struct bn_tabdata *bn_tabdata_get_constval(double val,
389  const struct bn_table *tabp);
390 
391 /*
392  *@brief
393  * Set all the tabdata elements to 'val'
394  */
395 BN_EXPORT extern void bn_tabdata_constval(struct bn_tabdata *data,
396  double val);
397 
398 /*
399  *@brief
400  * Convert an bn_tabdata/bn_table pair into a Tcl compatible string
401  * appended to a VLS. It will have form:
402  * x {...} y {...} nx # ymin # ymax #
403  */
404 BN_EXPORT extern void bn_tabdata_to_tcl(struct bu_vls *vp,
405  const struct bn_tabdata *data);
406 
407 /*
408  *@brief
409  * Given an array of (x, y) pairs, build the relevant bn_table and
410  * bn_tabdata structures.
411  *
412  * The table is terminated by an x value <= 0.
413  * Consistent with the interpretation of the spans,
414  * invent a final span ending x value.
415  */
416 BN_EXPORT extern struct bn_tabdata *bn_tabdata_from_array(const double *array);
417 
418 /*
419  *@brief
420  * Shift the data by a constant offset in the independent variable
421  * (often frequency), interpolating new sample values.
422  */
423 BN_EXPORT extern void bn_tabdata_freq_shift(struct bn_tabdata *out,
424  const struct bn_tabdata *in,
425  double offset);
426 
427 /*
428  *@brief
429  * Returns number of sample points between 'low' and 'hi', inclusive.
430  */
431 BN_EXPORT extern int bn_table_interval_num_samples(const struct bn_table *tabp,
432  double low,
433  double hi);
434 
435 /*
436  *@brief
437  * Remove all sampling points between subscripts i and j, inclusive.
438  * Don't bother freeing the tiny bit of storage at the end of the array.
439  * Returns number of points removed.
440  */
441 BN_EXPORT extern int bn_table_delete_sample_pts(struct bn_table *tabp,
442  unsigned int i,
443  unsigned int j);
444 
445 /*
446  *@brief
447  * A new table is returned which has sample points at places from
448  * each of the input tables.
449  */
450 BN_EXPORT extern struct bn_table *bn_table_merge2(const struct bn_table *a,
451  const struct bn_table *b);
452 
453 /*
454  *@brief
455  * Create a filter to accept power in a given band.
456  * The first and last filter values will be in the range 0..1,
457  * while all the internal filter values will be 1.0,
458  * and all samples outside the given band will be 0.0.
459  *
460  *
461  * @return NULL if given band does not overlap input spectrum
462  * @return tabdata*
463  */
464 BN_EXPORT extern struct bn_tabdata *bn_tabdata_mk_linear_filter(const struct bn_table *spectrum,
465  double lower_wavelen,
466  double upper_wavelen);
467 
469 
470 #endif /* BN_TABDATA_H */
471 /** @} */
472 /*
473  * Local Variables:
474  * mode: C
475  * tab-width: 8
476  * indent-tabs-mode: t
477  * c-file-style: "stroustrup"
478  * End:
479  * ex: shiftwidth=4 tabstop=8
480  */
void bn_table_free(struct bn_table *tabp)
Definition: tabdata.c:57
Definition: db_flip.c:35
char filename[MAXLENGTH]
Definition: human.c:105
struct bn_tabdata * bn_tabdata_resample_max(const struct bn_table *newtable, const struct bn_tabdata *olddata)
Definition: tabdata.c:574
int bn_table_interval_num_samples(const struct bn_table *tabp, double low, double hi)
Definition: tabdata.c:1168
void bn_tabdata_incr_mul2_scale(struct bn_tabdata *out, const struct bn_tabdata *in1, const struct bn_tabdata *in2, double scale)
struct bn_tabdata * bn_tabdata_malloc_array(const struct bn_table *tabp, size_t num)
Definition: tabdata.c:995
void bn_tabdata_free(struct bn_tabdata *data)
Definition: tabdata.c:67
size_t ny
Definition: tabdata.h:102
int bn_table_write(const char *filename, const struct bn_table *tabp)
Definition: tabdata.c:717
void bn_tabdata_blend2(struct bn_tabdata *out, double scale1, const struct bn_tabdata *in1, double scale2, const struct bn_tabdata *in2)
Header file for the BRL-CAD common definitions.
double bn_tabdata_area2(const struct bn_tabdata *in)
Definition: tabdata.c:433
struct bn_table * bn_table_read(const char *filename)
Definition: tabdata.c:747
void bn_tabdata_copy(struct bn_tabdata *out, const struct bn_tabdata *in)
Definition: tabdata.c:1025
void bn_tabdata_blend3(struct bn_tabdata *out, double scale1, const struct bn_tabdata *in1, double scale2, const struct bn_tabdata *in2, double scale3, const struct bn_tabdata *in3)
void bn_tabdata_to_tcl(struct bu_vls *vp, const struct bn_tabdata *data)
Definition: tabdata.c:1087
COMPLEX data[64]
Definition: fftest.c:34
size_t nx
Definition: tabdata.h:75
void bn_tabdata_freq_shift(struct bn_tabdata *out, const struct bn_tabdata *in, double offset)
Definition: tabdata.c:1146
void bn_tabdata_scale(struct bn_tabdata *out, const struct bn_tabdata *in1, double scale)
fastf_t y[1]
array of ny samples, dynamically sized
Definition: tabdata.h:104
struct bn_table * bn_table_make_uniform(size_t num, double first, double last)
Definition: tabdata.c:98
#define __BEGIN_DECLS
Definition: common.h:73
void bn_table_scale(struct bn_table *tabp, double scale)
void bn_tabdata_mul(struct bn_tabdata *out, const struct bn_tabdata *in1, const struct bn_tabdata *in2)
Definition: tabdata.c:149
struct bn_tabdata * bn_tabdata_resample_avg(const struct bn_table *newtable, const struct bn_tabdata *olddata)
Definition: tabdata.c:643
struct bn_tabdata * bn_tabdata_get_constval(double val, const struct bn_table *tabp)
Definition: tabdata.c:1054
void bn_tabdata_add(struct bn_tabdata *out, const struct bn_tabdata *in1, const struct bn_tabdata *in2)
Definition: tabdata.c:123
int bn_print_table_and_tabdata(const char *filename, const struct bn_tabdata *data)
Definition: tabdata.c:830
struct bn_tabdata * bn_read_table_and_tabdata(const char *filename)
Definition: tabdata.c:863
goto out
Definition: nmg_mod.c:3846
uint32_t magic
Definition: tabdata.h:74
double bn_tabdata_mul_area2(const struct bn_tabdata *in1, const struct bn_tabdata *in2)
Definition: tabdata.c:475
struct bn_tabdata * bn_tabdata_mk_linear_filter(const struct bn_table *spectrum, double lower_wavelen, double upper_wavelen)
Definition: tabdata.c:1252
void bn_tabdata_constval(struct bn_tabdata *data, double val)
Definition: tabdata.c:1072
struct bn_tabdata * bn_tabdata_binary_read(const char *filename, size_t num, const struct bn_table *tabp)
Definition: tabdata.c:934
void bn_pr_tabdata(const char *title, const struct bn_tabdata *data)
Definition: tabdata.c:816
void bn_tabdata_incr_mul3_scale(struct bn_tabdata *out, const struct bn_tabdata *in1, const struct bn_tabdata *in2, const struct bn_tabdata *in3, double scale)
struct bn_table * bn_table_merge2(const struct bn_table *a, const struct bn_table *b)
Definition: tabdata.c:1209
double bn_tabdata_mul_area1(const struct bn_tabdata *in1, const struct bn_tabdata *in2)
Definition: tabdata.c:455
void bn_pr_table(const char *title, const struct bn_table *tabp)
Definition: tabdata.c:803
void bn_tabdata_join1(struct bn_tabdata *out, const struct bn_tabdata *in1, double scale, const struct bn_tabdata *in2)
fastf_t x[1]
array of nx+1 wavelengths, dynamically sized
Definition: tabdata.h:76
uint32_t magic
Definition: tabdata.h:101
void bn_tabdata_mul3(struct bn_tabdata *out, const struct bn_tabdata *in1, const struct bn_tabdata *in2, const struct bn_tabdata *in3)
Definition: tabdata.c:175
fastf_t bn_table_lin_interp(const struct bn_tabdata *samp, double wl)
struct bn_tabdata * bn_tabdata_dup(const struct bn_tabdata *in)
Definition: tabdata.c:1041
#define __END_DECLS
Definition: common.h:74
struct bn_tabdata * bn_tabdata_from_array(const double *array)
Definition: tabdata.c:1116
struct bn_table * spectrum
Definition: init.c:41
int bn_table_delete_sample_pts(struct bn_table *tabp, unsigned int i, unsigned int j)
Definition: tabdata.c:1184
double bn_tabdata_area1(const struct bn_tabdata *in)
Definition: tabdata.c:414
Definition: vls.h:56
double fastf_t
Definition: defines.h:300
void bn_tabdata_join2(struct bn_tabdata *out, const struct bn_tabdata *in1, double scale2, const struct bn_tabdata *in2, double scale3, const struct bn_tabdata *in3)
const struct bn_table * table
Up pointer to definition of X axis.
Definition: tabdata.h:103
void bn_ck_table(const struct bn_table *tabp)
Definition: tabdata.c:80