dataFile

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

Synopsis

                    VisuColorization;
enum                VisuColorizationErrorFlag;
gboolean            (*VisuColorizationHidingFunc)       (VisuColorization *dt,
                                                         const VisuColorizationNodeData *values,
                                                         gpointer data);
enum                VisuColorizationInputScaleId;
struct              VisuColorizationNodeData;
gboolean            visu_colorization_applyHide         (VisuColorization *dt,
                                                         VisuData *dataObj);
VisuColorization *  visu_colorization_get               (VisuData *data,
                                                         gboolean create,
                                                         gboolean *new);
const int *         visu_colorization_getColUsed        (const VisuColorization *dt);
gboolean            visu_colorization_getColumnMinMax   (const VisuColorization *dt,
                                                         float minMax[2],
                                                         guint column);
GQuark              visu_colorization_getErrorQuark     ();
gchar *             visu_colorization_getFile           (const VisuColorization *dt);
gboolean            visu_colorization_getFileSet        (const VisuColorization *dt);
float               visu_colorization_getMax            (const VisuColorization *dt,
                                                         int column);
float               visu_colorization_getMin            (const VisuColorization *dt,
                                                         int column);
int                 visu_colorization_getNColumns       (const VisuColorization *dt);
gboolean            visu_colorization_getRestrictInRange
                                                        (const VisuColorization *dt);
VisuColorizationInputScaleId visu_colorization_getScaleType
                                                        (const VisuColorization *dt);
int                 visu_colorization_getScalingUsed    (const VisuColorization *dt);
ToolShade *         visu_colorization_getShade          (const VisuColorization *dt);
gboolean            visu_colorization_getSingleColumnId (const VisuColorization *dt,
                                                         gint *id);
gboolean            visu_colorization_getUsed           (const VisuColorization *dt);
int                 visu_colorization_init              ();
VisuColorization *  visu_colorization_new               ();
VisuColorization *  visu_colorization_new_fromData      (VisuData *dataObj,
                                                         guint nbColumns,
                                                         GArray *data,
                                                         gboolean *new);
VisuColorization *  visu_colorization_new_fromFile      (VisuData *data,
                                                         const char *filename,
                                                         gboolean *new,
                                                         GError **error);
VisuColorization *  visu_colorization_ref               (VisuColorization *dt);
gboolean            visu_colorization_setColUsed        (VisuColorization *dt,
                                                         int val,
                                                         int pos);
void                visu_colorization_setHidingFunc     (VisuColorization *dt,
                                                         VisuColorizationHidingFunc func,
                                                         gpointer data,
                                                         GDestroyNotify destroy);
gboolean            visu_colorization_setMax            (VisuColorization *dt,
                                                         float max,
                                                         int column);
gboolean            visu_colorization_setMin            (VisuColorization *dt,
                                                         float min,
                                                         int column);
gboolean            visu_colorization_setRestrictInRange
                                                        (VisuColorization *dt,
                                                         gboolean status);
gboolean            visu_colorization_setScaleType      (VisuColorization *dt,
                                                         VisuColorizationInputScaleId scale);
gboolean            visu_colorization_setScalingUsed    (VisuColorization *dt,
                                                         int val);
gboolean            visu_colorization_setShade          (VisuColorization *dt,
                                                         ToolShade *shade);
gboolean            visu_colorization_setUsed           (VisuData *data,
                                                         int val);
void                visu_colorization_unref             (VisuColorization *dt);

Object Hierarchy

  GBoxed
   +----VisuColorization

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 visu_colorization_new_fromFile(). 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 visu_colorization_setUsed().

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 visu_colorization_applyHide(), it is possible to hide some nodes depending on given input data.

Details

VisuColorization

typedef struct _VisuColorization VisuColorization;

An opaque structure to store colorisation settings.

Since 3.7


enum VisuColorizationErrorFlag

typedef enum {
    VISU_COLORIZATION_ERROR_NO_COLUMN,
    VISU_COLORIZATION_ERROR_MISSING_DATA
} VisuColorizationErrorFlag;

Possible errors when reading a file with column data.

VISU_COLORIZATION_ERROR_NO_COLUMN

no column can be found in the file ;

VISU_COLORIZATION_ERROR_MISSING_DATA

some data are missing to match the number of nodes.

VisuColorizationHidingFunc ()

gboolean            (*VisuColorizationHidingFunc)       (VisuColorization *dt,
                                                         const VisuColorizationNodeData *values,
                                                         gpointer data);

Function to decide to hide a node or not.

dt :

a VisuColorization object ;

values :

the column values.

data :

some data. [closure]

Returns :

TRUE to hide a node depending on values.

Since 3.7


enum VisuColorizationInputScaleId

typedef enum {
    VISU_COLORIZATION_NORMALIZE,
    VISU_COLORIZATION_MINMAX
} VisuColorizationInputScaleId;

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

VISU_COLORIZATION_NORMALIZE

input data are converted into [0;1] using input min/max values.

VISU_COLORIZATION_MINMAX

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

struct VisuColorizationNodeData

struct VisuColorizationNodeData {
  const VisuData *dataObj;
  const VisuNode *node;
  GArray *data;
};

