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

# Isosurfaces from 3D functions

## Name

Isosurfaces from 3D functions -- computing triangulated isosurfaces of a given function f(x,y,z).

## Synopsis

    #include <gts.h>

    struct      GtsCartesianGrid;
    struct      GtsGridPlane;

    GtsGridPlane* gts_grid_plane_new            (guint nx,
                                                 guint ny);
    void        gts_grid_plane_destroy          (GtsGridPlane *g);

    struct      GtsIsoSlice;

    GtsIsoSlice* gts_iso_slice_new              (guint nx,
                                                 guint ny);
    void        gts_iso_slice_fill              (GtsIsoSlice *slice,
                                                 GtsGridPlane *plane1,
                                                 GtsGridPlane *plane2,
                                                 gdouble **f1,
                                                 gdouble **f2,
                                                 gdouble iso,
                                                 GtsVertexClass *klass);
    void        gts_iso_slice_fill_cartesian    (GtsIsoSlice *slice,
                                                 GtsCartesianGrid g,
                                                 gdouble **f1,
                                                 gdouble **f2,
                                                 gdouble iso,
                                                 GtsVertexClass *klass);
    void        gts_iso_slice_destroy           (GtsIsoSlice *slice);
    void        gts_isosurface_slice            (GtsIsoSlice *slice1,
                                                 GtsIsoSlice *slice2,
                                                 GtsSurface *surface);
    void        (*GtsIsoCartesianFunc)          (gdouble **a,
                                                 GtsCartesianGrid g,
                                                 guint i,
                                                 gpointer data);
    void        gts_isosurface_cartesian        (GtsSurface *surface,
                                                 GtsCartesianGrid g,
                                                 GtsIsoCartesianFunc f,
                                                 gpointer data,
                                                 gdouble iso);
    void        gts_isosurface_tetra            (GtsSurface *surface,
                                                 GtsCartesianGrid g,
                                                 GtsIsoCartesianFunc f,
                                                 gpointer data,
                                                 gdouble iso);
    void        gts_isosurface_tetra_bounded    (GtsSurface *surface,
                                                 GtsCartesianGrid g,
                                                 GtsIsoCartesianFunc f,
                                                 gpointer data,
                                                 gdouble iso);

## Description

Using the gts_isosurface_cartesian() function, it is possible to build a triangulated isosurface of a given user-defined function. As its name indicates this function assumes that the values of the user-defined function are defined for points located on a regular cartesian grid described by the GtsCartesianGrid parameter. The triangles describing the isosurface are computed for each pair of successive planes z and z+dz in a pipelined manner. Consequently only two planes need to be stored in memory at any time. This allows to construct isosurfaces for datasets too large to fit in main memory.

## Details

### struct GtsCartesianGrid

    struct GtsCartesianGrid {
      guint nx, ny, nz;
      gdouble x, dx, y, dy, z, dz;
    };

A regular cartesian grid is defined by the number of points in each direction, the spatial increment in each direction and the coordinates of the first point.

guint `nx` | Number of points in direction x.
guint `ny` | Number of points in direction y.
guint `nz` | Number of points in direction z.
gdouble `x` | x coordinate of the first point.
gdouble `dx` | Increment in direction x.
gdouble `y` | y coordinate of the first point.
gdouble `dy` | Increment in direction y.
gdouble `z` | z coordinate of the first point.
gdouble `dz` | Increment in direction z.

### struct GtsGridPlane

    struct GtsGridPlane {
      GtsPoint ** p;
      guint nx, ny;
    };

### gts_grid_plane_new ()

    GtsGridPlane* gts_grid_plane_new            (guint nx,
                                                 guint ny);

`nx` : |
`ny` : |
Returns : |

### gts_grid_plane_destroy ()

    void        gts_grid_plane_destroy          (GtsGridPlane *g);

`g` : |

### struct GtsIsoSlice

    struct GtsIsoSlice;

A GtsIsoSlice is an opaque data structure containing the coordinates of the points located on the isosurface for a given slice of the user-defined function.

### gts_iso_slice_new ()

    GtsIsoSlice* gts_iso_slice_new              (guint nx,
                                                 guint ny);

`nx` : | number of vertices in the x direction.
`ny` : | number of vertices in the y direction.
Returns : | a new GtsIsoSlice.

### gts_iso_slice_fill ()

    void        gts_iso_slice_fill              (GtsIsoSlice *slice,
                                                 GtsGridPlane *plane1,
                                                 GtsGridPlane *plane2,
                                                 gdouble **f1,
                                                 gdouble **f2,
                                                 gdouble iso,
                                                 GtsVertexClass *klass);

Fill `slice` with the coordinates of the vertices defined by f1 (x,y,z) = `iso` and f2 (x, y, z) = `iso`.

`slice` : | a GtsIsoSlice.
`plane1` : | a GtsGridPlane.
`plane2` : | another GtsGridPlane.
`f1` : | values of the function corresponding to `plane1`.
`f2` : | values of the function corresponding to `plane2`.
`iso` : | isosurface value.
`klass` : | a GtsVertexClass or one of its descendant to be used for the new vertices.

