v0.2.1
Fast, portable C library for geometry input/output
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Modules
Data Structures | Enumerations | Functions
gmioSTL

Provides API to handle input/output operations with the STL file format. More...

Data Structures

struct  gmio_stl_infos
 Informations retrieved by gmio_stl_infos_get() More...
 
struct  gmio_stl_infos_get_options
 Options of function gmio_stl_infos_get() More...
 
struct  gmio_stl_read_options
 Options of function gmio_stl_read() More...
 
struct  gmio_stl_write_options
 Options of function gmio_stl_write() More...
 
struct  gmio_stl_mesh
 Provides an interface for accessing the underlying(hidden) user mesh. More...
 
struct  gmio_stl_mesh_creator_infos
 Informations about the STL stream, used in gmio_stl_mesh_creator::func_begin_solid() More...
 
struct  gmio_stl_mesh_creator
 Provides an interface for the creation of the underlying(hidden) user mesh. More...
 
struct  gmio_stl_triangle
 STL mesh triangle. More...
 
struct  gmio_stlb_header
 80-byte data at the beginning of any STL binary file More...
 

Enumerations

enum  gmio_stl_constants
 
enum  
 GMIO_STL_ERROR_TAG Byte-mask to tag(identify) STL-specific error codes More...
 
enum  gmio_stl_error
 This enum defines the various error codes reported by STL read/write functions. More...
 
enum  
 GMIO_STL_FORMAT_TAG_BINARY Byte-mask to tag(identify) STL binary formats More...
 
enum  gmio_stl_format
 This enums defines the various STL formats. More...
 
enum  gmio_stl_info_flag
 Flags(OR-combinations) for each STL info. More...
 

Functions

enum gmio_stl_format gmio_stl_format_probe (struct gmio_stream *stream)
 Returns the format of the STL data in stream. More...
 
enum gmio_stl_format gmio_stl_format_probe_file (const char *filepath)
 Returns the format of the STL data in file at location filepath. More...
 
int gmio_stl_infos_get (struct gmio_stl_infos *infos, struct gmio_stream *stream, unsigned flags, const struct gmio_stl_infos_get_options *options)
 Finds informations about STL contents. More...
 
gmio_streamsize_t gmio_stla_infos_get_streamsize (struct gmio_stream *stream, struct gmio_memblock *stream_memblock)
 Returns the size(in bytes) of the next STL ascii solid in stream. More...
 
int gmio_stl_read (struct gmio_stream *stream, struct gmio_stl_mesh_creator *mesh_creator, const struct gmio_stl_read_options *options)
 Reads STL mesh from stream, format is automatically guessed. More...
 
int gmio_stl_read_file (const char *filepath, struct gmio_stl_mesh_creator *mesh_creator, const struct gmio_stl_read_options *options)
 Reads STL mesh from a file, format is automatically guessed. More...
 
int gmio_stla_read (struct gmio_stream *stream, struct gmio_stl_mesh_creator *mesh_creator, const struct gmio_stl_read_options *options)
 Reads mesh from STL ascii stream. More...
 
int gmio_stlb_read (struct gmio_stream *stream, struct gmio_stl_mesh_creator *mesh_creator, enum gmio_endianness byte_order, const struct gmio_stl_read_options *options)
 Reads mesh from STL binary stream. More...
 
int gmio_stl_write (enum gmio_stl_format format, struct gmio_stream *stream, const struct gmio_stl_mesh *mesh, const struct gmio_stl_write_options *options)
 Writes STL mesh to stream. More...
 
int gmio_stl_write_file (enum gmio_stl_format format, const char *filepath, const struct gmio_stl_mesh *mesh, const struct gmio_stl_write_options *options)
 Writes STL mesh to stream. More...
 
int gmio_stlb_header_write (struct gmio_stream *stream, enum gmio_endianness byte_order, const struct gmio_stlb_header *header, uint32_t facet_count)
 Writes STL binary header data to stream. More...
 
void gmio_stl_triangle_compute_normal (struct gmio_stl_triangle *tri)
 Computes the normal vector of triangle tri. More...
 
struct gmio_stlb_header gmio_stlb_header_str (const char *str)
 Returns a gmio_stlb_header object whose contents is a copy of str. More...
 
void gmio_stlb_header_to_printable_str (const struct gmio_stlb_header *header, char *str, char replacement)
 Copies header into C string str. More...
 

Detailed Description

Provides API to handle input/output operations with the STL file format.

Support of the STL file format(STereoLithography) is complete :

In addition, the gmioSTL module has the following advatanges:

In this module, the name of all entities(structures, functions, ...) are prefixed either with :

