GTS Library Reference Manual |
---|
#include <gts.h> #define GTS_SURFACE_CLASS (klass) #define GTS_SURFACE (obj) #define GTS_IS_SURFACE (obj) struct GtsSurfaceClass; struct GtsSurface; GtsSurfaceClass* gts_surface_class (void); GtsSurface* gts_surface_new (GtsSurfaceClass *klass, GtsFaceClass *face_class, GtsEdgeClass *edge_class, GtsVertexClass *vertex_class); void gts_surface_add_face (GtsSurface *s, GtsFace *f); void gts_surface_remove_face (GtsSurface *s, GtsFace *f); GtsSurface* gts_surface_copy (GtsSurface *s1, GtsSurface *s2); void gts_surface_merge (GtsSurface *s, GtsSurface *with);guint gts_surface_read (GtsSurface *surface, GtsFile *f);gboolean gts_surface_is_manifold (GtsSurface *s);gboolean gts_surface_is_orientable (GtsSurface *s);gboolean gts_surface_is_closed (GtsSurface *s);guint gts_surface_vertex_number (GtsSurface *s);guint gts_surface_edge_number (GtsSurface *s);guint gts_surface_face_number (GtsSurface *s);GSList * gts_surface_boundary (GtsSurface *surface);gdouble gts_surface_area (GtsSurface *s);gdouble gts_surface_volume (GtsSurface *s);gdouble gts_surface_center_of_mass (GtsSurface *s,GtsVector cm);gdouble gts_surface_center_of_area (GtsSurface *s,GtsVector cm); struct GtsSurfaceStats; struct GtsSurfaceQualityStats; void gts_surface_stats (GtsSurface *s, GtsSurfaceStats *stats); void gts_surface_quality_stats (GtsSurface *s, GtsSurfaceQualityStats *stats); void gts_surface_print_stats (GtsSurface *s,FILE *fptr); void gts_surface_write (GtsSurface *s,FILE *fptr); void gts_surface_write_oogl (GtsSurface *s,FILE *fptr); void gts_surface_write_oogl_boundary (GtsSurface *s,FILE *fptr); void gts_surface_write_vtk (GtsSurface *s,FILE *fptr);gint (*GtsFunc) (gpointer item,gpointer data); void gts_surface_foreach_vertex (GtsSurface *s, GtsFunc func,gpointer data); void gts_surface_foreach_edge (GtsSurface *s, GtsFunc func,gpointer data); void gts_surface_foreach_face (GtsSurface *s, GtsFunc func,gpointer data);guint gts_surface_foreach_face_remove (GtsSurface *s, GtsFunc func,gpointer data);gboolean gts_surface_foreach_intersecting_face (GtsSurface *s, GtsBBTreeTraverseFunc func,gpointer data); struct GtsSurfaceTraverse; GtsSurfaceTraverse* gts_surface_traverse_new (GtsSurface *s, GtsFace *f); GtsFace* gts_surface_traverse_next (GtsSurfaceTraverse *t,guint *level); void gts_surface_traverse_destroy (GtsSurfaceTraverse *t); void gts_surface_distance (GtsSurface *s1, GtsSurface *s2,gdouble delta, GtsRange *face_range, GtsRange *boundary_range);GSList * gts_surface_strip (GtsSurface *s); void gts_surface_tessellate (GtsSurface *s, GtsRefineFunc refine_func,gpointer refine_data); GtsSurface* gts_surface_generate_sphere (GtsSurface *s,guint geodesation_order);GSList * gts_surface_split (GtsSurface *s);
A GtsSurface is defined as a collection of GtsFace. No topological constraint is imposed: the surface may or may not be manifold, closed or orientable.
When destroying a GtsSurface, all the faces not used by another surface are also destroyed. This default behaviour can be changed punctually by setting the global variable gts_allow_floating_faces to TRUE. You must not forget to set this variable back to FALSE as all the algorithms of GTS assume the default behaviour.
#define GTS_SURFACE_CLASS(klass)
Casts klass to GtsSurfaceClass.
klass : | a descendant of GtsSurfaceClass. |
#define GTS_IS_SURFACE(obj)
Evaluates to TRUE if obj is a GtsSurface, FALSE otherwise.
obj : | a pointer to test. |
struct GtsSurfaceClass { GtsObjectClass parent_class; void (* add_face) (GtsSurface *, GtsFace *); void (* remove_face) (GtsSurface *, GtsFace *); };
The surface class. No virtual function is defined.
struct GtsSurface { GtsObject object; #ifdef USE_SURFACE_BTREE GTree * faces; #else /* not USE_SURFACE_BTREE */ GHashTable * faces; #endif /* not USE_SURFACE_BTREE */ GtsFaceClass * face_class; GtsEdgeClass * edge_class; GtsVertexClass * vertex_class; gboolean keep_faces; };
The surface structure derived from GtsObject. This structure should only be accessed through the following functions.
GtsSurface* gts_surface_new (GtsSurfaceClass *klass, GtsFaceClass *face_class, GtsEdgeClass *edge_class, GtsVertexClass *vertex_class);
klass : | |
face_class : | a GtsFaceClass. |
edge_class : | a GtsEdgeClass. |
vertex_class : | |
Returns : | a new empty GtsSurface. |
void gts_surface_add_face (GtsSurface *s, GtsFace *f);
Adds face f to surface s.
s : | a GtsSurface. |
f : | a GtsFace. |
void gts_surface_remove_face (GtsSurface *s, GtsFace *f);
Removes face f from surface s.
s : | a GtsSurface. |
f : | a GtsFace. |
GtsSurface* gts_surface_copy (GtsSurface *s1, GtsSurface *s2);
Add a copy of all the faces, edges and vertices of s2 to s1.
s1 : | a GtsSurface. |
s2 : | a GtsSurface. |
Returns : | s1. |
void gts_surface_merge (GtsSurface *s, GtsSurface *with);
Adds all the faces of with which do not already belong to s to s.
s : | a GtsSurface. |
with : | another GtsSurface. |
guint gts_surface_read (GtsSurface *surface, GtsFile *f);
Add to surface the data read from f. The format of the file pointed to by f is as described in gts_surface_write().
surface : | a GtsSurface. |
f : | a GtsFile. |
Returns : | 0 if successful or the line number at which the parsing stopped in case of error (in which case the error field of f is set to a description of the error which occured). |
gboolean gts_surface_is_manifold (GtsSurface *s);
s : | a GtsSurface. |
Returns : | TRUE if the surface is a manifold, FALSE otherwise. |
gboolean gts_surface_is_orientable (GtsSurface *s);
s : | a GtsSurface. |
Returns : | TRUE if all the faces of s have compatible orientation
as checked by |
gboolean gts_surface_is_closed (GtsSurface *s);
s : | a GtsSurface. |
Returns : | TRUE if s is a closed surface, FALSE otherwise. Note that a closed surface is also a manifold. |
guint gts_surface_vertex_number (GtsSurface *s);
s : | a GtsSurface. |
Returns : | the number of vertices of s. |
guint gts_surface_edge_number (GtsSurface *s);
s : | a GtsSurface. |
Returns : | the number of edges of s. |
guint gts_surface_face_number (GtsSurface *s);
s : | a GtsSurface. |
Returns : | the number of faces of s |
GSList * gts_surface_boundary (GtsSurface *surface);
surface : | a GtsSurface. |
Returns : | a list of GtsEdge boundary of surface. |
gdouble gts_surface_area (GtsSurface *s);
s : | a GtsSurface. |
Returns : | the area of s obtained as the sum of the signed areas of its faces. |
gdouble gts_surface_volume (GtsSurface *s);
s : | a GtsSurface. |
Returns : | the signed volume of the domain bounded by the surface s. It makes sense only if s is a closed and orientable manifold. |
gdouble gts_surface_center_of_mass (GtsSurface *s,GtsVector cm);
Fills cm with the coordinates of the center of mass of s.
s : | a GtsSurface. |
cm : | a |
Returns : | the signed volume of the domain bounded by the surface s. |
gdouble gts_surface_center_of_area (GtsSurface *s,GtsVector cm);
Fills cm with the coordinates of the center of area of s.
s : | a GtsSurface. |
cm : | a |
Returns : | the area of surface s. |
struct GtsSurfaceStats { guint n_faces; guint n_incompatible_faces; guint n_duplicate_faces; guint n_duplicate_edges; guint n_boundary_edges; guint n_non_manifold_edges; GtsRange edges_per_vertex, faces_per_edge; GtsSurface * parent; };
Connectivity statistics.
n_faces | Number of faces. |
n_incompatible_faces | Number of incompatible faces (see gts_triangles_are_compatible() for details). |
n_duplicate_faces | Number of duplicate faces (see gts_triangle_is_duplicate() for details). |
n_duplicate_edges | Number of duplicate edges (see gts_segment_is_duplicate() for details). |
n_boundary_edges | Number of boundary edges. |
n_non_manifold_edges | Number of non-manifold edges. |
GtsRange edges_per_vertex | Statistics on the number of edges per vertex. |
GtsRange faces_per_edge | Statistics on the number of faces per vertex. |
GtsSurface *parent | Surface from which these statistics have been obtained. |
struct GtsSurfaceQualityStats { GtsRange face_quality; GtsRange face_area; GtsRange edge_length; GtsRange edge_angle; GtsSurface * parent; };
Quality and geometry statistics.
GtsRange face_quality | Statistics for face quality (see gts_triangle_quality() for details). |
GtsRange face_area | Statistics for the face area. |
GtsRange edge_length | Statistics for the edge length. |
GtsRange edge_angle | Statistics for the edge angles. |
GtsSurface *parent | Surface from which these statistics have been obtained. |
void gts_surface_stats (GtsSurface *s, GtsSurfaceStats *stats);
Fills stats with the statistics relevant to surface s.
s : | a GtsSurface. |
stats : |
void gts_surface_quality_stats (GtsSurface *s, GtsSurfaceQualityStats *stats);
Fills stats with quality statistics relevant to surface s.
s : | a GtsSurface. |
stats : |
void gts_surface_print_stats (GtsSurface *s,FILE *fptr);
Writes in the file pointed to by fptr the statistics for surface s.
s : | a GtsSurface. |
fptr : | a file pointer. |
void gts_surface_write (GtsSurface *s,FILE *fptr);
Writes in the file fptr an ASCII representation of s. The file format is as follows.
All the lines beginning with GTS_COMMENTS are ignored. The first line contains three unsigned integers separated by spaces. The first integer is the number of vertices, nv, the second is the number of edges, ne and the third is the number of faces, nf.
Follows nv lines containing the x, y and z coordinates of the vertices. Follows ne lines containing the two indices (starting from one) of the vertices of each edge. Follows nf lines containing the three ordered indices (also starting from one) of the edges of each face.
The format described above is the least common denominator to all
GTS files. Consistent with an object-oriented approach, the GTS
file format is extensible. Each of the lines of the file can be
extended with user-specific attributes accessible through the
s : | a GtsSurface. |
fptr : | a file pointer. |
void gts_surface_write_oogl (GtsSurface *s,FILE *fptr);
Writes in the file fptr an OOGL (Geomview) representation of s.
s : | a GtsSurface. |
fptr : | a file pointer. |
void gts_surface_write_oogl_boundary (GtsSurface *s,FILE *fptr);
Writes in the file fptr an OOGL (Geomview) representation of the boundary of s.
s : | a GtsSurface. |
fptr : | a file pointer. |
void gts_surface_write_vtk (GtsSurface *s,FILE *fptr);
Writes in the file fptr a VTK representation of s.
s : | a GtsSurface. |
fptr : | a file pointer. |
gint (*GtsFunc) (gpointer item,gpointer data);
A user function called for each item of a collection.
item : | a pointer this function is called for. |
data : | user data passed to the function. |
Returns : | if 0 the calling sequence continues, otherwise it stops. |
void gts_surface_foreach_vertex (GtsSurface *s, GtsFunc func,gpointer data);
Calls func once for each vertex of s.
s : | a GtsSurface. |
func : | a GtsFunc. |
data : | user data to be passed to func. |
void gts_surface_foreach_edge (GtsSurface *s, GtsFunc func,gpointer data);
Calls func once for each edge of s.
s : | a GtsSurface. |
func : | a GtsFunc. |
data : | user data to be passed to func. |
void gts_surface_foreach_face (GtsSurface *s, GtsFunc func,gpointer data);
Calls func once for each face of s.
s : | a GtsSurface. |
func : | a GtsFunc. |
data : | user data to be passed to func. |
guint gts_surface_foreach_face_remove (GtsSurface *s, GtsFunc func,gpointer data);
Calls func once for each face of s. If func returns TRUE the
corresponding face is removed from s (and destroyed if it does not
belong to any other surface and
s : | a GtsSurface. |
func : | a GtsFunc. |
data : | user data to be passed to func. |
Returns : | the number of faces removed from s. |
gboolean gts_surface_foreach_intersecting_face (GtsSurface *s, GtsBBTreeTraverseFunc func,gpointer data);
Calls func for each intersecting pair of faces of s.
s : | a GtsSurface. |
func : | |
data : | user data to pass to func. |
Returns : | TRUE if func was called at least once, FALSE otherwise. |
GtsSurfaceTraverse* gts_surface_traverse_new (GtsSurface *s, GtsFace *f);
s : | a GtsSurface. |
f : | a GtsFace belonging to s. |
Returns : | a new GtsSurfaceTraverse, initialized to start traversing from face f of surface s. |
GtsFace* gts_surface_traverse_next (GtsSurfaceTraverse *t,guint *level);
t : | |
level : | a pointer to a guint or NULL. |
Returns : | the next face of the traversal in breadth-first order or NULL if no faces are left. If level if not NULL, it is filled with the level of the returned face (0 for the initial face, 1 for its neighbors and so on). |
void gts_surface_traverse_destroy (GtsSurfaceTraverse *t);
Frees all the memory allocated for t.
t : |
void gts_surface_distance (GtsSurface *s1, GtsSurface *s2,gdouble delta, GtsRange *face_range, GtsRange *boundary_range);
Using the gts_bb_tree_surface_distance() and gts_bb_tree_surface_boundary_distance() functions fills face_range and boundary_range with the min, max and average Euclidean (minimum) distances between the faces of s1 and the faces of s2 and between the boundary edges of s1 and s2.
s1 : | a GtsSurface. |
s2 : | a GtsSurface. |
delta : | a spatial increment defined as the percentage of the diagonal of the bounding box of s2. |
face_range : | a GtsRange. |
boundary_range : | a GtsRange. |
GSList * gts_surface_strip (GtsSurface *s);
Decompose s into triangle strips for fast-rendering.
s : | a GtsSurface. |
Returns : | a list of triangle strips containing all the triangles of s. A triangle strip is itself a list of successive triangles having one edge in common. |
void gts_surface_tessellate (GtsSurface *s, GtsRefineFunc refine_func,gpointer refine_data);
Tessellate each triangle of s with 4 triangles: the number of triangles is increased by a factor of 4. http://mathworld.wolfram.com/GeodesicDome.html
If refine_func is set to NULL a mid arc function is used: if the surface is a polyhedron with the unit sphere as circum sphere, then gts_surface_tessellate() corresponds to a geodesation step (see gts_surface_generate_sphere()).
s : | a GtsSurface. |
refine_func : | |
refine_data : | user data to be passed to refine_func. |
GtsSurface* gts_surface_generate_sphere (GtsSurface *s,guint geodesation_order);
Add a triangulated unit sphere generated by recursive subdivision to s. First approximation is an isocahedron; each level of refinement (geodesation_order) increases the number of triangles by a factor of 4. http://mathworld.wolfram.com/GeodesicDome.html
s : | a GtsSurface. |
geodesation_order : | a |
Returns : | s. |
GSList * gts_surface_split (GtsSurface *s);
Splits a surface into connected and manifold components.
s : | a GtsSurface. |
Returns : | a list of new GtsSurface. |
<<< Faces | Geometrical data structures >>> |