## dataFile

dataFile — Adds a possibility to colorize nodes depending on data read in an input file.

## Synopsis

    enum        DataFileInputScaleId;
    enum        DataFileColorModeId;
    int         initDataFileModule              ();
    void        dataFileReDraw                  (VisuData *data);
    int         dataFileSet_used                (VisuData *data,
                                                 int val);
    int         dataFileGet_used                (VisuData *data);
    int         dataFileSet_file                (VisuData *attachedVisuData,
                                                 char *filename,
                                                 GString *message,
                                                 int *errors);
    gchar*      dataFileGet_file                (VisuData *visuData);
    gboolean    dataFileGet_fileMinMaxFromColumn
                                                (VisuData *visuData,
                                                 float minMax[2],
                                                 int column);
    int         dataFileSet_scaleType           (VisuData *visuData,
                                                 DataFileInputScaleId scale);
    DataFileInputScaleId dataFileGet_scaleType  (VisuData *visuData);
    int         dataFileSet_min                 (VisuData *visuData,
                                                 float min);
    int         dataFileSet_max                 (VisuData *visuData,
                                                 float max);
    float       dataFileGet_min                 (VisuData *visuData);
    float       dataFileGet_max                 (VisuData *visuData);
    int         dataFileSet_vectA               (VisuData *visuData,
                                                 float val,
                                                 int pos);
    int         dataFileSet_vectB               (VisuData *visuData,
                                                 float val,
                                                 int pos);
    float*      dataFileGet_vectA               (VisuData *visuData);
    float*      dataFileGet_vectB               (VisuData *visuData);
    int         dataFileSet_colUsed             (VisuData *visuData,
                                                 int val,
                                                 int pos);
    int*        dataFileGet_colUsed             (VisuData *visuData);
    int         dataFileGet_nbColumns           (VisuData *visuData);
    int         dataFileSet_colorType           (VisuData *visuData,
                                                 DataFileColorModeId color);
    DataFileColorModeId dataFileGet_colorType   (VisuData *visuData);
    void        dataFileGet_valuesTransformedInRGB
                                                (VisuData *visuData,
                                                 float *valuesTransformed,
                                                 float *valuesFrom);
    int         dataFileSet_shade               (VisuData *visuData,
                                                 Shade *shade);
    gboolean    dataFileApply_hideOnMinValue    (VisuData *visuData,
                                                 int column,
                                                 float value);

## Description

With this module, it is possible to colorize nodes depending on data read in an input file. An input file can be associated to a VisuData object using `dataFileSet_file()`. Doing this, the rendering is changed and nodes are colorized following a scheme describe later. To turn off colorization without removing the data file (for temporary turn off for instance), use `dataFileSet_used()`.

The input file must have the same numbers of uncommented lines as there are nodes in the VisuData associated with. If less data is given, missing data are treaded as min values data. The input data file can has as much column as desired. The colorization is based on a linear color transformation. This transformation is applied on color channel in RGB mode or in HSV mode. Resulting color is given by : [resulting color vect] = [vectB] + [input data][vectA], where [input data] are input data scaled to [0;1]. It is possible to choose which column multiplies which color channel.

Using `dataFileApply_hideOnMinValue()`, it is possible to hide some nodes depending on given input data. If the `column` argument is -1, it unmask all nodes.

Using this module stores several Shade that can be used by other modules after being initialized using `dataFileBuild_presetShadeList()`.

## Details

### enum DataFileInputScaleId

    typedef enum
      {
        dataFile_normalize,
        dataFile_minMax
      } DataFileInputScaleId;

Control how input data are converted into [0;1], after conversion, values are clamped if needed.

`dataFile_normalize` | input data are converted into [0;1] using input min/max values.
`dataFile_minMax` | input data are converted into [0;1] using user defined min/max values.

### enum DataFileColorModeId

    typedef enum
      {
        dataFile_rgb,
        dataFile_hsv
      } DataFileColorModeId;

Control in which color space the color transformation is done.

`dataFile_rgb` | color transformation are applied in RGB mode.
`dataFile_hsv` | color transformation are applied in HSV mode.

### initDataFileModule ()

    int         initDataFileModule              ();

Called by V_Sim on startup, should not be called again.

Returns : | 1 if eveything goes right.

### dataFileReDraw ()

    void        dataFileReDraw                  (VisuData *data);

