## scalarFields

scalarFields — Gives capabilities to load a scalar field.

## Synopsis

    #define             SCALAR_FIELD_DEFINED_IN_STRUCT_FILE
    struct              ScalarField_struct;
    typedef             ScalarField;
    gboolean            (*ScalarFieldLoadMethod)            (const gchar *filename,
                                                             GList **fieldList,
                                                             GError **error,
                                                             OptionTable *table);
    enum                ScalarField_meshflag;

    ScalarField*        scalarFieldNew                      (const gchar *filename);
    void                scalarFieldFree                     (ScalarField *field);
    void                scalarFieldAdd_loadMethod           (const gchar *name,
                                                             ScalarFieldLoadMethod method,
                                                             FileFormat *format,
                                                             int priority);
    gboolean            scalarFieldLoad_fromFile            (const gchar *filename,
                                                             GList **fieldList,
                                                             GError **error,
                                                             OptionTable *table);
    void                scalarFieldDraw_map                 (ScalarField *field,
                                                             Plane *plane,
                                                             Shade *shade,
                                                             OpenGLView *view,
                                                             float precision,
                                                             float drawnMinMax[2],
                                                             matrix_scaleflag scale,
                                                             guint nIsoLines,
                                                             float *rgb,
                                                             float *inputMinMax);
    void                scalarFieldAdd_option               (ScalarField *field,
                                                             Option *option);

    GList*              scalarFieldGet_allLoadMethods       ();
    GList*              scalarFieldGet_allOptions           (ScalarField *field);
    void                scalarFieldGet_box                  (ScalarField *field,
                                                             double box[6]);
    gchar*              scalarFieldGet_commentary           (ScalarField *field);
    double***           scalarFieldGet_data                 (ScalarField *field);
    gchar*              scalarFieldGet_filename             (ScalarField *field);
    void                scalarFieldGet_gridSize             (ScalarField *field,
                                                             int grid[3]);
    void                scalarFieldGet_minMax               (ScalarField *field,
                                                             double minmax[2]);
    gboolean            scalarFieldGet_value                (ScalarField *field,
                                                             float xyz[3],
                                                             double *value,
                                                             float extension[3]);
    gboolean            scalarFieldGet_periodic             (ScalarField *field);
    ScalarField_meshflag scalarFieldGet_meshtype            (ScalarField *field);
    double*             scalarFieldGet_meshx                (ScalarField *field);
    double*             scalarFieldGet_meshy                (ScalarField *field);
    double*             scalarFieldGet_meshz                (ScalarField *field);
    double              scalarFieldGet_secondaryMin         (ScalarField *field);

    void                scalarFieldSet_box                  (ScalarField *field,
                                                             double box[6]);
    void                scalarFieldSet_commentary           (ScalarField *field,
                                                             gchar *comment);
    void                scalarFieldSet_fitToBox             (VisuData *data,
                                                             ScalarField *field);
    void                scalarFieldSet_gridSize             (ScalarField *field,
                                                             int grid[3]);
    void                scalarFieldSet_data                 (ScalarField *field,
                                                             double *data,
                                                             gboolean xyzOrder);
    void                scalarFieldSet_periodic             (ScalarField *field,
                                                             gboolean periodic);
    void                scalarFieldSet_meshtype             (ScalarField *field,
                                                             ScalarField_meshflag meshtype);

    void                scalarFieldInit                     ();

## Description

A scalar field is represented by the given of datas on a regular grid meshing the bounding box. Scalar field can be read from several kind of files by adding load methods using `scalarFieldAdd_loadMethod()`. The basic implementation gives access to ASCII encoded files following a simple format.

In coordination with Plane and Shade, scalar field can be represented as coloured map calling `scalarFieldDraw_map()`. The current implementation of interpolation is very limited since basic linear approximation is used.

If a structure file also contains a scalar field, when loaded, it should add a VisuData property called SCALAR_FIELD_DEFINED_IN_STRUCT_FILE using `visuDataAdd_property()`. Then V_Sim will be able to handle the structure file as a density file also.

## Details

