From 2764e77c566eb06d26aa689c75965cf132106d67 Mon Sep 17 00:00:00 2001 From: Hugues Delorme Date: Mon, 14 Mar 2016 15:53:22 +0100 Subject: [PATCH] Improve doc --- README.md | 13 ++-- doc/Doxyfile.cmake | 6 +- doc/mainpage.c | 88 +++++++++++++++++++++++ examples/occstl_read_file.cpp | 3 - examples/occstl_redefine_mesh_creator.cpp | 8 +-- examples/occstl_write_file.cpp | 7 +- examples/stl_get_infos.c | 22 +++--- examples/stl_read_file.c | 20 +++--- examples/stl_write_file.c | 6 -- 9 files changed, 116 insertions(+), 57 deletions(-) create mode 100644 doc/mainpage.c diff --git a/README.md b/README.md index 13914f8..a2b507d 100644 --- a/README.md +++ b/README.md @@ -38,14 +38,11 @@ Supported CAD files format Current version only supports the STL file format (STereoLithography), but support is complete : - * [x] Binary format - * [x] Little/big endian support - * [x] 80-byte header support - * [x] Facet "attribute byte count" field support - * [x] ASCII format - * [x] Case-insensitive reading - * [x] Output format(%f, %e, ...) and precision of floats support - * [x] Detection of the input data format + * [x] ASCII format: Case-insensitive reading + * [x] ASCII format: Output format(%f, %e, ...) and precision of floats support + * [x] Binary format: Little/big endian support + * [x] Binary format: 80-byte header and facet "attribute byte count" support + * [x] Detection of the input format * [x] Retrieval of infomations about contents(facet count, solid name, ...) In addition, the STL module has the following advatanges: diff --git a/doc/Doxyfile.cmake b/doc/Doxyfile.cmake index f288f56..2c37afe 100644 --- a/doc/Doxyfile.cmake +++ b/doc/Doxyfile.cmake @@ -249,7 +249,7 @@ EXTENSION_MAPPING = MARKDOWN_SUPPORT = YES -USE_MDFILE_AS_MAINPAGE = @CMAKE_CURRENT_SOURCE_DIR@/../README.md +USE_MDFILE_AS_MAINPAGE = # If you use STL classes (i.e. std::string, std::vector, etc.) but do not want # to include (a tag file for) the STL sources as input, then you should @@ -641,7 +641,7 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = @CMAKE_CURRENT_SOURCE_DIR@/../README.md \ +INPUT = @CMAKE_CURRENT_SOURCE_DIR@/../doc/mainpage.c \ @CMAKE_CURRENT_SOURCE_DIR@/../src # This tag can be used to specify the character encoding of the source files @@ -702,7 +702,7 @@ EXCLUDE_SYMBOLS = internal # directories that contain example code fragments that are included (see # the \include command). -EXAMPLE_PATH = +EXAMPLE_PATH = @CMAKE_CURRENT_SOURCE_DIR@/../examples # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp diff --git a/doc/mainpage.c b/doc/mainpage.c new file mode 100644 index 0000000..4d6802a --- /dev/null +++ b/doc/mainpage.c @@ -0,0 +1,88 @@ +/*! \mainpage + +\section intro Introduction + + gmio is a reusable C library whose purpose is to provide complete I/O + support for various CAD file formats (eg. STL) + + gmio aims to be fast, + portable (C90 conformance) and feature-rich. + Main highlights: + + \li "Abstract" streams that does not tie the user to C stream (`FILE*`)\n + gmio provides a general stream structure based on callbacks, so that any API + can be used (C++ streams, QFile, ...) + + \li Buffering of input/ouput for efficient device usage + \li Operations can be easily aborted + \li Progress report about the I/O operation + \li Available under the CeCILL-B license, which is fully BSD compatible + +\section sup_cadf Supported CAD files format + +Current version only supports the STL file format (STereoLithography), but +support is complete : + + \li ASCII format: Case-insensitive reading + \li ASCII format: Output format(%f, %e, ...) and precision of floats support + \li Binary format: Little/big endian support + \li Binary format: 80-byte header and facet "attribute byte count" support + \li Detection of the input format + \li Retrieval of infomations about contents(facet count, solid name, ...) + +In addition, the STL module has the following advatanges: + + \li The user keeps its own geometry data structures, no conversion needed\n + This reduces the effort so that the user just specifies callbacks for + retrieval/creation of mesh data + + \li Constant memory footprint\n + Memory consumption is indenpendant of the mesh size ie. the amount of memory + used remains constant during the I/O operation + + \li Extended support of OpenCascade\n + `StlMesh_Mesh` objects can be used seamlessly with gmio + +\section build Building gmio + +gmio can be built with CMake, by default a static library is generated. + +Read the Build instructions + +\section bug_report How to report a bug + +If you think you have found a bug in gmio, we would like to hear +about it so that we can fix it.\n +The gmio bug tracking system is open to the public at https://github.com/fougue/gmio/issues. + +Always include the following information in your bug report: + \li the name and version number of your compiler + \li the name and version number of your operating system + \li the version of gmio you are using + \li what configure options it was compiled with. + +If the problem you are reporting is only visible at run-time, try to +create a small test program that shows the problem when run. + +\section lic License + +This software is governed by the CeCILL-B license under French law and +abiding by the rules of distribution of free software.\n +You can use, modify and/ or redistribute the software under the terms of the CeCILL-B +license as circulated by CEA, CNRS and INRIA at this +URL + +\section creds Credits + +"gmio" logo rendered with Prism font (thanks to Erik Yin !) + +*/ + +/*! + \example ../examples/occstl_read_file.cpp + \example ../examples/occstl_redefine_mesh_creator.cpp + \example ../examples/occstl_write_file.cpp + \example ../examples/stl_get_infos.c + \example ../examples/stl_read_file.c + \example ../examples/stl_write_file.c + */ diff --git a/examples/occstl_read_file.cpp b/examples/occstl_read_file.cpp index 592a398..1e7a2b6 100644 --- a/examples/occstl_read_file.cpp +++ b/examples/occstl_read_file.cpp @@ -23,11 +23,8 @@ int main(int argc, char** argv) { int error = 0; if (argc > 1) { - // Path to the STL file const char* filepath = argv[1]; - // StlMesh_Mesh object to be constructed Handle_StlMesh_Mesh mesh = new StlMesh_Mesh; - // Holds callbacks functions gmio_stl_mesh_creator mesh_creator = gmio_stl_occmesh_creator(mesh); // Read, using default options(NULL) diff --git a/examples/occstl_redefine_mesh_creator.cpp b/examples/occstl_redefine_mesh_creator.cpp index 232d798..f07c56f 100644 --- a/examples/occstl_redefine_mesh_creator.cpp +++ b/examples/occstl_redefine_mesh_creator.cpp @@ -10,7 +10,7 @@ #include #include -// Redefine func_begin_solid of some gmio_stl_mesh_creator object +// Redefine gmio_stl_mesh_creator::func_begin_solid void my_mesh_creator__begin_solid( void* cookie, const gmio_stl_mesh_creator_infos* infos) { @@ -20,7 +20,7 @@ void my_mesh_creator__begin_solid( // Do something more ... } -// Redefine func_add_triangle of some gmio_stl_mesh_creator object +// Redefine gmio_stl_mesh_creator::func_add_triangle void my_mesh_creator__add_triangle( void* cookie, uint32_t tri_id, const gmio_stl_triangle* triangle) { @@ -34,13 +34,9 @@ int main(int argc, char** argv) { int error = 0; if (argc > 1) { - // Path to the STL file const char* filepath = argv[1]; - // StlMesh_Mesh object to be constructed Handle_StlMesh_Mesh mesh = new StlMesh_Mesh; - // mesh_creator to be redefined gmio_stl_mesh_creator base_creator = gmio_stl_occmesh_creator(mesh); - // Holds callbacks functions gmio_stl_mesh_creator creator = {}; creator.cookie = &base_creator; creator.func_begin_solid = my_mesh_creator__begin_solid; diff --git a/examples/occstl_write_file.cpp b/examples/occstl_write_file.cpp index 0007a9c..b64afa0 100644 --- a/examples/occstl_write_file.cpp +++ b/examples/occstl_write_file.cpp @@ -22,20 +22,15 @@ int main(int argc, char** argv) { int error = 0; if (argc > 1) { - // Path to the STL file const char* filepath = argv[1]; - // StlMesh_Mesh object to be constructed Handle_StlMesh_Mesh occmesh = new StlMesh_Mesh; - // Initialize the OpenCascade StlMesh_Mesh here // ... - // Will give fast access to all the triangles of the StlMesh_Mesh object const gmio_stl_occmesh_iterator occmesh_it(occmesh); - // The gmio interface over OpenCascade's StlMesh_Mesh const gmio_stl_mesh mesh = gmio_stl_occmesh(occmesh_it); - // Write binary STL little-endian, using default options(NULL) + // Write binary STL(little-endian), using default options(NULL) error = gmio_stl_write_file( GMIO_STL_FORMAT_BINARY_LE, filepath, &mesh, NULL); if (error != GMIO_ERROR_OK) diff --git a/examples/stl_get_infos.c b/examples/stl_get_infos.c index 29e4210..b3bf891 100644 --- a/examples/stl_get_infos.c +++ b/examples/stl_get_infos.c @@ -1,15 +1,13 @@ /* ----------------------------------------------------------------------------- * - * Example: read a STL file + * Example: get informations about an STL file * - * Just give a filepath and an initialized gmio_stl_mesh_creator object to - * gmio_stl_read_file(). - * The gmio_stl_mesh_creator object holds pointers to the callbacks invoked - * during the read operation. - * These callbacks creates the final mesh object. - * - * Note if you want to have control over the stream to be used, call - * gmio_stl_read() instead. + * Informations that can be retrieved by gmio_stl_infos_get() are: + * - STL format of the input stream + * - Count of facets(triangles) + * - Size of the STL contents in bytes + * - STL ascii only: name of the solid + * - STL binary only: header(80-bytes) * * -------------------------------------------------------------------------- */ @@ -48,17 +46,13 @@ int main(int argc, char** argv) { int error = 0; if (argc > 1) { - /* Path to the STL file */ const char* filepath = argv[1]; - /* Read-only standard stream on the STL file */ FILE* file = fopen(filepath, "rb"); if (file != NULL) { - /* gmio stream interface object */ struct gmio_stream stream = gmio_stream_stdio(file); - /* Will holds informations about the STL file */ struct gmio_stl_infos infos = {0}; - /* Retrieve STL informations */ + /* Retrieve STL informations, using default options(NULL) */ error = gmio_stl_infos_get( &infos, &stream, GMIO_STL_INFO_FLAG_ALL, NULL); printf("File: %s\n", filepath); diff --git a/examples/stl_read_file.c b/examples/stl_read_file.c index 4e4923e..c27ffb6 100644 --- a/examples/stl_read_file.c +++ b/examples/stl_read_file.c @@ -26,8 +26,8 @@ static void my_3d_mesh__begin_solid( { struct my_3d_mesh* my_mesh = (struct my_3d_mesh*)cookie; size_t tri_count = 0; - if (infos->format == GMIO_STL_FORMAT_ASCII) /* Assume facet size ~200B */ - tri_count = infos->stla_stream_size / 200u; + if (infos->format == GMIO_STL_FORMAT_ASCII) /* Assume facet size ~230B */ + tri_count = infos->stla_stream_size / 230; else /* Binary STL */ tri_count = infos->stlb_triangle_count; my_mesh->triangle_array = @@ -37,8 +37,7 @@ static void my_3d_mesh__begin_solid( my_mesh->triangle_array_capacity = tri_count; } -/* Callback invoked sequentially for each triangle in the STL mesh - * Just do something with the "triangle" passed in */ +/* Callback invoked sequentially for each triangle in the STL mesh */ static void my_3d_mesh__copy_triangle( void* cookie, uint32_t triangle_id, @@ -50,7 +49,12 @@ static void my_3d_mesh__copy_triangle( /* Capacity of the triangle array is too small, this can happen only * when reading STL ascii data, where the count of triangles in not * precisely known. - * To overcome this just grow capacity of the triangle array of 12.5% */ + * To overcome this: + * - instead of just using general gmio_stl_read(), call + * call gmio_stl_infos_get(GMIO_STL_INFO_FLAG_FACET_COUNT) and then + * gmio_stla_read() + * - or just grow the capacity of your mesh, here the triangle array + * is grown by 12.5% */ size_t new_capacity = my_mesh->triangle_array_capacity; new_capacity += new_capacity >> 3; my_mesh->triangle_array = @@ -77,19 +81,13 @@ int main(int argc, char** argv) { int error = 0; if (argc > 1) { - /* Path to the STL file */ const char* filepath = argv[1]; - /* User-defined mesh object, to be constructed */ struct my_3d_mesh my_mesh = {0}; - /* Holds callbacks functions */ struct gmio_stl_mesh_creator mesh_creator = {0}; /* Initialize the callback object */ - /* -- Cookie object passed to callbacks of gmio_stl_mesh_creator */ mesh_creator.cookie = &my_mesh; - /* -- Function called initially at the beginning of a STL solid(mesh) */ mesh_creator.func_begin_solid = my_3d_mesh__begin_solid; - /* -- Function called for each triangle in the STL mesh */ mesh_creator.func_add_triangle = my_3d_mesh__copy_triangle; /* Read, using default options(NULL) */ diff --git a/examples/stl_write_file.c b/examples/stl_write_file.c index 5b476df..a79404b 100644 --- a/examples/stl_write_file.c +++ b/examples/stl_write_file.c @@ -39,22 +39,16 @@ int main(int argc, char** argv) { int error = 0; if (argc > 1) { - /* Path to the STL file */ const char* filepath = argv[1]; - /* User-defined mesh object */ struct my_3d_mesh my_mesh = {0}; - /* The interface to the user-defined mesh object */ struct gmio_stl_mesh mesh = {0}; /* Construct the user mesh */ /* ... */ /* Initialize the mesh interface */ - /* -- Cookie object passed to callbacks of gmio_stl_mesh */ mesh.cookie = &my_mesh; - /* -- Count of triangles in the mesh */ mesh.triangle_count = my_mesh.triangle_array_count; - /* -- Pointer on a function that retrieves a triangle from the mesh */ mesh.func_get_triangle = my_3d_mesh__get_triangle; /* Write binary STL little-endian, using default options(NULL) */