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 :

• ASCII format: Case-insensitive reading
• ASCII format: Support of output format(%f, %e, ...) and precision of floats
• Binary format: Support of little/big endianness
• Binary format: Support of 80-byte header and facet "attribute byte count"
• Support of multiple solids from stream(eg. 4 solids in STL ascii file)
• Detection of the input format
• Retrieval of infomations about contents

In addition, the gmioSTL module has the following advatanges:

• The user keeps its own geometry data structures, no conversion needed.
• Fixed memory consumption and independant of the mesh size
• Seamless use of OpenCascade in gmio(see gmioSupport module)

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

• gmio_stl
• gmio_stla, this applies only for STL ascii
• gmio_stlb, this applies only for STL binary(little/big endian)

	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 : calling gmio_stl_write() with options == NULL OR stla_solid_name == NULL
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 : calling gmio_stl_write() with options == NULL OR stlb_header == NULL
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

Informations about the STL stream, used in gmio_stl_mesh_creator::func_begin_solid()

Examples:

/examples/occstl_redefine_mesh_creator.cpp, and /examples/stl_read_file.c.

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

STL mesh triangle.

Examples:

/examples/occstl_redefine_mesh_creator.cpp, /examples/stl_read_file.c, and /examples/stl_write_file.c.

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

enum gmio_stl_constants

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.

enum gmio_stl_error

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

enum gmio_stl_format

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)

enum gmio_stl_info_flag

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_UNKNOWN

in 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

filepath

Path 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_SIZE

if options->stream_memblock.size < GMIO_STLB_MIN_CONTENTS_SIZE

See also

gmio_stl_read(), gmio_stl_read_file()