### SCALAR_FIELD_DEFINED_IN_STRUCT_FILE

    #define SCALAR_FIELD_DEFINED_IN_STRUCT_FILE "fileFormat_hasPotentialOrDensity"

Flag used to registered a gboolean property in a VisuData object. If this flag is TRUE, the file used to read the structure can be used to read a density or a potential.

### struct ScalarField_struct

    struct ScalarField_struct;

The structure used to store a scalar field.

### ScalarField

    typedef struct ScalarField_struct ScalarField;

Short name to address ScalarField_struct objects.

### ScalarFieldLoadMethod ()

    gboolean            (*ScalarFieldLoadMethod)            (const gchar *filename,
                                                             GList **fieldList,
                                                             GError **error,
                                                             OptionTable *table);

Read the given file try to load it as a scalar field file. If succeed (i.e. with none fatal errors) the method should return TRUE, but if not `fieldList` must be unchanged and the method should return TRUE. If an error occurs, it is stored into `error`. When entering the routine, *`error` must be NULL. If `table` is given, it means that the caller routine gives some options to the loader routine. These options are a set of names and values.

If the file contains several fields, they must be loaded and added to `fieldList`.

`filename` : | the filename (path) the field should be loaded from ;
`fieldList` : | a GList to store read field(s) ;
`error` : | a location on a error pointer ;
`table` : | a set of different options (can be NULL).
Returns : | TRUE if the read file is in a valid format (even with minor errors), FALSE otherwise.

### enum ScalarField_meshflag

    typedef enum
      {
        uniform,
        nonuniform
      } ScalarField_meshflag;

flag (comment) standing at the begining of a Scalar field file, that gives informations concerning the mesh.

`uniform` | the mesh has constant divisions along x, y and z axis ;
`nonuniform` | the mesh has non linear divisions along x, y or z axis.

### scalarFieldNew ()

    ScalarField*        scalarFieldNew                      (const gchar *filename);