This methods is a short-cut to call `visuData_createAllNodes()` and then emit the 'OpenGLAskForReDraw' signal.

May become deprecated soon.

`data` : | a VisuData object that holds the data file informations.

### dataFileSet_used ()

    int         dataFileSet_used                (VisuData *data,
                                                 int val);

When TRUE, rendering is modified by applying a colorization method to normal nodes. The color used depend on input data. See `dataFileSet_file()` to choose them.

`data` : | a VisuData object to set the colorisation tool or not ;
`val` : | a boolean integer.
Returns : | TRUE if val is true and if a valid input file is already in memory.

### dataFileGet_used ()

    int         dataFileGet_used                (VisuData *data);

This method retrieve the used flag, see `dataFileSet_used()` to set it.

`data` : | a VisuData object to get if the colorisation tool is set or not ;
Returns : | 1 if the used flag is set.

### dataFileSet_file ()

    int         dataFileSet_file                (VisuData *attachedVisuData,
                                                 char *filename,
                                                 GString *message,
                                                 int *errors);

Call this method to parse a data file and associate its values to the given VisuData object.

`attachedVisuData` : | a VisuData object to attach the data file to ;
`filename` : | the path to find the data file on the disk ;
`message` : | an allocated GString to store some IO messages ;
`errors` : | an allocated integer to store if some errors occured.
Returns : | 0 if nothing is loaded, 1 some data have been loaded.

### dataFileGet_file ()

    gchar*      dataFileGet_file                (VisuData *visuData);

If the given `visuData` has an input data file already loaded, it returns its name.

`visuData` : | a VisuData object.
Returns : | the name of the input data file if set. This name is own by V_Sim and should not be freed.

### dataFileGet_fileMinMaxFromColumn ()

    gboolean    dataFileGet_fileMinMaxFromColumn
                                                (VisuData *visuData,
                                                 float minMax[2],
                                                 int column);

This method is used to retrieve the minimum and the maximum values of the column designed by the `column` argument. Column are numbered beginning at 0.

`visuData` : | the VisuData object which the colour data are associated to ;
`minMax` : | an allocated array of two floating point values ;
`column` : | an integer.
Returns : | FALSE if `column` < 0 or if `column` is greater than the number of read column or if no file has been set.

### dataFileSet_scaleType ()

    int         dataFileSet_scaleType           (VisuData *visuData,
                                                 DataFileInputScaleId scale);

This method is used to change the scale method used on input data. See DataFileInputScaleId for further informations. This method raises a error if no input file has already been associated to the give `visuData`.

`visuData` : | a VisuData object ;
`scale` : | an integer.
Returns : | 1 if `visuData_createAllNodes()` should be called.

### dataFileGet_scaleType ()

    DataFileInputScaleId dataFileGet_scaleType  (VisuData *visuData);

Retrieve the scaling method of input data associated to the given `visuData`.

`visuData` : | a VisuData object.
Returns : | the scaling method if `visuData` has an input data file associated or the default value if not.

### dataFileSet_min ()

    int         dataFileSet_min                 (VisuData *visuData,
                                                 float min);

When the scaling method is dataFile_minMax (see DataFileInputScaleId) min and max value for convert input data are user defined. Use this method to choose the minimum bound. This method raises a error if no input file has already been associated to the give `visuData`.

`visuData` : | a VisuData object ;
`min` : | a floating point value.
Returns : | 1 if `visuData_createAllNodes()` should be called.

### dataFileSet_max ()

    int         dataFileSet_max                 (VisuData *visuData,
                                                 float max);

When the scaling method is dataFile_minMax (see DataFileInputScaleId) min and max value for convert input data are user defined. Use this method to choose the maximum bound. This method raises a error if no input file has already been associated to the give `visuData`.

`visuData` : | a VisuData object ;
`max` : | a floating point value.
Returns : | 1 if `visuData_createAllNodes()` should be called.

### dataFileGet_min ()

    float       dataFileGet_min                 (VisuData *visuData);

Retrieve the minimum value used when scaling is user defined.

`visuData` : | a VisuData object.
Returns : | the minimum bound if `visuData` has an input data file associated or the default value if not.

### dataFileGet_max ()

    float       dataFileGet_max                 (VisuData *visuData);

Retrieve the maximum value used when scaling is user defined.

`visuData` : | a VisuData object.
Returns : | the maximum bound if `visuData` has an input data file associated or the default value if not.

