## map map — Describe how to handle and draw coloured map on a plane from a density field. |

## Synopsis

    enum                VisuMapExportFormat;
                        VisuMap;
    VisuMap*            visu_map_new                        ();
    VisuMap*            visu_map_newFromPlane               (Plane *plane);
    void                visu_map_free                       (VisuMap *map);
    gboolean            visu_map_setField                   (VisuMap *map,
                                                             ScalarField *field,
                                                             ToolMatrixScalingFlag scale,
                                                             float *inputMinMax,
                                                             float ext[3]);
    gboolean            visu_map_setLevel                   (VisuMap *map,
                                                             float gross,
                                                             float boxSpan);
    gboolean            visu_map_setLines                   (VisuMap *map,
                                                             guint nIsoLines,
                                                             float minmax[2]);
    float*              visu_map_getScaledMinMax            (VisuMap *map);
    float*              visu_map_getFieldMinMax             (VisuMap *map);
    int                 visu_map_getGlListId                (VisuMap *map);
    void                visu_map_compute                    (VisuMap *map);
    void                visu_map_draw                       (VisuMap *map,
                                                             float prec,
                                                             Shade *shade,
                                                             float *rgb,
                                                             gboolean alpha,
                                                             gboolean direct);
    gboolean            visu_map_export                     (VisuMap *map,
                                                             Shade *shade,
                                                             float *rgb,
                                                             float precision,
                                                             gchar *filename,
                                                             VisuMapExportFormat format,
                                                             GError **error);

## Description

A map is a coloured representation of a scalar field on a plane. To define a new map, use `visu_map_newFromPlane()` and use `visu_map_setField()` to associate a scalarfield to it.

The representation of the map is done by an adaptive mesh of triangles. One can adjust the size of the smaller resolution by using `visu_map_setLevel()`. Finally the level of adaptiveness is chosen at rendering time by choosing a more or less crude precision argument to `visu_map_draw()`.

In adition to the colour representation, isolines can be drawn at given iso-values, see `visu_map_setLines()`.

An additionnal capability allows to export VisuMap into SVG or PDF vector files.

## Details

### enum VisuMapExportFormat

    typedef enum
      {
        VISU_MAP_EXPORT_SVG,
        VISU_MAP_EXPORT_PDF
      } VisuMapExportFormat;

Possible export for the map, see `visu_map_export()`.

`VISU_MAP_EXPORT_SVG` | SVG export ;
`VISU_MAP_EXPORT_PDF` | PDF export.

Since 3.6

### VisuMap

    typedef struct _VisuMap VisuMap;

All fields are private.

Since 3.6

### visu_map_new ()

    VisuMap*            visu_map_new                        ();

Creates a new VisuMap object.

Returns : | a newly created VisuMap object.

Since 3.6

### visu_map_newFromPlane ()

    VisuMap*            visu_map_newFromPlane               (Plane *plane);

Creates a new VisuMap object, projected on `plane`.

`plane` : | a Plane object.
Returns : | a newly created VisuMap object.

Since 3.6

### visu_map_free ()

    void                visu_map_free                       (VisuMap *map);

Deallocate all memory related to `map`.

`map` : | a VisuMap object.

Since 3.6

### visu_map_setField ()

    gboolean            visu_map_setField                   (VisuMap *map,
                                                             ScalarField *field,
                                                             ToolMatrixScalingFlag scale,
                                                             float *inputMinMax,
                                                             float ext[3]);

It associates the values of `field` to `map`. The calculation is not directly done, and a call to `visu_map_compute()` is necessary. If `inputMinMax` is provided, these values are used to scale the values of `field` to [0;1], otherwise the minMax values of the field itself are used. The scaling algorithm is defined by `scale`.

`map` : | a VisuMap object.
`field` : | a ScalarField object.
`scale` : | a flag.
`inputMinMax` : | two floats or NULL.
`ext` : | the box extension.
Returns : | a newly created VisuMap object.

