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],
                                             gboolean logScale,
                                             guint nIsoLines);
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,
                                             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,
                                             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        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],
                                             gboolean logScale,
                                             guint nIsoLines);

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 ;
logScale : if TRUE, field is drawn in log scale ;
nIsoLines : the number of isolines to draw.

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

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.