GTS Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# Triangles

## Name

Triangles -- triangle object and related functions.

## Synopsis

    #include <gts.h>

    #define     GTS_TRIANGLE_CLASS              (klass)
    #define     GTS_TRIANGLE                    (obj)
    #define     GTS_IS_TRIANGLE                 (obj)
    struct      GtsTriangleClass;
    struct      GtsTriangle;

    GtsTriangleClass* gts_triangle_class        (void);
    GtsTriangle* gts_triangle_new               (GtsTriangleClass *klass,
                                                 GtsEdge *e1,
                                                 GtsEdge *e2,
                                                 GtsEdge *e3);
    void        gts_triangle_set                (GtsTriangle *triangle,
                                                 GtsEdge *e1,
                                                 GtsEdge *e2,
                                                 GtsEdge *e3);
    gdouble     gts_triangle_area               (GtsTriangle *t);
    gdouble     gts_triangle_perimeter          (GtsTriangle *t);
    gdouble     gts_triangle_quality            (GtsTriangle *t);
    void        gts_triangle_normal             (GtsTriangle *t,
                                                 gdouble *x,
                                                 gdouble *y,
                                                 gdouble *z);
    void        gts_triangle_revert             (GtsTriangle *t);
    gdouble     gts_triangle_orientation        (GtsTriangle *t);
    GtsTriangle* gts_triangle_is_duplicate      (GtsTriangle *t);
    gdouble     gts_triangles_angle             (GtsTriangle *t1,
                                                 GtsTriangle *t2);
    gboolean    gts_triangles_are_compatible    (GtsTriangle *t1,
                                                 GtsTriangle *t2,
                                                 GtsEdge *e);
    GtsTriangle* gts_triangle_enclosing         (GtsTriangleClass *klass,
                                                 GSList *points,
                                                 gdouble scale);
    GtsEdge*    gts_triangles_common_edge       (GtsTriangle *t1,
                                                 GtsTriangle *t2);
    guint       gts_triangle_neighbor_number    (GtsTriangle *t);
    GSList*     gts_triangle_neighbors          (GtsTriangle *t);
    void        gts_triangle_vertices_edges     (GtsTriangle *t,
                                                 GtsEdge *e,
                                                 GtsVertex **v1,
                                                 GtsVertex **v2,
                                                 GtsVertex **v3,
                                                 GtsEdge **e1,
                                                 GtsEdge **e2,
                                                 GtsEdge **e3);
    GtsVertex*  gts_triangle_vertex_opposite    (GtsTriangle *t,
                                                 GtsEdge *e);
    GtsEdge*    gts_triangle_edge_opposite      (GtsTriangle *t,
                                                 GtsVertex *v);
    void        gts_triangle_vertices           (GtsTriangle *t,
                                                 GtsVertex **v1,
                                                 GtsVertex **v2,
                                                 GtsVertex **v3);
    #define     gts_triangle_vertex             (t)
    gboolean    gts_triangle_is_ok              (GtsTriangle *t);
    GtsTriangle* gts_triangle_use_edges         (GtsEdge *e1,
                                                 GtsEdge *e2,
                                                 GtsEdge *e3);
    GtsPoint*   gts_triangle_circumcircle_center
                                                (GtsTriangle *t,
                                                 GtsPointClass *point_class);
    GtsObject*  gts_triangle_is_stabbed         (GtsTriangle *t,
                                                 GtsPoint *p,
                                                 gdouble *orientation);
    gboolean    gts_triangles_are_folded        (GSList *triangles,
                                                 GtsVertex *A,
                                                 GtsVertex *B,
                                                 gdouble max);
    GSList*     gts_triangles_from_edges        (GSList *edges);

## Description

A GtsTriangle is defined by three GtsEdge. They are oriented, the normal to the triangle points toward an observer seing the three edges in counter-clockwise order.

When destroying a GtsTriangle, all the edges not used by another triangle are also destroyed. This default behaviour can be changed punctually by setting the global variable gts_allow_floating_edges to `TRUE`. You must not forget to set this variable back to `FALSE` as all the algorithms of GTS assume the default behaviour.

