## 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);

    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]);
    void        scalarFieldAdd_option           (ScalarField *field,
                                                 Option *option);

    GList*      scalarFieldGet_allLoadMethods   ();
    GList*      scalarFieldGet_allOptions       (ScalarField *field);
    void        scalarFieldGet_box              (ScalarField *field,
                                                 float 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);

    void        scalarFieldSet_box              (ScalarField *field,
                                                 float 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);

    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.

### 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]);

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.

`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.

### 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,
                                                 float 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);

Knowing the point coordinates, it interpolate a value from the scalar field.

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

### scalarFieldSet_box ()

    void        scalarFieldSet_box              (ScalarField *field,
                                                 float 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);

Set the data of the given `field`. The array `data` should be stored in z direction first, followed by y and x. 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.

### scalarFieldInit ()

    void        scalarFieldInit                 ();

Initialisation method, should not be used.