Functions Structures
Read gmio_stl_read()
gmio_stl_read_file()
gmio_stla_read()
gmio_stlb_read()
gmio_stl_read_options
gmio_stl_mesh_creator
gmio_stl_mesh_creator_infos
gmio_stlb_header
Write gmio_stl_write()
gmio_stl_write_file()
gmio_stlb_header_write()
gmio_stl_write_options
gmio_stl_mesh
gmio_stlb_header
Infos on contents gmio_stl_infos_get()
gmio_stla_infos_get_streamsize()
gmio_stl_infos
gmio_stl_infos_get_options
Detect format gmio_stl_format_probe()
gmio_stl_format_probe_file()
Utilities gmio_stl_triangle_compute_normal()
gmio_stlb_header_str()
gmio_stlb_header_to_printable_str()
gmio_stl_triangle

Data Structure Documentation

struct gmio_stl_infos

Informations retrieved by gmio_stl_infos_get()

Examples:
/examples/stl_get_infos.c.
Data Fields
uint32_t facet_count Count of facets(triangles)
enum gmio_stl_format format STL format of the input stream.
gmio_streamsize_t size Size of the STL data in bytes.

For STL ascii it includes the "endsolid" tag

char * stla_solidname STL ascii only: name of the solid.

The pointer has to be set before calling gmio_stl_infos_get()

See also
stla_solidname_maxlen
size_t stla_solidname_maxlen STL ascii only: maximum length(capacity) of stla_solidname.

The value has to be set before calling gmio_stl_infos_get()

See also
stla_solidname
struct gmio_stlb_header stlb_header STL binary only: header(80-bytes) of STL data.
struct gmio_stl_infos_get_options

Options of function gmio_stl_infos_get()

Data Fields
enum gmio_stl_format format_hint Assume STL input format, if GMIO_STL_FORMAT_UNKNOWN then it is automatically guessed.
gmio_streamsize_t size_limit Restrict gmio_stl_infos_get() to not read further this limit(in bytes)
Warning
Not yet supported
struct gmio_memblock stream_memblock See gmio_stl_read_options::stream_memblock.
struct gmio_stl_write_options

Options of function gmio_stl_write()

Data Fields
bool stl_write_triangles_only Flag allowing to skip writting of any header/footer data, but just triangles.

If set to true then :

  • for STL ASCII format, "solid [name]" and "endsolid" will no be written to output stream
  • for STL binary format, the 80 bytes header followed by the mesh facet count (4bytes) will no be written to output stream
enum gmio_float_text_format stla_float32_format The format used when writting float values as strings.

Option useful only with STL ascii format (GMIO_STL_FORMAT_ASCII).

Defaulted to GMIO_FLOAT_TEXT_FORMAT_DECIMAL_LOWERCASE when calling gmio_stl_write() with options==NULL

uint8_t stla_float32_prec The maximum number of significant digits when writting float values.

Option useful only with STL ascii format (GMIO_STL_FORMAT_ASCII).

Defaulted to 9 when calling gmio_stl_write() with options==NULL

const char * stla_solid_name Name of the solid to appear in solid [name] facet normal ...

Option useful only with STL ascii format (GMIO_STL_FORMAT_ASCII).

Defaulted to an empty string "" when :

struct gmio_stlb_header stlb_header Header data(80-bytes)

Option useful only with STL binary formats (GMIO_STL_FORMAT_BINARY_LE or GMIO_STL_FORMAT_BINARY_BE).

Defaulted to an array containing 0 when :

struct gmio_memblock stream_memblock See gmio_stl_read_options::stream_memblock.
struct gmio_task_iface task_iface See gmio_stl_read_options::task_iface.
struct gmio_stl_mesh_creator_infos
Data Fields
enum gmio_stl_format format Format of the input STL mesh.
const char * stla_solid_name Null terminated C-string holding the STL mesh(solid) name.

Available only if STL ASCII format, NULL otherwise

gmio_streamsize_t stla_stream_size Total size (in bytes) of the input stream.

This is the result of gmio_stl_read_options::func_stla_get_streamsize()

Useful to roughly estimate the facet count in the input mesh. Available only if STL ASCII format, 0 otherwise

const struct gmio_stlb_header * stlb_header Contains the header data(80 bytes)

Available only if binary STL, NULL otherwise

uint32_t stlb_triangle_count Count of mesh facets(triangles)

Available only if binary STL, 0 otherwise

struct gmio_stl_triangle
Data Fields
uint16_t attribute_byte_count Useful only for STL binary format.
struct gmio_vec3f n Normal vector.
struct gmio_vec3f v1 Vertex 1.
struct gmio_vec3f v2 Vertex 2.
struct gmio_vec3f v3 Vertex 3.
struct gmio_stlb_header

80-byte data at the beginning of any STL binary file

Data Fields
uint8_t data[GMIO_STLB_HEADER_SIZE]

Enumeration Type Documentation

anonymous enum

GMIO_STL_ERROR_TAG Byte-mask to tag(identify) STL-specific error codes

