star-enclosures-3d

Extract enclosures from 3D geometry
git clone git://git.meso-star.fr/star-enclosures-3d.git
Log | Files | Refs | README | LICENSE

README.md (5209B)

      1 # Star-enclosures-3d
      2 
      3 ## Overview
      4 
      5 The purpose of Star-enclosures-3d is to extract enclosures from raw
      6 geometry. An enclosure is a set of triangles enclosing a given volume.
      7 The enclosure notion extends to open enclosures for which there is no
      8 inside or outside. For every detected enclosure, the library provides
      9 the set of involved triangle sides as well as the set of involved media
     10 and a few metrics (number of triangles, volume, area, ...).
     11 
     12 From release 0.5, the geometry has to be provided at once, with no
     13 duplicates nor zero-area triangles. To help ensuring this constraints,
     14 one can rely on the star-geometry-3d library.
     15 
     16 Also the convention regarding FRONT/BACK sides for input triangles as
     17 well as the convention regarding normals' orientation for output
     18 triangles can be set.
     19 
     20 ## Requirements
     21 
     22 - C compiler
     23 - POSIX make
     24 - pkg-config
     25 - [RSys](https://gitlab.com/vaplv/rsys)
     26 - [Star 3D](https://gitlab.com/meso-star/star-3d)
     27 - [Star 3DUT](https://gitlab.com/meso-star/star-3dut)
     28   (optinal for tests)
     29 - [Star SamPling](https://gitlab.com/meso-star/star-sp)
     30   (optinal for tests)
     31 
     32 ## Installation
     33 
     34 Edit config.mk as needed, then run:
     35 
     36     make clean install
     37 
     38 ## Release notes
     39 
     40 ### Version 0.7.2
     41 
     42 - Another correction in the code that groups connex components to create
     43   enclosures.
     44 - Add function `senc3d_scene_dump_enclosure_obj` which writes an Obj
     45   file of a given enclosure geometry.
     46 
     47 ### Version 0.7.1
     48 
     49 - Fixes a bug in the code that groups connex components to create
     50   enclosures.
     51 
     52 ### Version 0.7
     53 
     54 - Replace CMake by Makefile as build system.
     55 - Update compiler and linker flags to increase the security and
     56   robustness of generated binaries.
     57 - Provide a pkg-config file to link the library as an external
     58   dependency.
     59 
     60 ### Version 0.6
     61 
     62 - Major rework on the code that groups connex components to create
     63   enclosures.
     64 - Add tests showing bugs at the grouping stage in previous release.
     65 - Add debug code that allows to dump how connex components are grouped.
     66 - Fix compilation warnings.
     67 - Sets the required version of Star-3D to 0.9.
     68 
     69 ### Version 0.5.5
     70 
     71 - Fixes a crash linked to numerical accuracy that caused connex
     72   components grouping to loop forever.
     73 
     74 ### Version 0.5.4
     75 
     76 - Fixes the (rare) situation where temporary local variables could be
     77   used in a unitialized way in the `senc3d_scene_create` function.
     78 - Sets the required version of Star-SampPling to 0.12. This version
     79   fixes compilation errors with gcc 11 but introduces API breaks.
     80 
     81 ### Version 0.5.3
     82 
     83 - Fix API break on filter function introduced by Star-3D 0.8.
     84 
     85 ### Version 0.5.1
     86 
     87 - BugFix: enclosures including multiple media could end with invalid
     88   primitive count.
     89 
     90 - BugFix: grouping of components in contact at a single vertex was
     91   incorrect, causing invalid enclosures.
     92 
     93 ### Version 0.5
     94 
     95 This release breaks the API as geometry cannot be provided through calls
     96 to an add-like call anymore. Instead the whole geometry must be provided
     97 at once, with no duplicates (either vertices or triangles) nor zero-area
     98 triangles.
     99 
    100 - Compute volume and surface of enclosures.
    101 
    102 - Report overlapping triangles.
    103   Only triangles with a common edge are currently detected.
    104   Do not extract enclosures when overlapping triangles are detected.
    105 
    106 - Make enclosure IDs consistent across runs.
    107 
    108 - Fix enclosure extraction when all triangles Nz component is zero.
    109 
    110 - More robust on invalid scenes.
    111 
    112 ### Version 0.4.2
    113 
    114 - Fix global id of triangles; releases 0.4.0 and 0.4.1 are broken
    115 
    116 - Reintroduce an API call to get the global id in user space of
    117   a global unique triangle after deduplication
    118 
    119 ### Version 0.4.1
    120 
    121 - Fix an infinite loop related to a rare numerical accuracy problem.
    122 
    123 ### Version 0.4
    124 
    125 - Change signature of the `senc_scene_add_geometry` API. Thus this
    126   release is **not compatible** with previous ones.
    127   The `global_id` callback that was ill-defined is removed and 2
    128   callbacks are added to manage client-app data when deduplicating
    129   geometry.
    130   These 2 callback allow a proper client-app management of global ids. 
    131 - Remove execution time for analysis steps from the log.
    132 
    133 ### Version 0.3.1
    134 
    135 - Performance Fix: when a connex component was canceled by a thread the
    136   complexity was O(n^2). New algorithm is O(n).
    137 - Output execution time for analysis steps in the log.
    138 
    139 ### Version 0.3
    140 
    141 - Add API calls to access to geometry frontiers.
    142 - Improve documentation in the header file.
    143 - BugFix: wrong data cleaning on computation canceling.
    144 
    145 ### Version 0.2.2
    146 
    147 - BugFix when grouping components into enclosures.
    148 - Add a warning message in log when triangles that could surround a
    149   hole are found (triangles with at least one unshared edge and
    150   different media on its sides).
    151 
    152 ### Version 0.2.1
    153 
    154 - BugFix: needed data cleaning on computation canceling.
    155 
    156 ### Version 0.2
    157 
    158 - Add the support of enclosures with multiple media.
    159 - Allow to set the FRONT/BACK convention for input triangles.
    160 - Allow to set the normal convention for output triangles.
    161 
    162 ## License
    163 
    164 Copyright © 2018-2020, 2023, 2024
    165 [|Méso|Star>](https://www.meso-star.com) (<contact@meso-star.com>).
    166 
    167 It is free software released under the GPLv3+ license. You are welcome
    168 to redistribute it under certain conditions; refer to the COPYING files
    169 for details.