caiyu/gmio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve doc

Browse Source
This commit is contained in:
Hugues Delorme 2016-03-14 15:53:22 +01:00
parent 9c83cf96e9
commit 2764e77c56
9 changed files with 116 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
README.md
View File

@ -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:

6
doc/Doxyfile.cmake
View File

@ -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

88
doc/mainpage.c Normal file
View File

@ -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. <a href="https://en.wikipedia.org/wiki/STL_%28file_format%29">STL</a>)
gmio aims to be <a href="https://github.com/fougue/gmio/wiki/4.-Benchmarks">fast</a>,
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 <a href="https://github.com/fougue/gmio/wiki/2.-Build-instructions">Build instructions</a>
\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
<a href="http://www.cecill.info/licences/Licence_CeCILL-B_V1-en.html">URL</a>
\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
*/

3
examples/occstl_read_file.cpp
View File

@ -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)

8
examples/occstl_redefine_mesh_creator.cpp
View File

@ -10,7 +10,7 @@
#include <StlMesh_Mesh.hxx>
#include <iostream>
// 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;

7
examples/occstl_write_file.cpp
View File

@ -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)

22
examples/stl_get_infos.c
View File

@ -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);

20
examples/stl_read_file.c
View File

@ -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) */

6
examples/stl_write_file.c
View File

@ -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) */