This structure holds the column value for a given node. It is mainly intended for bindings...

const VisuData *dataObj;

a VisuData object.

const VisuNode *node;

a VisuNode object.

GArray *data;

the column values for node. [element-type float]

visu_colorization_applyHide ()

gboolean            visu_colorization_applyHide         (VisuColorization *dt,
                                                         VisuData *dataObj);

From the hiding function of dt (see visu_colorization_setHidingFunc()), apply hiding property to nodes of dataObj.

dt :

a VisuColorization object.

dataObj :

a VisuData object to apply hiding scheme on.

Returns :

TRUE if "VisibilityChanged" signal should be emitted.

Since 3.7


visu_colorization_get ()

VisuColorization *  visu_colorization_get               (VisuData *data,
                                                         gboolean create,
                                                         gboolean *new);

Return an already associated VisuColorization object to data, or create it if necessary.

data :

a VisuData object. [allow-none]

create :

a boolean.

new :

a boolean location. [out][allow-none]

Returns :

a VisuColorization object. This object will be automatically freed with data. [transfer none]

Since 3.7


visu_colorization_getColUsed ()

const int *         visu_colorization_getColUsed        (const VisuColorization *dt);

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

dt :

a VisuData object. [allow-none]

Returns :

a three value array, own by V_Sim. It should not be freed. [transfer none][array fixed-size=3]

visu_colorization_getColumnMinMax ()