## Details

### GTS_TRIANGLE_CLASS()

    #define     GTS_TRIANGLE_CLASS(klass)

Casts `klass` to GtsTriangleClass.

`klass` : | a descendant of GtsTriangleClass.

### GTS_TRIANGLE()

    #define     GTS_TRIANGLE(obj)

Casts `obj` to GtsTriangle.

`obj` : | a descendant of GtsTriangle.

### GTS_IS_TRIANGLE()

    #define     GTS_IS_TRIANGLE(obj)

Evaluates to `TRUE` if `obj` is a descendant of GtsTriangle, `FALSE` otherwise.

`obj` : | a pointer to test.

### struct GtsTriangleClass

    struct GtsTriangleClass;

The triangle class, just derived from GtsObject.

### struct GtsTriangle

    struct GtsTriangle {
      GtsObject object;

      GtsEdge * e1;
      GtsEdge * e2;
      GtsEdge * e3;
    };

The triangle object.

GtsObject `object` | Parent object.
GtsEdge *`e1` | First edge.
GtsEdge *`e2` | Second edge.
GtsEdge *`e3` | Third edge.

### gts_triangle_class ()

    GtsTriangleClass* gts_triangle_class        (void);

Returns : | the GtsTriangleClass.

### gts_triangle_new ()

    GtsTriangle* gts_triangle_new               (GtsTriangleClass *klass,
                                                 GtsEdge *e1,
                                                 GtsEdge *e2,
                                                 GtsEdge *e3);

`klass` : | a GtsTriangleClass.
`e1` : | a GtsEdge.
`e2` : | another GtsEdge touching `e1`.
`e3` : | another GtsEdge touching both `e1` and `e2`.
Returns : | a new GtsTriangle having `e1`, `e2` and `e3` as edges.

### gts_triangle_set ()

    void        gts_triangle_set                (GtsTriangle *triangle,
                                                 GtsEdge *e1,
                                                 GtsEdge *e2,
                                                 GtsEdge *e3);

Sets the edge of `triangle` to `e1`, `e2` and `e3` while checking that they define a valid triangle.

`triangle` : | a GtsTriangle.
`e1` : | a GtsEdge.
`e2` : | another GtsEdge touching `e1`.
`e3` : | another GtsEdge touching both `e1` and `e2`.

### gts_triangle_area ()

    gdouble     gts_triangle_area               (GtsTriangle *t);

`t` : | a GtsTriangle.
Returns : | the area of the triangle `t`.

### gts_triangle_perimeter ()

    gdouble     gts_triangle_perimeter          (GtsTriangle *t);

`t` : | a GtsTriangle.
Returns : | the perimeter of the triangle `t`.

### gts_triangle_quality ()

    gdouble     gts_triangle_quality            (GtsTriangle *t);

The quality of a triangle is defined as the ratio of its surface to its perimeter relative to this same ratio for an equilateral triangle with the same area. The quality is then one for an equilateral triangle and tends to zero for a very stretched triangle.

`t` : | a GtsTriangle.
Returns : | the quality of the triangle `t`.

### gts_triangle_normal ()

    void        gts_triangle_normal             (GtsTriangle *t,
                                                 gdouble *x,
                                                 gdouble *y,
                                                 gdouble *z);

Computes the coordinates of the oriented normal of `t` as the cross-product of two edges, using the left-hand rule. The normal is not normalized. If this triangle is part of a closed and oriented surface, the normal points to the outside of the surface.

`t` : | a GtsTriangle.
`x` : | the x coordinate of the normal.
`y` : | the y coordinate of the normal.
`z` : | the z coordinate of the normal.

### gts_triangle_revert ()

    void        gts_triangle_revert             (GtsTriangle *t);

Changes the orientation of triangle `t`, turning it inside out.

`t` : | a GtsTriangle.

### gts_triangle_orientation ()

    gdouble     gts_triangle_orientation        (GtsTriangle *t);

Checks for the orientation of the plane (x,y) projection of a triangle. See gts_point_orientation() for details. This function is geometrically robust.