Create a new ScalarField object that is empty (all internal pointers are set to NULL and no memory is allocated except for the object itself. The `filename` argument is copied.

`filename` : | the path to the filename the field should be read from.
Returns : | a newly created ScalarField object. Use `scalarFieldFree()` to delete it.

### scalarFieldFree ()

    void                scalarFieldFree                     (ScalarField *field);

Free the memory used by the given object.

`field` : | a ScalarField object.

### scalarFieldAdd_loadMethod ()

    void                scalarFieldAdd_loadMethod           (const gchar *name,
                                                             ScalarFieldLoadMethod method,
                                                             FileFormat *format,
                                                             int priority);

This routine is used to add a new method to load scalar field. The priority uses the scale of the GLib (G_PRIORITY_DEFAULT is 0, G_PRIORITY_LOW 300 for instance).

`name` : | the name of the method ;
`method` : | a ScalarFieldLoadMethod function ;
`format` : | a FileFormat object ;
`priority` : | a priority value (the lower value, the higher priority).

### scalarFieldLoad_fromFile ()

    gboolean            scalarFieldLoad_fromFile            (const gchar *filename,
                                                             GList **fieldList,
                                                             GError **error,
                                                             OptionTable *table);

Read the given file and try to load it as a scalar field file. If succeed, all read fields are appended to the `fieldList` argument. If an error occurs, it is stored into `error`. When entering the routine, *`error` must be NULL. If `table` is given, it means that the caller routine gives some options to the loader routine. These options are a set of names and values.

If the file contains several fields, they must be loaded and added to `fieldList`.

`filename` : | the path to the file to be loaded ;
`fieldList` : | a GList to store read field(s) ;
`error` : | a location on a error pointer ;
`table` : | a set of different options (can be NULL).
Returns : | TRUE if everything goes with no error.

### scalarFieldDraw_map ()

    void                scalarFieldDraw_map                 (ScalarField *field,
                                                             Plane *plane,
                                                             Shade *shade,
                                                             OpenGLView *view,
                                                             float precision,
                                                             float drawnMinMax[2],
                                                             matrix_scaleflag scale,
                                                             guint nIsoLines,
                                                             float *rgb,
                                                             float *inputMinMax);

This method directly call OpenGL primitive to represent a scalar filed (`field`) on a plane (`plane`) using a color scheme (`shade`). The `view` is used to find the resolution of the grid as `precision` value influences it also. If `rgb` is NULL, then the colour inverse is used instead. If `inputMinMax` is given, the two values are used as the boundaries for the scale.

`field` : | a ScalarField object ;
`plane` : | a Plane object ;
`shade` : | a Shade object ;
`view` : | a OpenGLView object ;
`precision` : | percentage of precision (100. is normal) ;
`drawnMinMax` : | store the min and max drawn value ;
`scale` : | the transformation method ;
`nIsoLines` : | the number of isolines to draw.
`rgb` : | a color, can be NULL ;
`inputMinMax` : | two floats or NULL.

### scalarFieldAdd_option ()

    void                scalarFieldAdd_option               (ScalarField *field,
                                                             Option *option);

This method adds an option to the list of Option associated to the data. The given `option` will not be duplicated and should not be used elsewhere because it will be freed when the `field` will be freed.

`field` : | a ScalarField object ;
`option` : | a newly allocated option.

### scalarFieldGet_allLoadMethods ()

    GList*              scalarFieldGet_allLoadMethods       ();

This routine gives access to all the registered load method for scamlar fields.

Returns : | a list of all methods. This list is read-only and own by V_Sim.

### scalarFieldGet_allOptions ()

    GList*              scalarFieldGet_allOptions           (ScalarField *field);

Some Option can be stored in association to the values of the scalar field. These options are usually values associated to the read data, such as a spin direction when dealing with density of spin...

`field` : | a ScalarField object.
Returns : | a newly created GList that should be freed after use with `g_list_free()`. But data of the list are owned by V_Sim and should not be modified or freed.

### scalarFieldGet_box ()

    void                scalarFieldGet_box                  (ScalarField *field,
                                                             double box[6]);

This method is used to get the definition of the bounding box.

`field` : | a ScalarField object ;
`box` : | 6 floating point locations.

### scalarFieldGet_commentary ()

    gchar*              scalarFieldGet_commentary           (ScalarField *field);

If the file format support a commentary, this is a good method to get it.

`field` : | a ScalarField object.
Returns : | a pointer on the commentary (it should not be freed), can be NULL.

### scalarFieldGet_data ()

    double***           scalarFieldGet_data                 (ScalarField *field);

The data are stored as a 3 indexes array in x, y annd z increasing.

`field` : | a ScalarField object.
Returns : | a pointer on the allocated data array (it should not be freed).

### scalarFieldGet_filename ()

    gchar*              scalarFieldGet_filename             (ScalarField *field);

The data are read from a file.

`field` : | a ScalarField object.
Returns : | a pointer on the filename (it should not be freed).

### scalarFieldGet_gridSize ()

    void                scalarFieldGet_gridSize             (ScalarField *field,
                                                             int grid[3]);

This method is used to get the division in x, y, and z directions.

`field` : | a ScalarField object ;
`grid` : | 3 integer locations.

### scalarFieldGet_minMax ()

    void                scalarFieldGet_minMax               (ScalarField *field,
                                                             double minmax[2]);

Get the minimum and the maximum values of the given `field`.

`field` : | a ScalarField object ;
`minmax` : | two double values.

### scalarFieldGet_value ()

    gboolean            scalarFieldGet_value                (ScalarField *field,
                                                             float xyz[3],
                                                             double *value,
                                                             float extension[3]);

Knowing the point coordinates, it interpolate a value from the scalar field. If the scalar field is periodic (see `scalarFieldSet_periodic()`), then it allow the coordinates to extend inside the given `extension`.

`field` : | a ScalarField object ;
`xyz` : | a point coordinate (in real space) ;
`value` : | a location to store the value ;
`extension` : | a possible extension in box coordinates.
Returns : | TRUE if the value can be interpolate, FALSE otherwise, for instance, when the point `xyz` is out of bounds.

### scalarFieldGet_periodic ()

    gboolean            scalarFieldGet_periodic             (ScalarField *field);

Get the periodicity status of the scalar field.

`field` : | a ScalarField object.
Returns : | TRUE if the scalar field is periodic.

### scalarFieldGet_meshtype ()

    ScalarField_meshflag scalarFieldGet_meshtype            (ScalarField *field);

The vertex may be distributed linearly along the different directions or customily distributed.

`field` : | a ScalarField object ; to be added
Returns : | a ScalarField_meshflag (uniform or nonuniform).

### scalarFieldGet_meshx ()

    double*             scalarFieldGet_meshx                (ScalarField *field);

The mesh along x is stored as an array in x increasing.

`field` : | a ScalarField object.
Returns : | a pointer on the allocated meshx array (it should not be freed).

### scalarFieldGet_meshy ()

    double*             scalarFieldGet_meshy                (ScalarField *field);

The mesh along y is stored as an array in y increasing.

`field` : | a ScalarField object.
Returns : | a pointer on the allocated meshy array (it should not be freed).

### scalarFieldGet_meshz ()

    double*             scalarFieldGet_meshz                (ScalarField *field);

The mesh along z is stored as an array in z increasing.

`field` : | a ScalarField object.
Returns : | a pointer on the allocated meshz array (it should not be freed).

### scalarFieldGet_secondaryMin ()

    double              scalarFieldGet_secondaryMin         (ScalarField *field);

Get the second minimum value of the given `field`.

`field` : | a ScalarField object.
Returns : | the second minimum.

### scalarFieldSet_box ()

    void                scalarFieldSet_box                  (ScalarField *field,
                                                             double box[6]);

This method is used to set the definition of the bounding box.

`field` : | a ScalarField object ;
`box` : | 6 floating point values.

### scalarFieldSet_commentary ()

    void                scalarFieldSet_commentary           (ScalarField *field,
                                                             gchar *comment);

A commentary can be associated to a ScalarField, use this method to set it. The value of `comment` is NOT copied.

`field` : | a ScalarField object ;
`comment` : | an UTF-8 string to store as a commentary.

### scalarFieldSet_fitToBox ()

    void                scalarFieldSet_fitToBox             (VisuData *data,
                                                             ScalarField *field);

Change the box of the scalar field to be the same that the one of the given `data` object. This may influence the surfaces that may be created from the field later, for instance.

`data` : | a VisuData object ;
`field` : | a ScalarField object.

### scalarFieldSet_gridSize ()

    void                scalarFieldSet_gridSize             (ScalarField *field,
                                                             int grid[3]);

This method is used to set the division in x, y, and z directions. If the size of internal array for data is changed, it is reallocated and previous data are erased. Use `scalarFieldGet_data()` to get a pointer on this data array.

`field` : | a ScalarField object ;
`grid` : | 3 integers.

### scalarFieldSet_data ()

    void                scalarFieldSet_data                 (ScalarField *field,
                                                             double *data,
                                                             gboolean xyzOrder);

Set the data of the given `field`. The array `data` should be stored in z direction first, followed by y and x if `xyzOrder` is FALSE, or in the other order when TRUE. The number of elements in the x, y and z directions are read from field->nElements. Then use `scalarFieldSet_gridSize()` before using this method.

`field` : | a ScalarField object ;
`data` : | array containing data to be copied ;
`xyzOrder` : | a boolean.

### scalarFieldSet_periodic ()

    void                scalarFieldSet_periodic             (ScalarField *field,
                                                             gboolean periodic);

When the scalar field is periodic, the values on the border x = 1, y = 1 or z = 1 can be obtained reading those of border x = 0, y = 0 or z = 0. So if there are n values in one direction, the nth is at position 1 - 1/n in box coordinates in that direction. On the contrary, for non-periodic scalar field, the nth value is at coordinate 1 in box system and can be different from value 0.

`field` : | a ScalarField object ;
`periodic` : | a boolean.

### scalarFieldSet_meshtype ()

    void                scalarFieldSet_meshtype             (ScalarField *field,
                                                             ScalarField_meshflag meshtype);

Change the distribution of the vertex of the scalarfield between regular or custom.

`field` : | a ScalarField object ;
`meshtype` : | a ScalarField_meshflag object.

### scalarFieldInit ()

    void                scalarFieldInit                     ();

Initialisation method, should not be used.