sck.h (5688B)
1 /* Copyright (C) 2022, 2023 |Méso|Star> (contact@meso-star.com) 2 * Copyright (C) 2020, 2021 CNRS 3 * 4 * This program is free software: you can redistribute it and/or modify 5 * it under the terms of the GNU General Public License as published by 6 * the Free Software Foundation, either version 3 of the License, or 7 * (at your option) any later version. 8 * 9 * This program is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 * GNU General Public License for more details. 13 * 14 * You should have received a copy of the GNU General Public License 15 * along with this program. If not, see <http://www.gnu.org/licenses/>. */ 16 17 #ifndef SCK_H 18 #define SCK_H 19 20 #include <rsys/hash.h> 21 #include <rsys/rsys.h> 22 23 /* Library symbol management */ 24 #if defined(SCK_SHARED_BUILD) /* Build shared library */ 25 #define SCK_API extern EXPORT_SYM 26 #elif defined(SCK_STATIC) /* Use/build static library */ 27 #define SCK_API extern LOCAL_SYM 28 #else /* Use shared library */ 29 #define SCK_API extern IMPORT_SYM 30 #endif 31 32 /* Helper macro that asserts if the invocation of the sck function `Func' 33 * returns an error. One should use this macro on sck function calls for which 34 * no explicit error checking is performed */ 35 #ifndef NDEBUG 36 #define SCK(Func) ASSERT(sck_ ## Func == RES_OK) 37 #else 38 #define SCK(Func) sck_ ## Func 39 #endif 40 41 /* Forward declaration of external data types */ 42 struct logger; 43 struct mem_allocator; 44 45 struct sck_create_args { 46 struct logger* logger; /* May be NULL <=> default logger */ 47 struct mem_allocator* allocator; /* NULL <=> use default allocator */ 48 int verbose; /* Verbosity level */ 49 }; 50 #define SCK_CREATE_ARGS_DEFAULT__ {NULL, NULL, 0} 51 static const struct sck_create_args SCK_CREATE_ARGS_DEFAULT = 52 SCK_CREATE_ARGS_DEFAULT__; 53 54 struct sck_load_args { 55 const char* path; 56 int memory_mapping; /* Use memory mapping instead of normal loading */ 57 }; 58 #define SCK_LOAD_ARGS_NULL__ {NULL, 0} 59 static const struct sck_load_args SCK_LOAD_ARGS_NULL = SCK_LOAD_ARGS_NULL__; 60 61 struct sck_load_stream_args { 62 FILE* stream; 63 const char* name; /* Stream name */ 64 /* Use memory mapping instead of normal loading. Note that memory mapping 65 * cannot be used on some stream like stdin */ 66 int memory_mapping; 67 }; 68 #define SCK_LOAD_STREAM_ARGS_NULL__ {NULL, "stream", 0} 69 static const struct sck_load_stream_args SCK_LOAD_STREAM_ARGS_NULL = 70 SCK_LOAD_STREAM_ARGS_NULL__; 71 72 struct sck_band { 73 double lower; /* Lower band wavelength in nm (inclusive) */ 74 double upper; /* Upper band wavelength in nm (exclusive) */ 75 size_t quad_pts_count; /* #quadrature points */ 76 size_t id; 77 78 float* ks_list; /* Per node ks */ 79 80 /* Internal data */ 81 const struct sck* sck__; 82 const void* band__; 83 }; 84 #define SCK_BAND_NULL__ {0, 0, 0, 0, NULL, NULL, NULL} 85 static const struct sck_band SCK_BAND_NULL = SCK_BAND_NULL__; 86 87 struct sck_quad_pt { 88 float* ka_list; /* Per node ka */ 89 double weight; 90 size_t id; 91 }; 92 #define SCK_QUAD_PT_NULL__ {NULL, 0, 0} 93 static const struct sck_quad_pt SCK_QUAD_PT_NULL = SCK_QUAD_PT_NULL__; 94 95 /* Forward declaration of opaque data types */ 96 struct sck; 97 98 BEGIN_DECLS 99 100 /******************************************************************************* 101 * AtrKC API 102 ******************************************************************************/ 103 SCK_API res_T 104 sck_create 105 (const struct sck_create_args* args, 106 struct sck** sck); 107 108 SCK_API res_T 109 sck_ref_get 110 (struct sck* sck); 111 112 SCK_API res_T 113 sck_ref_put 114 (struct sck* sck); 115 116 SCK_API res_T 117 sck_load 118 (struct sck* sck, 119 const struct sck_load_args* args); 120 121 SCK_API res_T 122 sck_load_stream 123 (struct sck* sck, 124 const struct sck_load_stream_args* args); 125 126 /* Validates radiative coefficients. Data checks have already been carried out 127 * during loading, notably on spectral bands and quadrature points, but this 128 * function performs longer and more thorough tests. It reviews all scattering 129 * and absorption coefficients to check their validity, i.e. whether they are 130 * positive or zero. Note that checking radiative coefficients is not mandatory, 131 * in order to speed up the loading step and avoid loading/unloading them when 132 * using memory mapping. */ 133 SCK_API res_T 134 sck_validate 135 (const struct sck* sck); 136 137 SCK_API size_t 138 sck_get_bands_count 139 (const struct sck* sck); 140 141 SCK_API size_t 142 sck_get_nodes_count 143 (const struct sck* sck); 144 145 SCK_API res_T 146 sck_get_band 147 (const struct sck* sck, 148 const size_t iband, 149 struct sck_band* band); 150 151 /* Returns the range of band indices covered by a given spectral range. The 152 * returned index range is degenerated (i.e. ibands[0] > ibands[1]) if no band 153 * is found */ 154 SCK_API res_T 155 sck_find_bands 156 (const struct sck* sck, 157 const double range[2], /* In nm. Limits are inclusive */ 158 size_t ibands[2]); /* Range of overlaped bands. Limits are inclusive */ 159 160 SCK_API res_T 161 sck_band_get_quad_pt 162 (const struct sck_band* band, 163 const size_t iquad_pt, 164 struct sck_quad_pt* quad_pt); 165 166 SCK_API res_T 167 sck_band_sample_quad_pt 168 (const struct sck_band* band, 169 const double r, /* Canonical random number in [0, 1[ */ 170 size_t* iquad_pt); /* Index of the sampled quadrature point */ 171 172 SCK_API res_T 173 sck_quad_pt_compute_hash 174 (const struct sck_band* band, 175 const size_t iquad_pt, 176 hash256_T hash); 177 178 SCK_API res_T 179 sck_band_compute_hash 180 (const struct sck* sck, 181 const size_t iband, 182 hash256_T hash); 183 184 SCK_API res_T 185 sck_compute_hash 186 (const struct sck* sck, 187 hash256_T hash); 188 189 /* Returns the path of the file or the name of the stream from which the data 190 * was loaded */ 191 SCK_API const char* 192 sck_get_name 193 (const struct sck* sck); 194 195 END_DECLS 196 197 #endif /* SCK_H */