`t` : | a GtsTriangle.
Returns : | a number depending on the orientation of the vertices of `t`.

### gts_triangle_is_duplicate ()

    GtsTriangle* gts_triangle_is_duplicate      (GtsTriangle *t);

`t` : | a GtsTriangle.
Returns : | a GtsTriangle different from `t` but sharing all its edges with `t` or `NULL` if there is none.

### gts_triangles_angle ()

    gdouble     gts_triangles_angle             (GtsTriangle *t1,
                                                 GtsTriangle *t2);

`t1` : | a GtsTriangle.
`t2` : | a GtsTriangle.
Returns : | the value (in radians) of the angle between `t1` and `t2`.

### gts_triangles_are_compatible ()

    gboolean    gts_triangles_are_compatible    (GtsTriangle *t1,
                                                 GtsTriangle *t2,
                                                 GtsEdge *e);

Checks if `t1` and `t2` have compatible orientations i.e. if `t1` and `t2` can be part of the same surface without conflict in the surface normal orientation.

`t1` : | a GtsTriangle.
`t2` : | a GtsTriangle.
`e` : | a GtsEdge used by both `t1` and `t2`.
Returns : | `TRUE` if `t1` and `t2` are compatible, `FALSE` otherwise.

### gts_triangle_enclosing ()

    GtsTriangle* gts_triangle_enclosing         (GtsTriangleClass *klass,
                                                 GSList *points,
                                                 gdouble scale);

Builds a new triangle (including new vertices and edges) enclosing the plane projection of all the points in `points`. This triangle is equilateral and encloses a rectangle defined by the maximum and minimum x and y coordinates of the points. `scale` is an homothetic scaling factor. If equal to one, the triangle encloses exactly the enclosing rectangle.

`klass` : | the class of the new triangle.
`points` : | a list of GtsPoint.
`scale` : | a scaling factor (must be larger than one).
Returns : | a new GtsTriangle.

### gts_triangles_common_edge ()

    GtsEdge*    gts_triangles_common_edge       (GtsTriangle *t1,
                                                 GtsTriangle *t2);

`t1` : | a GtsTriangle.
`t2` : | a GtsTriangle.
Returns : | a GtsEdge common to both `t1` and `t2` or `NULL` if `t1` and `t2` do not share any edge.

### gts_triangle_neighbor_number ()

    guint       gts_triangle_neighbor_number    (GtsTriangle *t);

`t` : | a GtsTriangle.
Returns : | the number of triangles neighbors of `t`.

### gts_triangle_neighbors ()

    GSList*     gts_triangle_neighbors          (GtsTriangle *t);

`t` : | a GtsTriangle.
Returns : | a list of GtsTriangle neighbors of `t`.

### gts_triangle_vertices_edges ()

    void        gts_triangle_vertices_edges     (GtsTriangle *t,
                                                 GtsEdge *e,
                                                 GtsVertex **v1,
                                                 GtsVertex **v2,
                                                 GtsVertex **v3,
                                                 GtsEdge **e1,
                                                 GtsEdge **e2,
                                                 GtsEdge **e3);

Given `t` and `e`, returns `v1`, `v2`, `v3`, `e1`, `e2` and `e3`. `e1` has `v1` and `v2` as vertices, `e2` has `v2` and `v3` as vertices and `e3` has `v3` and `v1` as vertices. `v1`, `v2` and `v3` respects the orientation of `t`. If `e` is not NULL, `e1` and `e` are identical.

`t` : | a GtsTriangle.
`e` : | a GtsEdge belonging to the edges of `t` or `NULL`.
`v1` : | a GtsVertex used by `t`.
`v2` : | a GtsVertex used by `t`.
`v3` : | a GtsVertex used by `t`.
`e1` : | a GtsEdge used by `t`.
`e2` : | a GtsEdge used by `t`.
`e3` : | a GtsEdge used by `t`.

### gts_triangle_vertex_opposite ()

    GtsVertex*  gts_triangle_vertex_opposite    (GtsTriangle *t,
                                                 GtsEdge *e);