### dataFileSet_vectA ()

    int         dataFileSet_vectA               (VisuData *visuData,
                                                 float val,
                                                 int pos);

Change the vector A used to adapt the colour to the value of the loaded data.

`visuData` : | a VisuData object ;
`val` : | the value to set ;
`pos` : | an integer in [0;2].
Returns : | 1 if `visuData_createAllNodes()` should be called.

### dataFileSet_vectB ()

    int         dataFileSet_vectB               (VisuData *visuData,
                                                 float val,
                                                 int pos);

Change the vector B used to adapt the colour to the value of the loaded data.

`visuData` : | a VisuData object ;
`val` : | the value to set ;
`pos` : | an integer in [0;2].
Returns : | 1 if `visuData_createAllNodes()` should be called.

### dataFileGet_vectA ()

    float*      dataFileGet_vectA               (VisuData *visuData);

This method is used to retrieve the vector A used to adapt the colour to the value of the loaded data.

`visuData` : | a VisuData object ;
Returns : | a three value array, own by V_Sim. It should not be freed.

### dataFileGet_vectB ()

    float*      dataFileGet_vectB               (VisuData *visuData);

This method is used to retrieve the vector B used to adapt the colour to the value of the loaded data.

`visuData` : | a VisuData object ;
Returns : | a three value array, own by V_Sim. It should not be freed.

### dataFileSet_colUsed ()

    int         dataFileSet_colUsed             (VisuData *visuData,
                                                 int val,
                                                 int pos);

Choose if the loaded value should change the given channel of the colour.

`visuData` : | a VisuData object ;
`val` : | 0 or 1 ;
`pos` : | an integer in [0;2].
Returns : | 1 if `visuData_createAllNodes()` should be called.

### dataFileGet_colUsed ()

    int*        dataFileGet_colUsed             (VisuData *visuData);

This method is used to retrieve the vector used to adapt or not the colour to the value of the loaded data.

`visuData` : | a VisuData object.
Returns : | a three value array, own by V_Sim. It should not be freed.

### dataFileGet_nbColumns ()

    int         dataFileGet_nbColumns           (VisuData *visuData);

This method is used to retrieve the number of columns of data read in the loaded file.

`visuData` : | a VisuData object.
Returns : | this number of columns.

### dataFileSet_colorType ()

    int         dataFileSet_colorType           (VisuData *visuData,
                                                 DataFileColorModeId color);

Choose the encoding of colour for the three channels.

`visuData` : | a VisuData object ;
`color` : | the colour dimension (RGB or HSV).
Returns : | 1 if `visuData_createAllNodes()` should be called.

### dataFileGet_colorType ()

    DataFileColorModeId dataFileGet_colorType   (VisuData *visuData);

This method is used to retrieve the encoding of colour for the three channels.

`visuData` : | a VisuData object.
Returns : | RGB or HSV.

### dataFileGet_valuesTransformedInRGB ()

    void        dataFileGet_valuesTransformedInRGB
                                                (VisuData *visuData,
                                                 float *valuesTransformed,
                                                 float *valuesFrom);

Apply the colour transformation defined by vector A, vector B and columnUsed on the three given values. The returned colour is coded in RGB.

`visuData` : | the VisuData object which the colour data are associated to ;
`valuesTransformed` : | a three channel encoded colour ;
`valuesFrom` : | three values in [0;1].

### dataFileSet_shade ()

    int         dataFileSet_shade               (VisuData *visuData,
                                                 Shade *shade);

Apply all caracteristic of the given shade to the colorization the the given VisuObject.

`visuData` : | the VisuData object which the colour data are associated to ;
`shade` : | a valid Shade object.
Returns : | 1 if `visuData_createAllNodes()` should be called.

### dataFileApply_hideOnMinValue ()

    gboolean    dataFileApply_hideOnMinValue    (VisuData *visuData,
                                                 int column,
                                                 float value);

Use this method hide nodes whose data from column `column` is lower than the given `value`. If `column` is -1, then all previous masking are cancelled.

`visuData` : | the VisuData object which the colour data are associated to ;
`column` : | a integer corresponding to a column id ;
`value` : | a floating point value.
Returns : | TRUE if `visuData_createAllNodes()` should be called and "NodeRenderedChanged" signal should be emitted (with a NULL VisuElement parameter).