## geometry

geometry — different routines to do high level geometry studies on a box or a set of boxes.

## Synopsis

    typedef             VisuPathes;
    VisuPathes*         visu_pathes_new                     (float translation[3]);
    void                visu_pathes_free                    (VisuPathes *pathes);
    void                visu_pathes_empty                   (VisuPathes *pathes);
    gboolean            visu_pathes_addFromDiff             (VisuPathes *pathes,
                                                             VisuData *data);
    gboolean            visu_pathes_addNodeStep             (VisuPathes *pathes,
                                                             guint time,
                                                             guint nodeId,
                                                             float xyz[3],
                                                             float dxyz[3],
                                                             float energy);
    void                visu_pathes_pinPositions            (VisuPathes *pathes,
                                                             VisuData *data);
    void                visu_pathes_draw                    (VisuPathes *pathes);
    void                visu_pathes_constrainInBox          (VisuPathes *pathes,
                                                             VisuData *data);
    gboolean            visu_pathes_exportToXML             (const VisuPathes *pathes,
                                                             const gchar *filename,
                                                             GError **error);
    gboolean            visu_pathes_parseFromXML            (const gchar *filename,
                                                             VisuPathes *pathes,
                                                             GError **error);
    void                visu_pathes_setTranslation          (VisuPathes *pathes,
                                                             float cartCoord[3]);
    gboolean            visu_pathes_setShade                (VisuPathes *pathes,
                                                             Shade *shade);
    Shade*              visu_pathes_getShade                (VisuPathes *pathes);
    guint               visu_pathes_getLength               (VisuPathes *pathes);
    gboolean            visu_geodiff_new                    (VisuData *dataRef,
                                                             VisuData *data,
                                                             gboolean reorder);
    gboolean            visu_geodiff_setActive              (gboolean value);
    void                visu_geodiff_rebuildList            (VisuData *dataObj);
    gboolean            visu_geodiff_hasData                (VisuData *data);
    gchar*              visu_geodiff_export                 (VisuData *data);
    void                visu_geodiff_getPeriodicDistance    (float diff[3],
                                                             VisuData *data,
                                                             VisuNode *node1,
                                                             VisuNode *node2);
    void                geometryInit                        ();

## Description

The first possibility of the geometry section is to make a two by two difference node position difference between two VisuData objects. The VisuNode positions are compared (number to number and not closed equivalent to closed equivalent) and stored for visualisation. The visualisation is done through small arrows position on the currently visualised file.

## Details

### VisuPathes

    typedef struct VisuPathes_ VisuPathes;

An opaque structure to save a set of pathes.

Since 3.6

### visu_pathes_new ()

    VisuPathes*         visu_pathes_new                     (float translation[3]);

Create a new VisuPathes object.

`translation` : | the current box translation (cartesian).
Returns : | the newly create object VisuPathes, to be freed with `visu_pathes_free()`.

Since 3.6

### visu_pathes_free ()

    void                visu_pathes_free                    (VisuPathes *pathes);

Free a set of pathes.

`pathes` : | a VisuPathes object.

Since 3.6

### visu_pathes_empty ()

    void                visu_pathes_empty                   (VisuPathes *pathes);

Reinitialise internal values of a given `pathes`.

`pathes` : | a VisuPathes object.

Since 3.6

### visu_pathes_addFromDiff ()

    gboolean            visu_pathes_addFromDiff             (VisuPathes *pathes,
                                                             VisuData *data);

This routine read the geometry difference hold in `data` and add a new step in the set of pathes. If new pathes are created, one should call `visu_pathes_setTranslation()` to be sure that all pathes are moved inside the box.

`data` : | a VisuData object with a geometry difference (see `visu_geodiff_new()`).
`pathes` : | the set of pathes to extend.
Returns : | TRUE if new pathes have been added.

Since 3.6

### visu_pathes_addNodeStep ()

    gboolean            visu_pathes_addNodeStep             (VisuPathes *pathes,
                                                             guint time,
                                                             guint nodeId,
                                                             float xyz[3],
                                                             float dxyz[3],
                                                             float energy);

This routine expand the path for the given `nodeId` at position `xyz` of `dxyz`. The `energy` value will be used only if `visu_pathes_setShade()` is used with a non NULL Shade. In that case the `energy` value will be used to colourise the provided path.

`pathes` : | a set of pathes.
`time` : | the flag that give the number of expansion to update.
`nodeId` : | the node to expand the path of.
`xyz` : | the current position of the path.
`dxyz` : | the variation in the path.
`energy` : | the energy of the system.
Returns : | TRUE if a new path is started.

Since 3.6

### visu_pathes_pinPositions ()

    void                visu_pathes_pinPositions            (VisuPathes *pathes,
                                                             VisuData *data);

Use the current positions of `data` to extend `pathes`.

`pathes` : | a VisuPathes object.
`data` : | a VisuData object.