### gts_iso_slice_fill_cartesian ()

    void        gts_iso_slice_fill_cartesian    (GtsIsoSlice *slice,
                                                 GtsCartesianGrid g,
                                                 gdouble **f1,
                                                 gdouble **f2,
                                                 gdouble iso,
                                                 GtsVertexClass *klass);

Fill `slice` with the coordinates of the vertices defined by f1 (x,y,z) = `iso` and f2 (x, y, z) = `iso`.

`slice` : | a GtsIsoSlice.
`g` : | a GtsCartesianGrid.
`f1` : | values of the function for plane z = `g`.z.
`f2` : | values of the function for plane z = `g`.z + `g`.dz.
`iso` : | isosurface value.
`klass` : | a GtsVertexClass.

### gts_iso_slice_destroy ()

    void        gts_iso_slice_destroy           (GtsIsoSlice *slice);

Free all memory allocated for `slice`.

`slice` : | a GtsIsoSlice.

### gts_isosurface_slice ()

    void        gts_isosurface_slice            (GtsIsoSlice *slice1,
                                                 GtsIsoSlice *slice2,
                                                 GtsSurface *surface);

Given two successive slices `slice1` and `slice2` link their vertices with segments and triangles which are added to `surface`.

`slice1` : | a GtsIsoSlice.
`slice2` : | another GtsIsoSlice.
`surface` : | a GtsSurface.

### GtsIsoCartesianFunc ()

    void        (*GtsIsoCartesianFunc)          (gdouble **a,
                                                 GtsCartesianGrid g,
                                                 guint i,
                                                 gpointer data);

This user-defined function is passed to the gts_isosurface_cartesian() function. Given a particular GtsCartesianGrid `g` it must fill the array `a` with the values of the function for the plane z=`g`.z (or for the corresponding index `i`). This function is always called in order by gts_isosurface_cartesian(), i.e. `i` varies from 0 to `g`.nz - 1 with an increment of one (and similarly `g`.z is incremented every time by `g`.dz).

`a` : | the 2D array to be filled.
`g` : | a GtsCartesianGrid.
`i` : | the z direction index of the plane to be filled.
`data` : | user data.

### gts_isosurface_cartesian ()

    void        gts_isosurface_cartesian        (GtsSurface *surface,
                                                 GtsCartesianGrid g,
                                                 GtsIsoCartesianFunc f,
                                                 gpointer data,
                                                 gdouble iso);

Adds to `surface` new faces defining the isosurface f(x,y,z) = `iso`. By convention, the normals to the surface are pointing toward the positive values of f(x,y,z) - `iso`.

The user function `f` is called successively for each value of the z coordinate defined by `g`. It must fill the corresponding (x,y) plane with the values of the function for which the isosurface is to be computed.

`surface` : | a GtsSurface.
`g` : | a GtsCartesianGrid.
`f` : | a GtsIsoCartesianFunc.
`data` : | user data to be passed to `f`.
`iso` : | isosurface value.

### gts_isosurface_tetra ()

    void        gts_isosurface_tetra            (GtsSurface *surface,
                                                 GtsCartesianGrid g,
                                                 GtsIsoCartesianFunc f,
                                                 gpointer data,
                                                 gdouble iso);

Adds to `surface` new faces defining the isosurface f(x,y,z) = `iso`. By convention, the normals to the surface are pointing toward the positive values of f(x,y,z) - `iso`.

The user function `f` is called successively for each value of the z coordinate defined by `g`. It must fill the corresponding (x,y) plane with the values of the function for which the isosurface is to be computed.

`surface` : | a GtsSurface.
`g` : | a GtsCartesianGrid.
`f` : | a GtsIsoCartesianFunc.
`data` : | user data to be passed to `f`.
`iso` : | isosurface value.

### gts_isosurface_tetra_bounded ()

    void        gts_isosurface_tetra_bounded    (GtsSurface *surface,
                                                 GtsCartesianGrid g,
                                                 GtsIsoCartesianFunc f,
                                                 gpointer data,
                                                 gdouble iso);

Adds to `surface` new faces defining the isosurface f(x,y,z) = `iso`. By convention, the normals to the surface are pointing toward the positive values of f(x,y,z) - `iso`. To ensure a closed object, a boundary of G_MINDOUBLE is added around the domain

The user function `f` is called successively for each value of the z coordinate defined by `g`. It must fill the corresponding (x,y) plane with the values of the function for which the isosurface is to be computed.

`surface` : | a GtsSurface.
`g` : | a GtsCartesianGrid.
`f` : | a GtsIsoCartesianFunc.
`data` : | user data to be passed to `f`.
`iso` : | isosurface value.

<<< Previous Page | Home | Up | Next Page >>>
Out-of-core simplification | Delaunay and constrained Delaunay triangulations