sphin.h (19741B)
1 /* Copyright (C) 2024-2026 Centre National de la Recherche Scientifique 2 * Copyright (C) 2024-2026 Clermont Auvergne INP 3 * Copyright (C) 2024-2026 INSA Lyon 4 * Copyright (C) 2024-2026 Institut Mines Télécom Albi-Carmaux 5 * Copyright (C) 2024-2026 Institut National Polytechnique de Toulouse 6 * Copyright (C) 2024-2026 |Méso|Star> (contact@meso-star.com) 7 * Copyright (C) 2024-2026 PhotonLyX (info@photonlyx.com) 8 * Copyright (C) 2024-2026 Université de Lorraine 9 * Copyright (C) 2024-2026 Université Paul Sabatier 10 * Copyright (C) 2024-2026 Université Toulouse - Jean Jaurès 11 * 12 * This program is free software: you can redistribute it and/or modify 13 * it under the terms of the GNU General Public License as published by 14 * the Free Software Foundation, either version 3 of the License, or 15 * (at your option) any later version. 16 * 17 * This program is distributed in the hope that it will be useful, 18 * but WITHOUT ANY WARRANTY; without even the implied warranty of 19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 20 * GNU General Public License for more details. 21 * 22 * You should have received a copy of the GNU General Public License 23 * along with this program. If not, see <http://www.gnu.org/licenses/>. */ 24 25 #ifndef SPHIN_H 26 #define SPHIN_H 27 28 #include <rsys/rsys.h> 29 30 /* Library symbol management */ 31 #if defined(SPHIN_SHARED_BUILD) /* Directive defined only when building 32 star-phor-input (see Makefile) */ 33 #define SPHIN_API extern EXPORT_SYM /* When building star-phor-input */ 34 #else 35 #define SPHIN_API extern IMPORT_SYM /* When using star-phor-input */ 36 #endif 37 38 /* Helper macro that asserts if the invocation of the sphin function `Func' 39 * returns an error. One should use this macro on sphin function calls for which 40 * no explicit error checking is performed */ 41 #ifndef NDEBUG 42 #define SPHIN(Func) ASSERT(sphin_##Func == RES_OK) 43 #else 44 #define SPHIN(Func) sphin_##Func 45 #endif 46 47 enum sphin_side { 48 SPHIN_SIDE_BACK, /* 0 */ 49 SPHIN_SIDE_FRONT, /* 1 */ 50 SPHIN_SIDE_NONE__ /* 2 */ 51 }; 52 53 enum sphin_brdf_direction_distribution { 54 SPHIN_BRDF_DIRECTION_LAMBERT, /* 0 */ 55 SPHIN_BRDF_DIRECTION_SPECULAR, /* 1 */ 56 SPHIN_BRDF_DIRECTION_NONE__ /* 2 */ 57 }; 58 59 enum sphin_brdf_reflectivity_type { 60 SPHIN_BRDF_REFLECTIVITY_TABULATED, 61 SPHIN_BRDF_REFLECTIVITY_FRESNEL_DIELECTRIC, 62 SPHIN_BRDF_REFLECTIVITY_FRESNEL_DIELECTRIC_CONDUCTOR, 63 SPHIN_BRDF_REFLECTIVITY_NONE__ 64 }; 65 66 enum sphin_btdf_direction_distribution { 67 SPHIN_BTDF_DIRECTION_LAMBERT, 68 SPHIN_BTDF_DIRECTION_SNELL_DIELECTRIC, 69 SPHIN_BTDF_DIRECTION_KEEP_CURRENT_DIR, 70 SPHIN_BTDF_DIRECTION_NONE__ 71 }; 72 73 enum sphin_btdf_transmissivity_type { 74 SPHIN_BTDF_TRANSMISSIVITY_TABULATED, 75 SPHIN_BTDF_TRANSMISSIVITY_FRESNEL_DIELECTRIC, 76 SPHIN_BTDF_TRANSMISSIVITY_FRESNEL_DIELECTRIC_CONDUCTOR, 77 SPHIN_BTDF_TRANSMISSIVITY_NONE__ 78 }; 79 80 enum sphin_photon_unit { 81 SPHIN_PHOTON_UNIT_MOL, /* [mol] */ 82 SPHIN_PHOTON_UNIT_JOULE, /* [J] */ 83 SPHIN_PHOTON_UNIT_NONE__ 84 }; 85 86 enum sphin_source_surface_direction_distribution_type { 87 SPHIN_SOURCE_DIRECTION_COLLIM, 88 SPHIN_SOURCE_DIRECTION_COS_POW_N, 89 SPHIN_SOURCE_DIRECTION_ISOTROPIC, 90 SPHIN_SOURCE_DIRECTION_NONE__ 91 }; 92 93 enum sphin_prop_rad_type { 94 SPHIN_PROP_RAD_BOLTZMANN, 95 SPHIN_PROP_RAD_SCATTERER, 96 SPHIN_PROP_RAD_NONE__ 97 }; 98 99 enum sphin_interpolation_type { 100 SPHIN_INTERPOLATION_LINEAR, 101 SPHIN_INTERPOLATION_NONE__ 102 }; 103 104 struct sphin_create_args { 105 struct logger* logger; /* May be NULL <=> default logger */ 106 struct mem_allocator* allocator; /* NULL <=> use default allocator */ 107 int verbose; /* Verbosity level. Bigger values => more verbosity */ 108 }; 109 110 /* Public structs are provided with default values to simplify initialization 111 * and ensure consistent behavior. Users can either use the default settings or 112 * override specific fields as needed. If the struct is created by sphin, it 113 * will be initialized to its default value and the fields will be overwritten 114 * during the parsing */ 115 #define SPHIN_CREATE_ARGS_DEFAULT__ {NULL, NULL, 0} 116 static const struct sphin_create_args SPHIN_CREATE_ARGS_DEFAULT = 117 SPHIN_CREATE_ARGS_DEFAULT__; 118 119 struct sphin_source_surface_flux_density { 120 double flux_density; /* either [umol/m^2/s] or [W/m^2] */ 121 struct sphin_spectral_property* emission_spectrum; /* Normalized */ 122 enum sphin_photon_unit unit; 123 }; 124 #define SPHIN_SOURCE_SURFACE_FLUX_DENSITY_NULL__ { \ 125 0, \ 126 NULL, \ 127 SPHIN_PHOTON_UNIT_NONE__\ 128 } 129 static const struct sphin_source_surface_flux_density 130 SPHIN_SOURCE_SURFACE_FLUX_DENSITY_NULL = 131 SPHIN_SOURCE_SURFACE_FLUX_DENSITY_NULL__; 132 133 struct sphin_source_surface_direction_distribution_cos_pow_n { 134 double collimation_degree; 135 }; 136 #define SPHIN_SOURCE_SURFACE_DIRECTION_DISTRIBUTION_COS_POW_N_NULL__ {0} 137 static const struct sphin_source_surface_direction_distribution_cos_pow_n 138 SPHIN_SOURCE_SURFACE_DIRECTION_DISTRIBUTION_COS_POW_N_NULL = 139 SPHIN_SOURCE_SURFACE_DIRECTION_DISTRIBUTION_COS_POW_N_NULL__; 140 141 struct sphin_source_surface_direction_distribution_collim { 142 double direction[3]; /* {0,0,0} <=> use surface normal */ 143 }; 144 #define SPHIN_SOURCE_SURFACE_DIRECTION_DISTRIBUTION_COLLIM_NULL__ {{0,0,0}} 145 static const struct sphin_source_surface_direction_distribution_collim 146 SPHIN_SOURCE_SURFACE_DIRECTION_DISTRIBUTION_COLLIM_NULL = 147 SPHIN_SOURCE_SURFACE_DIRECTION_DISTRIBUTION_COLLIM_NULL__; 148 149 struct sphin_source_surface_direction_distribution { 150 enum sphin_source_surface_direction_distribution_type type; 151 struct sphin_source_surface_direction_distribution_cos_pow_n cos_pow_n; 152 struct sphin_source_surface_direction_distribution_collim collim; 153 }; 154 #define SPHIN_SOURCE_SURFACE_DIRECTION_DISTRIBUTION_NULL__ { \ 155 SPHIN_SOURCE_DIRECTION_NONE__, \ 156 SPHIN_SOURCE_SURFACE_DIRECTION_DISTRIBUTION_COS_POW_N_NULL__, \ 157 SPHIN_SOURCE_SURFACE_DIRECTION_DISTRIBUTION_COLLIM_NULL__ \ 158 } 159 static const struct sphin_source_surface_direction_distribution 160 SPHIN_SOURCE_SURFACE_DIRECTION_DISTRIBUTION_NULL = 161 SPHIN_SOURCE_SURFACE_DIRECTION_DISTRIBUTION_NULL__; 162 163 /* This structure, by design, describe a mesh in the simplest possible way, 164 * without making assumptions about how it will be used. It provides only the 165 * essential data: a flat array of vertex coordinates and an index array 166 * defining triangles. 167 * 168 * The responsibility for interpreting or structuring this data lies with the 169 * user or the functions that load the mesh. */ 170 struct sphin_mesh { 171 const double* coords; /* A sequence of triplets (x, y, z): 172 * [x0, y0, z0, x1, y1, z1, ...] */ 173 const size_t* indices; /* A sequence of indices that represents each triangle 174 * in the coords array */ 175 size_t triangle_count; 176 size_t vertex_count; 177 }; 178 #define SPHIN_MESH_NULL__ {NULL, NULL, 0, 0} 179 static const struct sphin_mesh SPHIN_MESH_NULL = SPHIN_MESH_NULL__; 180 181 struct sphin_geometry_descriptor { 182 const char* filename; 183 enum sphin_side side; /* FRONT: The structure is concerned with the same 184 * direction as the normal. 185 * BACK: The structure is concerned with the opposite 186 * direction of the normal. 187 * It determines which of the sides of a given geometry 188 * must be decorated with physical properties. 189 * Moreover, when used in a sphin_volume, it determine 190 * how the enclosure is formed. */ 191 struct sphin_mesh mesh; 192 }; 193 #define SPHIN_GEOMETRY_DESCRIPTOR_NULL__ { \ 194 NULL, \ 195 SPHIN_SIDE_NONE__, \ 196 SPHIN_MESH_NULL__ \ 197 } 198 static const struct sphin_geometry_descriptor 199 SPHIN_GEOMETRY_DESCRIPTOR_NULL = 200 SPHIN_GEOMETRY_DESCRIPTOR_NULL__; 201 202 struct sphin_spectral_property_descriptor { 203 const char* filename; 204 const double* wavelengths; /* In nm */ 205 const double* values; /* Corresponding value to each of the wavelengths */ 206 size_t data_count; /* Number of elements in the arrays */ 207 }; 208 #define SPHIN_SPECTRAL_PROPERTY_DESCRIPTOR_NULL__ {NULL, NULL, NULL, 0} 209 static const struct sphin_spectral_property_descriptor 210 SPHIN_SPECTRAL_PROPERTY_DESCRIPTOR_NULL = 211 SPHIN_SPECTRAL_PROPERTY_DESCRIPTOR_NULL__; 212 213 /* Forward declarations 214 * 215 * These structures are declared but remain opaque to users of the 216 * star-phor-input programming interface. Their internal representation 217 * is hidden to ensure encapsulation and modularity. 218 * 219 * Users must interact with these structures exclusively through the 220 * functions provided by the library (e.g., those prefixed with sphin_get).*/ 221 struct sphin; /* Library handler */ 222 struct sphin_config; /* Physical configuration */ 223 struct sphin_brdf; 224 struct sphin_btdf; 225 struct sphin_geometry; 226 struct sphin_prop_rad; 227 struct sphin_refractive_index; 228 struct sphin_scatterer; 229 struct sphin_sensor_surface; 230 struct sphin_sensor_volume; 231 struct sphin_source_surface; 232 struct sphin_spectral_property; 233 struct sphin_surface; 234 struct sphin_volume; 235 236 BEGIN_DECLS 237 238 /******************************************************************************* 239 * API of the sphin handler 240 ******************************************************************************/ 241 SPHIN_API res_T 242 sphin_create 243 (const struct sphin_create_args* args, 244 struct sphin** sphin); 245 246 SPHIN_API res_T 247 sphin_ref_get 248 (struct sphin* sphin); 249 250 SPHIN_API res_T 251 sphin_ref_put 252 (struct sphin* sphin); 253 254 /******************************************************************************* 255 * API of the configuration 256 ******************************************************************************/ 257 SPHIN_API res_T 258 sphin_load 259 (struct sphin* sphin, 260 const char* filename, 261 struct sphin_config** config); 262 263 SPHIN_API res_T 264 sphin_load_stream 265 (struct sphin* sphin, 266 FILE* stream, 267 const char* stream_name, 268 struct sphin_config** config); 269 270 SPHIN_API res_T 271 sphin_config_ref_get 272 (struct sphin_config* config); 273 274 SPHIN_API res_T 275 sphin_config_ref_put 276 (struct sphin_config* config); 277 278 SPHIN_API res_T 279 sphin_config_get_volume_count 280 (struct sphin_config* config, 281 size_t* nvolumes); 282 283 SPHIN_API res_T 284 sphin_config_get_volume 285 (struct sphin_config* config, 286 size_t ivolume, 287 struct sphin_volume** volume); 288 289 SPHIN_API res_T 290 sphin_config_get_surface_count 291 (struct sphin_config* config, 292 size_t* nsurfaces); 293 294 SPHIN_API res_T 295 sphin_config_get_surface 296 (struct sphin_config* config, 297 size_t isurface, 298 struct sphin_surface** surface); 299 300 SPHIN_API res_T 301 sphin_config_get_total_surface_power 302 (struct sphin_config* config, 303 double* total_power); 304 305 /******************************************************************************* 306 * API of the volume 307 ******************************************************************************/ 308 SPHIN_API res_T 309 sphin_volume_ref_get 310 (struct sphin_volume* volume); 311 312 SPHIN_API res_T 313 sphin_volume_ref_put 314 (struct sphin_volume* volume); 315 316 SPHIN_API res_T 317 sphin_volume_get_name 318 (struct sphin_volume* volume, 319 char** name); 320 321 SPHIN_API res_T 322 sphin_volume_compute_total_size 323 (struct sphin_volume* volume, 324 double* total_size); 325 326 SPHIN_API res_T 327 sphin_volume_get_sensor 328 (struct sphin_volume* volume, 329 struct sphin_sensor_volume** sensor_volume); /* May be NULL <=> no sensor */ 330 331 SPHIN_API res_T 332 sphin_volume_get_geometry_count 333 (struct sphin_volume* volume, 334 size_t* ngeometries); 335 336 SPHIN_API res_T 337 sphin_volume_get_geometry 338 (struct sphin_volume* volume, 339 size_t igeometry, 340 struct sphin_geometry** geometry); 341 342 SPHIN_API res_T 343 sphin_volume_get_prop_rad_count 344 (struct sphin_volume* volume, 345 size_t* prop_rad_count); 346 347 SPHIN_API res_T 348 sphin_volume_get_prop_rad 349 (struct sphin_volume* volume, 350 size_t iprop_rad, 351 struct sphin_prop_rad** prop_rad); 352 353 SPHIN_API res_T 354 sphin_volume_get_refractive_index 355 (struct sphin_volume* volume, 356 struct sphin_refractive_index** refr_ind); /* May be NULL <=> no refr_ind */ 357 358 /******************************************************************************* 359 * API of the radiative properties 360 ******************************************************************************/ 361 SPHIN_API res_T 362 sphin_prop_rad_ref_get 363 (struct sphin_prop_rad* prop_rad); 364 365 SPHIN_API res_T 366 sphin_prop_rad_ref_put 367 (struct sphin_prop_rad* prop_rad); 368 369 SPHIN_API res_T 370 sphin_prop_rad_get_name 371 (struct sphin_prop_rad* prop_rad, 372 char** name); 373 374 SPHIN_API res_T 375 sphin_prop_rad_get_scatterer 376 (struct sphin_prop_rad* prop_rad, 377 struct sphin_scatterer** scatterer); 378 379 /******************************************************************************* 380 * API of the scatterer 381 ******************************************************************************/ 382 SPHIN_API res_T 383 sphin_scatterer_ref_get 384 (struct sphin_scatterer* scatterer); 385 386 SPHIN_API res_T 387 sphin_scatterer_ref_put 388 (struct sphin_scatterer* scatterer); 389 390 SPHIN_API res_T 391 sphin_scatterer_get_concentration 392 (struct sphin_scatterer* scatterer, 393 double* concentration); 394 395 SPHIN_API res_T 396 sphin_scatterer_get_abs_cross_sec 397 (struct sphin_scatterer* scatterer, 398 struct sphin_spectral_property** abs_cross_sec); 399 400 /******************************************************************************* 401 * API of the refractive index 402 ******************************************************************************/ 403 SPHIN_API res_T 404 sphin_refractive_index_ref_get 405 (struct sphin_refractive_index* refr_ind); 406 407 SPHIN_API res_T 408 sphin_refractive_index_ref_put 409 (struct sphin_refractive_index* refr_ind); 410 411 SPHIN_API res_T 412 sphin_refractive_index_get_n_real 413 (struct sphin_refractive_index* refr_ind, 414 struct sphin_spectral_property** n_real); /* May be NULL <=> no n_real */ 415 416 SPHIN_API res_T 417 sphin_refractive_index_get_n_imag 418 (struct sphin_refractive_index* refr_ind, 419 struct sphin_spectral_property** n_imag); /* May be NULL <=> no n_imag */ 420 421 /******************************************************************************* 422 * API of the surface 423 ******************************************************************************/ 424 SPHIN_API res_T 425 sphin_surface_ref_get 426 (struct sphin_surface* surface); 427 428 SPHIN_API res_T 429 sphin_surface_ref_put 430 (struct sphin_surface* surface); 431 432 SPHIN_API res_T 433 sphin_surface_get_name 434 (struct sphin_surface* surface, 435 char** name); 436 437 SPHIN_API res_T 438 sphin_surface_compute_total_area 439 (struct sphin_surface* surface, 440 double* area); 441 442 SPHIN_API res_T 443 sphin_surface_get_sensor 444 (struct sphin_surface* surface, 445 struct sphin_sensor_surface** sensor_surface); /* May be NULL <=> no 446 sensor */ 447 448 SPHIN_API res_T 449 sphin_surface_get_brdf 450 (const struct sphin_surface* surface, 451 struct sphin_brdf** brdf); /* May be NULL <=> no brdf */ 452 453 SPHIN_API res_T 454 sphin_surface_get_btdf 455 (const struct sphin_surface* surface, 456 struct sphin_btdf** btdf); /* May be NULL <=> no btdf */ 457 458 SPHIN_API res_T 459 sphin_surface_get_source 460 (const struct sphin_surface* surface, 461 struct sphin_source_surface** source_surface); /* May be NULL <=> no src */ 462 463 SPHIN_API res_T 464 sphin_surface_get_geometry_count 465 (struct sphin_surface* surface, 466 size_t* ngeometries); 467 468 SPHIN_API res_T 469 sphin_surface_get_geometry 470 (struct sphin_surface* surface, 471 size_t igeometry, 472 struct sphin_geometry** geometry); 473 474 SPHIN_API res_T 475 sphin_surface_source_get_power 476 (struct sphin_surface* surface, 477 double* power); 478 479 /******************************************************************************* 480 * API of the source surface 481 ******************************************************************************/ 482 SPHIN_API res_T 483 sphin_source_surface_ref_get 484 (struct sphin_source_surface* source_surface); 485 486 SPHIN_API res_T 487 sphin_source_surface_ref_put 488 (struct sphin_source_surface* source_surface); 489 490 SPHIN_API res_T 491 sphin_source_surface_get_direction_distribution 492 (const struct sphin_source_surface* source_surface, 493 struct sphin_source_surface_direction_distribution* distrib); 494 495 SPHIN_API res_T 496 sphin_source_surface_get_flux_density 497 (const struct sphin_source_surface* source_surface, 498 struct sphin_source_surface_flux_density* density); 499 500 /******************************************************************************* 501 * API of the BRDF 502 ******************************************************************************/ 503 SPHIN_API res_T 504 sphin_brdf_ref_get 505 (struct sphin_brdf* brdf); 506 507 SPHIN_API res_T 508 sphin_brdf_ref_put 509 (struct sphin_brdf* brdf); 510 511 SPHIN_API res_T 512 sphin_brdf_get_direction_distribution 513 (struct sphin_brdf* brdf, 514 enum sphin_brdf_direction_distribution* direction_distribution); 515 516 SPHIN_API res_T 517 sphin_brdf_get_reflectivity_type 518 (struct sphin_brdf* brdf, 519 enum sphin_brdf_reflectivity_type* reflectivity_type); 520 521 SPHIN_API res_T 522 sphin_brdf_get_reflectivity_value 523 (struct sphin_brdf* brdf, /* Only for SPHIN_BRDF_REFLECTIVITY_CONSTANT */ 524 struct sphin_spectral_property** reflectivity); 525 526 /******************************************************************************* 527 * API of the BTDF 528 ******************************************************************************/ 529 SPHIN_API res_T 530 sphin_btdf_ref_get 531 (struct sphin_btdf* btdf); 532 533 SPHIN_API res_T 534 sphin_btdf_ref_put 535 (struct sphin_btdf* btdf); 536 537 SPHIN_API res_T 538 sphin_btdf_get_direction_distribution 539 (struct sphin_btdf* btdf, 540 enum sphin_btdf_direction_distribution* direction_distribution); 541 542 SPHIN_API res_T 543 sphin_btdf_get_transmissivity_type 544 (struct sphin_btdf* btdf, 545 enum sphin_btdf_transmissivity_type* transmissivity_type); 546 547 SPHIN_API res_T 548 sphin_btdf_get_transmissivity_value 549 (struct sphin_btdf* btdf, /* Only for SPHIN_BTDF_TRANSMISSIVITY_CONSTANT */ 550 struct sphin_spectral_property** transmissivity); 551 552 /******************************************************************************* 553 * API of the sensor_volume 554 ******************************************************************************/ 555 SPHIN_API res_T 556 sphin_sensor_volume_ref_get 557 (struct sphin_sensor_volume* sensor_volume); 558 559 SPHIN_API res_T 560 sphin_sensor_volume_ref_put 561 (struct sphin_sensor_volume* sensor_volume); 562 563 SPHIN_API res_T 564 sphin_sensor_volume_get_response_function 565 (struct sphin_sensor_volume* sensor_volume, 566 double* response_function); 567 568 /******************************************************************************* 569 * API of the sensor_surface 570 ******************************************************************************/ 571 SPHIN_API res_T 572 sphin_sensor_surface_ref_get 573 (struct sphin_sensor_surface* sensor_surface); 574 575 SPHIN_API res_T 576 sphin_sensor_surface_ref_put 577 (struct sphin_sensor_surface* sensor_surface); 578 579 SPHIN_API res_T 580 sphin_sensor_surface_get_response_function 581 (struct sphin_sensor_surface* sensor_surface, 582 double* response_function); 583 584 /******************************************************************************* 585 * API of the geometry 586 ******************************************************************************/ 587 SPHIN_API res_T 588 sphin_geometry_ref_get 589 (struct sphin_geometry* geometry); 590 591 SPHIN_API res_T 592 sphin_geometry_ref_put 593 (struct sphin_geometry* geometry); 594 595 SPHIN_API res_T 596 sphin_geometry_get_desc 597 (const struct sphin_geometry* geometry, 598 struct sphin_geometry_descriptor* desc); 599 600 /******************************************************************************* 601 * API of the spectral_property 602 ******************************************************************************/ 603 SPHIN_API res_T 604 sphin_spectral_property_ref_get 605 (struct sphin_spectral_property* property); 606 607 SPHIN_API res_T 608 sphin_spectral_property_ref_put 609 (struct sphin_spectral_property* property); 610 611 SPHIN_API res_T 612 sphin_spectral_property_get_desc 613 (const struct sphin_spectral_property* property, 614 struct sphin_spectral_property_descriptor* desc); 615 616 SPHIN_API res_T 617 sphin_spectral_property_interpolate_at_wavelength 618 (const struct sphin_spectral_property* property, 619 double wavelength, 620 enum sphin_interpolation_type type, 621 double* value); 622 623 END_DECLS 624 #endif /* SPHIN_H */