gboolean            visu_colorization_getColumnMinMax   (const VisuColorization *dt,
                                                         float minMax[2],
                                                         guint 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.

dt :

the VisuColorization 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.

visu_colorization_getErrorQuark ()

GQuark              visu_colorization_getErrorQuark     ();

Internal routine for error handling.

Returns :

the GQuark associated to errors related to colour data files. [transfer none]

visu_colorization_getFile ()

gchar *             visu_colorization_getFile           (const VisuColorization *dt);

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

dt :

a VisuColorization object. [allow-none]

Returns :

the name of the input data file if set. [transfer full]

visu_colorization_getFileSet ()

gboolean            visu_colorization_getFileSet        (const VisuColorization *dt);

A set of data per node can be associated to a VisuData. This routine retrieves if visuData has it or not.

dt :

a VisuColorization object. [allow-none]

Returns :

TRUE if visuData has colour data associated.

Since 3.6


visu_colorization_getMax ()

float               visu_colorization_getMax            (const VisuColorization *dt,
                                                         int column);

Retrieve the maximum value used when scaling is user defined.

dt :

a VisuData object. [allow-none]

column :

a column id.

Returns :

the maximum bound if dt is not NULL or the default value if not.

visu_colorization_getMin ()

float               visu_colorization_getMin            (const VisuColorization *dt,
                                                         int column);

Retrieve the minimum value used when scaling is user defined.

dt :

a VisuData object. [allow-none]

column :

a column id.

Returns :

the minimum bound if dt is not NULL or the default value if not.

visu_colorization_getNColumns ()

int                 visu_colorization_getNColumns       (const VisuColorization *dt);

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

dt :

a VisuColorization object.

Returns :

this number of columns.

visu_colorization_getRestrictInRange ()

gboolean            visu_colorization_getRestrictInRange
                                                        (const VisuColorization *dt);

The colourisation can be applied on all nodes or on nodes within range. See visu_colorization_setRestrictInRange().

dt :

a VisuColorization object with some data file information.

Returns :

TRUE if colourisation is done only if values are in range.

Since 3.7


visu_colorization_getScaleType ()

VisuColorizationInputScaleId visu_colorization_getScaleType
                                                        (const VisuColorization *dt);

Retrieve the scaling method of input data associated to the given dt.

dt :

a VisuColorization object. [allow-none]

Returns :

the scaling method if dt is not NULL or the default value if not.

visu_colorization_getScalingUsed ()

int                 visu_colorization_getScalingUsed    (const VisuColorization *dt);

Retrieve if a column is used as entry to scale the nodes.

dt :

a VisuColorization object hosting the data values. [allow-none]

Returns :

-1 if no scaling is used.

visu_colorization_getShade ()

ToolShade *         visu_colorization_getShade          (const VisuColorization *dt);

Return the shade used to colourise the nodes.

dt :

the VisuColorization object which the colour data are associated to. [allow-none]

Returns :

the ToolShade used (own by V_Sim). [transfer none]

visu_colorization_getSingleColumnId ()

gboolean            visu_colorization_getSingleColumnId (const VisuColorization *dt,
                                                         gint *id);

The colourisation can be applied from values coming from several columns. But, if only one column is used, this routine will give it in id.

dt :

a VisuColorization object.

id :

a location to store a column id. [out]

Returns :

FALSE if several columns are used, or TRUE if a single column is used for the colourisation.

visu_colorization_getUsed ()

gboolean            visu_colorization_getUsed           (const VisuColorization *dt);

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

dt :

a VisuColorization object to get if the colorisation tool is set or not ;. [allow-none]

Returns :

1 if the used flag is set.

visu_colorization_init ()

int                 visu_colorization_init              ();

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

Returns :

1 if eveything goes right.

visu_colorization_new ()

VisuColorization *  visu_colorization_new               ();

Create a new object to store colorisation data.

Returns :

a newly created VisuColorization. [transfer full]

Since 3.7


visu_colorization_new_fromData ()

VisuColorization *  visu_colorization_new_fromData      (VisuData *dataObj,
                                                         guint nbColumns,
                                                         GArray *data,
                                                         gboolean *new);

Add colourisation data to dataObj.

dataObj :

a VisuData object.

nbColumns :

an integer.

data :

the colorization data. [element-type gfloat]

new :

a location for a boolean. [allow-none][out caller-allocates]

Returns :

a newly created VisuColorization or NULL. [transfer full]

Since 3.7


visu_colorization_new_fromFile ()

VisuColorization *  visu_colorization_new_fromFile      (VisuData *data,
                                                         const char *filename,
                                                         gboolean *new,
                                                         GError **error);

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

data :

a VisuData object to attach the data file to ;

filename :

the path to find the data file on the disk ;

new :

a location for a boolean. [allow-none][out caller-allocates]

error :

a location to a NULL GError.

Returns :

a newly created VisuColorization or NULL. [transfer full]

visu_colorization_ref ()

VisuColorization *  visu_colorization_ref               (VisuColorization *dt);

Increase the ref counter.

dt :

a VisuColorization object.

Returns :

itself.

Since 3.7


visu_colorization_setColUsed ()

gboolean            visu_colorization_setColUsed        (VisuColorization *dt,
                                                         int val,
                                                         int pos);

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

dt :

a VisuColorization object ;

val :

a column id a special value ;

pos :

an integer in [0;2].

Returns :

TRUE if VisuNodeArray::RenderingChanged should be emitted.

visu_colorization_setHidingFunc ()

void                visu_colorization_setHidingFunc     (VisuColorization *dt,
                                                         VisuColorizationHidingFunc func,
                                                         gpointer data,
                                                         GDestroyNotify destroy);

Set the hiding function to be called when visu_colorization_applyHide() is used.

dt :

a VisuColorization object.

func :

a VisuColorizationHidingFunc function. [allow-none][closure data]

data :

some data. [closure]

destroy :

a destroy function for data.

Since 3.7


visu_colorization_setMax ()

gboolean            visu_colorization_setMax            (VisuColorization *dt,
                                                         float max,
                                                         int column);

When the scaling method is VISU_COLORIZATION_MINMAX (see VisuColorizationInputScaleId) 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.

dt :

a VisuColorization object ;

max :

a floating point value.

column :

a column id.

Returns :

TRUE if VisuNodeArray::RenderingChanged should be emitted.

visu_colorization_setMin ()

gboolean            visu_colorization_setMin            (VisuColorization *dt,
                                                         float min,
                                                         int column);

When the scaling method is VISU_COLORIZATION_MINMAX (see VisuColorizationInputScaleId) 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.

dt :

a VisuColorization object ;

min :

a floating point value.

column :

a column id.

Returns :

TRUE if VisuNodeArray::RenderingChanged should be emitted.

visu_colorization_setRestrictInRange ()

gboolean            visu_colorization_setRestrictInRange
                                                        (VisuColorization *dt,
                                                         gboolean status);

The colourisation can be applied on all nodes or on nodes within range. See visu_colorization_getRestrictInRange() and visu_colorization_setMin() and visu_colorization_setMax().

dt :

a VisuColorization object with some data file information.

status :

a boolean.

Returns :

TRUE if the status is changed indeed.

Since 3.7


visu_colorization_setScaleType ()

gboolean            visu_colorization_setScaleType      (VisuColorization *dt,
                                                         VisuColorizationInputScaleId scale);

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

dt :

a VisuColorization object ;

scale :

an integer.

Returns :

TRUE if VisuNodeArray::RenderingChanged should be emitted.

visu_colorization_setScalingUsed ()

gboolean            visu_colorization_setScalingUsed    (VisuColorization *dt,
                                                         int val);

Give the column id to used to take the scaling values from. Set -1 if no scaling used. The scaling is used to change the size of each node, using an homothetic factor.

dt :

a VisuColorization object hosting the data values ;

val :

a column id.

Returns :

TRUE if the status changed.

visu_colorization_setShade ()

gboolean            visu_colorization_setShade          (VisuColorization *dt,
                                                         ToolShade *shade);

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

dt :

the VisuColorization object which the colour data are associated to ;

shade :

a valid ToolShade object.

Returns :

TRUE if VisuNodeArray::RenderingChanged should be emitted.

visu_colorization_setUsed ()

gboolean            visu_colorization_setUsed           (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 visu_colorization_new_fromFile() to choose them.

data :

a VisuData object to set the colorisation tool or not ;

val :

a boolean.

Returns :

TRUE if val is true and if a valid input file is already in memory.

visu_colorization_unref ()

void                visu_colorization_unref             (VisuColorization *dt);

Decrease the ref counter, free all memory if counter reachs zero.

dt :

a VisuColorization object.

Since 3.7