"Fossies" - the Fresh Open Source Software Archive

Member "brlcad-7.32.4/src/libgcv/NOTES" (29 Jul 2021, 8590 Bytes) of package /linux/misc/brlcad-7.32.4.tar.bz2:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 Included below are notes on the design and implementation of the
    2 Geometry Conversion Library (LIBGCV).
    3 
    4 
    5 ARCHITECTURE
    6 ============
    7 
    8 From an architecture standpoint, here are a few tenets that LIBGCV
    9 should adhere to:
   10 
   11 1) Minimal library dependencies.  It needs to drop into external codes
   12 without needing more than BRL-CAD's core libraries (libbu, libbn,
   13 libwdb, librt, libbrep).  Stand-alone distribution is a requirement.
   14 
   15 2) Public C or C++ API, not both.  If it's a C++ API, it shouldn't
   16 have free-floating global functions.  If it's a C API, it shouldn't
   17 expose C++ types in the public API without compilation safeguards.
   18 
   19 3) API independence.  Each added geometry format should extend LIBGCV
   20 without requiring ANY change to the public API.  That means we should
   21 not have an enum or #defines or public functions that embed a format
   22 (e.g., no public gcv_obj_to_g() functions).
   23 
   24 4) Plugin architecture.  Each format should require only one
   25 line/block be added to some GCV initialization function (or
   26 dynamically loaded at runtime) to register itself.  Ideally, each
   27 format lives in a sub-directory self-contained.
   28 
   29 5) Simplicity, consistency.  The API design should declare minimal
   30 symbols, types, structs, functions, designs.  It should follow
   31 conventions of our existing libraries in terms of conventions and
   32 patterns.
   33 
   34 
   35 API DESIGN
   36 ==========
   37 
   38 T.B.D.
   39 
   40 By design, this library is intended to be useful for reading and
   41 writing 3D geometry.  The public API design is intentionally very
   42 simple while supporting a number of file formats and geometry
   43 representation types.
   44 
   45 Supported file formats for reading and/or writing currently includes
   46 the following formats: OBJ, STL, VRML, FASTGEN4, and BRL-CAD.
   47 
   48 The library includes support for a number of implicit and explicit
   49 geometry representation types including Bags o' Triangles (triangle
   50 mesh geometry), n-Manifold polygonal meshes, volumetric data, NURBS,
   51 and implicit primitives with constructive solid geometry (CSG) Boolean
   52 operations.
   53 
   54 Multipass processing.  First check if all geometry records can be
   55 processed, e.g., whether a given geometry subtree or a particular
   56 geometry object will convert given a prescribed request.  This is to
   57 catch errors earlier in the pipeline.  Lossy or context-sensitive
   58 translations, e.g., exporting an infinite halfspace to polygonal
   59 format, are example considerations.
   60 
   61 Normalization.  Whether a prescribed output format supports a
   62 hierarchy and/or matrices or is modeled far from floating-point origin
   63 can influence conversion results.  Supporting normalization is not a
   64 priority, but may influence design options.
   65 
   66 
   67 PLAN OF ATTACK
   68 ==============
   69 
   70   1) move just the STL code without making any improvements or refactoring, get it under the API.
   71   2) that will undoubtedly require API adjusting.  adjust.
   72   3) get gcv command reading/writing stl files via libgcv.
   73   4) implement a brl-cad import/export plugin for v4/v5 binary, hook into libgcv.
   74   5) again, adjust and modify the API as needed here, checkpoint status.
   75   6) ensure gcv command recognizes stl and .g without requiring knowledge of them.
   76   7) test that g-to-stl is working and stl-to-g is working.
   77   8) migrate obj support into gcv (redundancies and all).
   78   9) implement general testing framework to evaluate all possible input/output combinations.
   79  10) test g-to-obj, obj-to-g, stl-to-obj, obj-to-stl, and report status.
   80  11) migrate fast4 import support.
   81  12) migrate vrml export support.
   82  13) test fast4-to-g, fast4-to-obj, fast4-to-stl, fast4-to-vrml, g-to-vrml, stl-to-vrml, obj-to-vrml.
   83  14) evaluate refactoring/consolidation of polygonal mesh logic in all formats.
   84  15) ensure gcv documentation is accurate and up-to-date (doxygen comments in the header).
   85   *) eliminate globals
   86   *) create a libgcv plugin template
   87   *) fast4 export
   88   *) vrml import
   89   *) create a stand-alone basic application runtime toolkit (BAR = libbu+libbn)
   90   *) update build system so GCV can be separated from the build tree stand-alone with BAR
   91   *) make gcv convert multithreaded
   92 
   93 
   94 NEW FORMATS
   95 ===========
   96 
   97 Adding a few notes on libraries that may be worth investigating to see
   98 if they have parsing logic that would help in developing converters
   99 for various formats.  They may amount to nothing, but are worth
  100 checking.
  101 
  102 For a fairly comprehensive list, see Paul Bourke's data formats page:
  103 http://paulbourke.net/dataformats/
  104 
  105 Collada (MIT licensed libraries)
  106 http://opencollada.org/
  107 http://sourceforge.net/projects/colladamaya/
  108 http://colladamaya.svn.sourceforge.net/viewvc/colladamaya/trunk/FCollada/
  109 
  110 Inventor files: (LGPL license)
  111 http://oss.sgi.com/projects/inventor/
  112 http://www.mevislab.de/inventor/ (website changed, see src/libgcv in
  113 				  dmtogl branch of BRL-CAD for patch)
  114 http://fl-inventor.sourceforge.net/
  115 Note that the Coin3D library is now 3-clause BSD as well, a better
  116 source from a licensing standpoint for extracting parsers etc.:
  117 https://bitbucket.org/Coin3D/coin/wiki/Home
  118 
  119 AutoCAD dwg - none (opendwg not compatible with BRL-CAD licensing)
  120 
  121 Solidworks (.sat, .sldprt, .sldasm)
  122 No external libraries apparent, probably unlikely
  123 src/external/Cubit/g-sat.cpp should be  useful as a starting point.
  124 
  125 Parasolid/UGS
  126 No external libraries apparent, probably unlikely
  127 
  128 POV-RAY
  129 Haven't found anything with a compatible license...
  130 
  131 Blender
  132 
  133 Apparently their file format is a bit... weird.  Possibly useful notes
  134 here:
  135 http://www.atmind.nl/blender/mystery_ot_blend.html
  136 http://www.blender.org/development/architecture/
  137 http://www.blender.org/development/architecture/notes-on-sdna/
  138 
  139 Since blender is GPL, unlikely their code can be used directly. Since
  140 their storage format seems to be close to their data structures, it
  141 might be worth contacting the project and asking specifically about
  142 the parsing code, if they have the flexibility to sub-license just
  143 that piece as LGPL.
  144 
  145 Update: From discussions at SIGGRAPH Blender forum, unlikely they have
  146 flexibility to relicense anything.  Much more interestingly, Gamekit
  147 was announced there which DOES import Blender files and is MIT
  148 licensed:
  149 
  150 http://code.google.com/p/gamekit/
  151 
  152 Exporting Blender may be impractical (i.e. no well defined format to
  153 target) but as Blender has importers for a wide variety of formats
  154 exporting to Blender directly may not be necessary
  155 
  156 Universal 3D (Apache 2.0 license)
  157 http://sourceforge.net/projects/u3d/
  158 
  159 PLY
  160 http://www.tecgraf.puc-rio.br/~diego/professional/rply/ (newer,
  161 probably should start here)
  162 http://www.cc.gatech.edu/projects/large_models/ply.html
  163 
  164 
  165 VRML/X3d  (LGPL license)
  166 http://openvrml.sourceforge.net/
  167 http://sourceforge.net/projects/x3dtoolkit/
  168 
  169 
  170 ===
  171 
  172 # inspired by https://xiph.org/flac/api/group__flac__stream__decoder.html
  173 
  174 gcv = new() := create context
  175 delete(gcv) := delete context
  176 set_...(gcv, ...) := set context properties
  177 get_...(gcv, ...) := get context properties
  178 init_fd(gcv, callbacks) := connect to a file descriptor
  179 init_FILE(gcv, callbacks) := connect to a file pointer
  180 init_file(gcv, callbacks) := connect to a file
  181 finish(gcv) := complete the conversion process, flush buffers, reset context (pairs with init)
  182 flush(gcv) := ensure all output streams are flushed (ensures writes)
  183 reset(gcv) := resets the context to an initialization state
  184 process_single(gcv) := process single object
  185 process(gcv) := process to end of stream
  186 
  187 # per format
  188 
  189 read(gcv, object(s), client_data) := read object(s)
  190 write(gcv, const object(s), client_data) := write object(s)
  191 seek(gcv, offset, client_data) := go to object #
  192 tell(gcv, offset, client_data) := current object position #
  193 length(gcv, length, client_data) := object count
  194 metadata(gcv, metadata, client_data) := object metadata (first, last, length/size, type, data)
  195 error(gcv, status, client_data) := called whenever an error occurs during conversion
  196 
  197 # modeled after java streams
  198 # inspired by http://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.html
  199 
  200 stream() := similar to read/write, returns set of objects
  201 filter() := applies filtering expression, returns set of objects
  202 toArray() := returns objects as a null-terminated array
  203 skip() := returns object set after discarding first n objects
  204 limit() := returns object set after discarding last n objects
  205 sorted() := returns object set sorted by specified criteria
  206 of() := returns ordered set of specified values
  207 min() := returns minimum object matching comparator callback
  208 max() : = returns maximum object matching comparator callback
  209 forEach() := perform action on each object
  210 count() := returns size of the object set
  211 distinct() := returns set of distinct objects from stream
  212 concat() := joins two streams together