Since 3.6

### visu_pathes_draw ()

    void                visu_pathes_draw                    (VisuPathes *pathes);

OpenGL calls to create the pathes.

`pathes` : | a set of pathes.

Since 3.6

### visu_pathes_constrainInBox ()

    void                visu_pathes_constrainInBox          (VisuPathes *pathes,
                                                             VisuData *data);

Modify the corrdinates of the path nodes to contraint them in a box (when applying translations for instance).

`pathes` : | a VisuPathes object.
`data` : | a VisuData object.

Since 3.6

### visu_pathes_exportToXML ()

    gboolean            visu_pathes_exportToXML             (const VisuPathes *pathes,
                                                             const gchar *filename,
                                                             GError **error);

Write an XML file with the description of the given `pathes`.

`pathes` : | a VisuPathes object.
`filename` : | a location on disk.
`error` : | a pointer on an error.
Returns : | TRUE if no error.

Since 3.6

### visu_pathes_parseFromXML ()

    gboolean            visu_pathes_parseFromXML            (const gchar *filename,
                                                             VisuPathes *pathes,
                                                             GError **error);

Read an XML containing a description of `pathes`. `pathes` is newly created on success and should be freed with `visu_pathes_free()`.

`filename` : | a location on disk.
`pathes` : | a VisuPathes object.
`error` : | a pointer on an error.
Returns : | TRUE on success.

Since 3.6

### visu_pathes_setTranslation ()

    void                visu_pathes_setTranslation          (VisuPathes *pathes,
                                                             float cartCoord[3]);

Change the translation of the path, stored in cartesian coordinates.

`pathes` : | a VisuPathes object.
`cartCoord` : | three floats.

Since 3.6

### visu_pathes_setShade ()

    gboolean            visu_pathes_setShade                (VisuPathes *pathes,
                                                             Shade *shade);

Set the colourisation scheme for the path.

`pathes` : | a VisuPathes object.
`shade` : | a Shade object.
Returns : | TRUE is the scheme is changed.

Since 3.6

### visu_pathes_getShade ()

    Shade*              visu_pathes_getShade                (VisuPathes *pathes);

The pathes are drawn with a colourisation scheme.

`pathes` : | a VisuPathes object.
Returns : | the Shade used by the `pathes`.

Since 3.6

### visu_pathes_getLength ()

    guint               visu_pathes_getLength               (VisuPathes *pathes);

Get the number of steps stored in a VisuPathes.

`pathes` : | a VisuPathes object.
Returns : | the number of steps.

Since 3.6

### visu_geodiff_new ()

    gboolean            visu_geodiff_new                    (VisuData *dataRef,
                                                             VisuData *data,
                                                             gboolean reorder);

Compare the position of each VisuNode of `dataRef` and `data`, the result is store as a property of `data` and can be visualise using `visu_geodiff_setActive()`. If `reorder` is TRUE, the nodes in `data` will be modified to follow the ordering of `dataRef`.

`dataRef` : | a VisuData object ;
`data` : | another VisuData object.
`reorder` : | a boolean.
Returns : | TRUE if a difference is possible (same number of nodes).

Since 3.5

### visu_geodiff_setActive ()

    gboolean            visu_geodiff_setActive              (gboolean value);

Visualise or not a geometry difference that has been previously obtained using `visu_geodiff_new()`. The representation is done via arrows positioned on nodes.

`value` : | a boolean.
Returns : | TRUE if the status of the geometry difference changed.

Since 3.5

### visu_geodiff_rebuildList ()

    void                visu_geodiff_rebuildList            (VisuData *dataObj);

Create the OpenGL list holding the representation of a geometry difference.

`dataObj` : | a VisuData containing a geometry diff.

Since 3.5

### visu_geodiff_hasData ()

    gboolean            visu_geodiff_hasData                (VisuData *data);

A set coordinate differences can be associated to a VisuData using `visu_geodiff_new()`.

`data` : | a VisuData object.
Returns : | TRUE if the given `data` has a set of differences associated.

Since 3.6

### visu_geodiff_export ()

    gchar*              visu_geodiff_export                 (VisuData *data);

Create a string with differences of coordinates stored in `data` in cartesian coordinates.

`data` : | a VisuData object.
Returns : | a new string that should be freed after use.

Since 3.6

### visu_geodiff_getPeriodicDistance ()

    void                visu_geodiff_getPeriodicDistance    (float diff[3],
                                                             VisuData *data,
                                                             VisuNode *node1,
                                                             VisuNode *node2);

Compute the shortest distance between `node1` and `node2` of `data` taking into account the periodic boundary conditions.

`diff` : | a location to store the shift.
`data` : | a VisuData object.
`node1` : | a VisuNode object.
`node2` : | another VisuNode object.

Since 3.5

### geometryInit ()

    void                geometryInit                        ();