Enumerator
GMIO_STL_ERROR_TAG 
anonymous enum

GMIO_STL_FORMAT_TAG_BINARY Byte-mask to tag(identify) STL binary formats

Enumerator
GMIO_STL_FORMAT_TAG_BINARY 
Enumerator
GMIO_STL_COORDS_RAWSIZE 

Compact size of a gmio_vec3f object.

GMIO_STLA_TRIANGLE_RAWSIZE 

Compact size of a gmio_stl_triangle object, STL ascii format.

GMIO_STLB_TRIANGLE_RAWSIZE 

Compact size of a gmio_stl_triangle object, STL binary format.

GMIO_STLB_HEADER_SIZE 

Size(in bytes) of the header data for STL binary.

GMIO_STLB_MIN_CONTENTS_SIZE 

Size(in bytes) of the minimum contents possible with the STL binary format.

This enum defines the various error codes reported by STL read/write functions.

Enumerator
GMIO_STL_ERROR_UNKNOWN_FORMAT 

STL format could not be guessed in read function.

GMIO_STL_ERROR_NULL_FUNC_GET_TRIANGLE 

Common STL write error indicating gmio_stl_mesh::func_get_triangle() pointer is NULL.

GMIO_STL_ERROR_PARSING 

Parsing error occured due to malformed STL ascii input.

GMIO_STL_ERROR_INVALID_FLOAT32_PREC 

Invalid max number of decimal significants digits must be in [1..9].

GMIO_STL_ERROR_UNSUPPORTED_BYTE_ORDER 

The byte order argument supplied is not supported, must be little or big endian.

GMIO_STL_ERROR_HEADER_WRONG_SIZE 

Error occured when reading header data in gmio_stlb_read()

GMIO_STL_ERROR_FACET_COUNT 

Error occured when reading facet count in gmio_stlb_read()

This enums defines the various STL formats.

Enumerator
GMIO_STL_FORMAT_UNKNOWN 

Unknown STL format.

GMIO_STL_FORMAT_ASCII 

STL ASCII (text)

GMIO_STL_FORMAT_BINARY_LE 

STL binary (little-endian)

GMIO_STL_FORMAT_BINARY_BE 

STL binary (big-endian)

Flags(OR-combinations) for each STL info.

Enumerator
GMIO_STL_INFO_FLAG_FACET_COUNT 

-> gmio_stl_infos::facet_count

GMIO_STL_INFO_FLAG_SIZE 

-> gmio_stl_infos::size

GMIO_STLA_INFO_FLAG_SOLIDNAME 

-> gmio_stl_infos::stla_solidname

GMIO_STLB_INFO_FLAG_HEADER 

-> gmio_stl_infos::stlb_header

GMIO_STL_INFO_FLAG_SOLIDNAME_OR_HEADER 

-> gmio_stl_infos::stla_solidname or gmio_stl_infos::stlb_header

GMIO_STL_INFO_FLAG_FORMAT 

-> gmio_stl_infos::format

GMIO_STL_INFO_FLAG_ALL 

All infos.

Function Documentation

enum gmio_stl_format gmio_stl_format_probe ( struct gmio_stream stream)

Returns the format of the STL data in stream.

It will try to read 512 bytes from stream into a buffer and then analyses this data to guess the format.

The position of the input stream is preserved.

Return values
GMIO_STL_FORMAT_UNKNOWNin case of error.
enum gmio_stl_format gmio_stl_format_probe_file ( const char *  filepath)

Returns the format of the STL data in file at location filepath.

This function is a wrapper around gmio_stl_format_probe()

Parameters
filepathPath to the STL file. A stream is opened with fopen() so the string shall follow the file name specifications of the running environment
int gmio_stl_infos_get ( struct gmio_stl_infos infos,
struct gmio_stream stream,
unsigned  flags,
const struct gmio_stl_infos_get_options options 
)

Finds informations about STL contents.

infos is an output parameter that will hold the retrieved informations

flags is a bitor combination of gmio_stl_info_flag values and is used to select the informations to retrieve.

Precondition
infos != NULL
stream != NULL

options can be safely set to NULL in this case default values are used

Returns
Error code (see gmio_core/error.h and stl_error.h)
Examples:
/examples/stl_get_infos.c.
int gmio_stl_read ( struct gmio_stream stream,
struct gmio_stl_mesh_creator mesh_creator,
const struct gmio_stl_read_options options 
)

Reads STL mesh from stream, format is automatically guessed.

The user mesh is created sequentially by calling gmio_stl_mesh_creator::func_add_triangle() with each triangle read from the stream.

It does nothing on the triangles read : no checking(eg. for Nan values), normals are given as they are.

Precondition
stream != NULL
mesh_creator != NULL

options may be NULL in this case default values are used