This function fails if `e` is not an edge of `t`.

`t` : | a GtsTriangle.
`e` : | a GtsEdge used by `t`.
Returns : | a GtsVertex, vertex of `t` which does not belong to `e`.

### gts_triangle_edge_opposite ()

    GtsEdge*    gts_triangle_edge_opposite      (GtsTriangle *t,
                                                 GtsVertex *v);

`t` : | a GtsTriangle.
`v` : | a GtsVertex of `t`.
Returns : | the edge of `t` opposite `v` or `NULL` if `v` is not a vertice of `t`.

### gts_triangle_vertices ()

    void        gts_triangle_vertices           (GtsTriangle *t,
                                                 GtsVertex **v1,
                                                 GtsVertex **v2,
                                                 GtsVertex **v3);

Fills `v1`, `v2` and `v3` with the oriented set of vertices, summits of `t`.

`t` : | a GtsTriangle.
`v1` : | a pointer on a GtsVertex.
`v2` : | a pointer on a GtsVertex.
`v3` : | a pointer on a GtsVertex.

### gts_triangle_vertex()

    #define     gts_triangle_vertex(t)

Evaluates to the GtsVertex of `t` not used by `t`->e1.

`t` : | a GtsTriangle.

### gts_triangle_is_ok ()

    gboolean    gts_triangle_is_ok              (GtsTriangle *t);

`t` : | a GtsTriangle.
Returns : | `TRUE` if `t` is a non-degenerate, non-duplicate triangle, `FALSE` otherwise.

### gts_triangle_use_edges ()

    GtsTriangle* gts_triangle_use_edges         (GtsEdge *e1,
                                                 GtsEdge *e2,
                                                 GtsEdge *e3);

`e1` : | a GtsEdge.
`e2` : | a GtsEdge.
`e3` : | a GtsEdge.
Returns : | a GtsTriangle having `e1`, `e2` and `e3` as edges or `NULL` if `e1`, `e2` and `e3` are not part of any triangle.

### gts_triangle_circumcircle_center ()

    GtsPoint*   gts_triangle_circumcircle_center
                                                (GtsTriangle *t,
                                                 GtsPointClass *point_class);

`t` : | a GtsTriangle.
`point_class` : | a GtsPointClass.
Returns : | a new GtsPoint, center of the circumscribing circle of `t` or `NULL` if the circumscribing circle is not defined.

### gts_triangle_is_stabbed ()

    GtsObject*  gts_triangle_is_stabbed         (GtsTriangle *t,
                                                 GtsPoint *p,
                                                 gdouble *orientation);

`t` : | a GtsTriangle.
`p` : | a GtsPoint.
`orientation` : | a pointer or `NULL`.
Returns : | one of the vertices of `t`, one of the edges of `t` or `t` if any of these are stabbed by the ray starting at `p` (included) and ending at (`p`->x, `p`->y, +infty), `NULL` otherwise. If the ray is contained in the plane of the triangle `NULL` is also returned. If `orientation` is not `NULL`, it is set to the value of the orientation of `p` relative to `t` (as given by gts_point_orientation_3d()).

### gts_triangles_are_folded ()

    gboolean    gts_triangles_are_folded        (GSList *triangles,
                                                 GtsVertex *A,
                                                 GtsVertex *B,
                                                 gdouble max);

Given a list of triangles sharing `A` and `B` as vertices, checks if any two triangles in the list make an angle larger than a given value defined by `max`.

`triangles` : | a list of GtsTriangle.
`A` : | a GtsVertex.
`B` : | another GtsVertex.
`max` : | the maximum value of the square of the cosine of the angle between two triangles.
Returns : | `TRUE` if any pair of triangles in `triangles` makes an angle larger than the maximum value, `FALSE` otherwise.

### gts_triangles_from_edges ()

    GSList*     gts_triangles_from_edges        (GSList *edges);

Builds a list of unique triangles which have one of their edges in `edges`.

`edges` : | a list of GtsEdge.
Returns : | the list of triangles.

<<< Previous Page | Home | Up | Next Page >>>
Edges | Faces