Since 3.6

### visu_map_setLevel ()

    gboolean            visu_map_setLevel                   (VisuMap *map,
                                                             float gross,
                                                             float boxSpan);

Setup the level of recursivity in triangle calculation, depending on the current zoom level.

`map` : | a VisuMap object.
`gross` : | current zoom level.
`boxSpan` : | the size of the rendering box.
Returns : | TRUE if the level is actually changed.

Since 3.6

### visu_map_setLines ()

    gboolean            visu_map_setLines                   (VisuMap *map,
                                                             guint nIsoLines,
                                                             float minmax[2]);

Calculate `nIsoLines` equally distributed in `minmax`.

`map` : | a VisuMap object.
`nIsoLines` : | number of required isolines.
`minmax` : | span for isoline values.
Returns : | TRUE if lines are successfully calculated.

Since 3.6

### visu_map_getScaledMinMax ()

    float*              visu_map_getScaledMinMax            (VisuMap *map);

After `map` has been computed by `visu_map_compute()`, one can access the scaled min and max values represented in the map. For field values, see `visu_map_getFieldMinMax()`.

`map` : | a VisuMap object.
Returns : | two floats being the min and the max in [0;1].

Since 3.6

### visu_map_getFieldMinMax ()

    float*              visu_map_getFieldMinMax             (VisuMap *map);

After `map` has been computed by `visu_map_compute()`, one can access the min and max values of the field as represented in the map. For scaled values, see `visu_map_getScaledMinMax()`.

`map` : | a VisuMap object.
Returns : | two floats being the min and the max.

Since 3.6

### visu_map_getGlListId ()

    int                 visu_map_getGlListId                (VisuMap *map);

When `visu_map_draw()` is called with direct being FALSE, one can access the OpenGL list used to draw the map with this routine.

`map` : | a VisuMap object.
Returns : | the OpenGL list id for this map.

Since 3.6

### visu_map_compute ()

    void                visu_map_compute                    (VisuMap *map);

After a Plane and a ScalarField has been defined (see `visu_map_newFromPlane()` and `visu_map_setField()`), the map is computed by refining a triangle approximation up to level defined by `visu_map_setLevel()`. The evaluation is lazy and calculation is indeed done, only if required level is lower than actual level. Calculation is done only for missing levels anyway.

`map` : | a VisuMap object.

Since 3.6

### visu_map_draw ()

    void                visu_map_draw                       (VisuMap *map,
                                                             float prec,
                                                             Shade *shade,
                                                             float *rgb,
                                                             gboolean alpha,
                                                             gboolean direct);

It draws the `map` with the given `shade`. `prec` give the level of refinement used to draw the map, 100 means normal and 200 means twice smaller level. If `rgb` is present, this colour is used for possible isolines. If `alpha` is TRUE, an alpha channel is added as a linear variation of the value of each vertex. If `direct` is FALSE, the drawing is compiled in a list available by calling `visu_map_getGlListId()`.

`map` : | a VisuMap object.
`prec` : | a pourcentage value.
`shade` : | a Shade object.
`rgb` : | a colour or NULL.
`alpha` : | a boolean.
`direct` : | a boolean.

Since 3.6

### visu_map_export ()

    gboolean            visu_map_export                     (VisuMap *map,
                                                             Shade *shade,
                                                             float *rgb,
                                                             float precision,
                                                             gchar *filename,
                                                             VisuMapExportFormat format,
                                                             GError **error);

Export the given map to the `format`, using the `shade` color. If `rgb` is provided and `map` has some isolines, they will be drawn with this colour, otherwise an inverse colour is used.

`map` : | a VisuMap object.
`shade` : | a Shade object.
`rgb` : | a colour (can be NULL).
`precision` : | a pourcentage for rendering quality.
`filename` : | the location to export to.
`format` : | the kind of format.
`error` : | a location to store an error.
Returns : | TRUE if no error.

Since 3.6