Returns
Error code (see gmio_core/error.h and stl_error.h)
See also
gmio_stl_read_file()
int gmio_stl_read_file ( const char *  filepath,
struct gmio_stl_mesh_creator mesh_creator,
const struct gmio_stl_read_options options 
)

Reads STL mesh from a file, format is automatically guessed.

This is just a facility function over gmio_stl_read(). The internal stream object is created to read file at filepath.

Precondition
filepath != NULL
The file is opened with fopen() so filepath shall follow the file name specifications of the running environment
mesh_creator != NULL

options may be NULL in this case default values are used

Returns
Error code (see gmio_core/error.h and stl_error.h)
See also
gmio_stl_read(), gmio_stream_stdio(FILE*)
Examples:
/examples/occstl_read_file.cpp, /examples/occstl_redefine_mesh_creator.cpp, and /examples/stl_read_file.c.
void gmio_stl_triangle_compute_normal ( struct gmio_stl_triangle tri)

Computes the normal vector of triangle tri.

Examples:
/examples/stl_write_file.c.
int gmio_stl_write ( enum gmio_stl_format  format,
struct gmio_stream stream,
const struct gmio_stl_mesh mesh,
const struct gmio_stl_write_options options 
)

Writes STL mesh to stream.

Precondition
stream != NULL
mesh != NULL

options may be NULL in this case default values are used

Returns
Error code (see gmio_core/error.h and stl_error.h)
See also
gmio_stl_write_file()
int gmio_stl_write_file ( enum gmio_stl_format  format,
const char *  filepath,
const struct gmio_stl_mesh mesh,
const struct gmio_stl_write_options options 
)

Writes STL mesh to stream.

This is just a facility function over gmio_stl_write(). The internal stream object is created to read file at filepath

Precondition
filepath != NULL
The file is opened with fopen() so filepath shall follow the file name specifications of the running environment
mesh != NULL
Returns
Error code (see gmio_core/error.h and stl_error.h)
See also
gmio_stl_write(), gmio_stream_stdio(FILE*)
Examples:
/examples/occstl_write_file.cpp, and /examples/stl_write_file.c.
gmio_streamsize_t gmio_stla_infos_get_streamsize ( struct gmio_stream stream,
struct gmio_memblock stream_memblock 
)

Returns the size(in bytes) of the next STL ascii solid in stream.

It is a facade over gmio_stl_infos_get() for gmio_stl_infos::size only

Pointer to this function can be given to gmio_stl_read_options::func_stla_get_streamsize() and is useful when reading in sequence multi solids in STL ascii. The stream can be cleanly advanced solid by solid after each call to gmio_stl_read()

Precondition
stream != NULL
stream_memblock != NULL
int gmio_stla_read ( struct gmio_stream stream,
struct gmio_stl_mesh_creator mesh_creator,
const struct gmio_stl_read_options options 
)

Reads mesh from STL ascii stream.

Precondition
stream != NULL
mesh_creator != NULL

options may be NULL in this case default values are used

Returns
Error code (see gmio_core/error.h and stl_error.h)
See also
gmio_stl_read(), gmio_stl_read_file()
struct gmio_stlb_header gmio_stlb_header_str ( const char *  str)

Returns a gmio_stlb_header object whose contents is a copy of str.

Only the first GMIO_STLB_HEADER_SIZE characters are copied.

If the length of str is less than GMIO_STLB_HEADER_SIZE then the remaining bytes are filled with zeroes.

void gmio_stlb_header_to_printable_str ( const struct gmio_stlb_header header,
char *  str,
char  replacement 
)

Copies header into C string str.

It replaces non-printable bytes with replacement char.

str must be at least GMIO_STLB_HEADER_SIZE+1 long, a terminating null character ('\0') is copied at position GMIO_STLB_HEADER_SIZE

int gmio_stlb_header_write ( struct gmio_stream stream,
enum gmio_endianness  byte_order,
const struct gmio_stlb_header header,
uint32_t  facet_count 
)

Writes STL binary header data to stream.

This functions only writes the 80-bytes header array and the count of facets of the mesh(with respect of the specified byte order).

Precondition
stream != NULL

header Can be safely set to NULL to generate an array of zeroes

Returns
Error code (see gmio_core/error.h and stl_error.h)
int gmio_stlb_read ( struct gmio_stream stream,
struct gmio_stl_mesh_creator mesh_creator,
enum gmio_endianness  byte_order,
const struct gmio_stl_read_options options 
)

Reads mesh from STL binary stream.

Precondition
stream != NULL
mesh_creator != NULL

options may be NULL in this case default values are used

Returns
Error code (see gmio_core/error.h and stl_error.h)
Return values
GMIO_ERROR_INVALID_MEMBLOCK_SIZEif options->stream_memblock.size < GMIO_STLB_MIN_CONTENTS_SIZE
See also
gmio_stl_read(), gmio_stl_read_file()
Fougue © 2016