scalarFields

scalarFields — Gives capabilities to load a scalar field.

Synopsis

enum                ScalarField_meshflag;
struct              ScalarField_struct;
typedef             ScalarField;
#define             SCALAR_FIELD_DEFINED_IN_STRUCT_FILE
ScalarField*        scalarFieldNew                      (const gchar *filename);
void                scalarFieldFree                     (ScalarField *field);
gboolean            scalarFieldLoad_fromFile            (const gchar *filename,
                                                         GList **fieldList,
                                                         GError **error,
                                                         GHashTable *table);
void                scalarFieldGet_minMax               (ScalarField *field,
                                                         double minmax[2]);
void                scalarFieldSet_data                 (ScalarField *field,
                                                         double *data,
                                                         gboolean xyzOrder);
void                scalarFieldSet_fitToBox             (VisuData *data,
                                                         ScalarField *field);
void                scalarFieldGet_box                  (ScalarField *field,
                                                         double box[6]);
void                scalarFieldSet_box                  (ScalarField *field,
                                                         double box[6]);
void                scalarFieldSet_boxFull              (ScalarField *field,
                                                         double box[3][3]);
void                scalarFieldGet_gridSize             (ScalarField *field,
                                                         int grid[3]);
void                scalarFieldSet_gridSize             (ScalarField *field,
                                                         int grid[3]);
void                scalarFieldSet_meshtype             (ScalarField *field,
                                                         ScalarField_meshflag meshtype);
ScalarField_meshflag  scalarFieldGet_meshtype           (ScalarField *field);
double*             scalarFieldGet_meshx                (ScalarField *field);
double*             scalarFieldGet_meshy                (ScalarField *field);
double*             scalarFieldGet_meshz                (ScalarField *field);
double***           scalarFieldGet_data                 (ScalarField *field);
gchar*              scalarFieldGet_filename             (ScalarField *field);
gchar*              scalarFieldGet_commentary           (ScalarField *field);
void                scalarFieldSet_commentary           (ScalarField *field,
                                                         gchar *comment);
gboolean            scalarFieldGet_periodic             (ScalarField *field);
void                scalarFieldSet_periodic             (ScalarField *field,
                                                         gboolean periodic);
GList*              scalarFieldGet_allOptions           (ScalarField *field);
void                scalarFieldAdd_option               (ScalarField *field,
                                                         ToolOption *option);
gboolean            scalarFieldGet_value                (ScalarField *field,
                                                         float xyz[3],
                                                         double *value,
                                                         float extension[3]);
gboolean            (*ScalarFieldLoadMethod)            (const gchar *filename,
                                                         GList **fieldList,
                                                         GError **error,
                                                         GHashTable *table);
void                scalarFieldAdd_loadMethod           (const gchar *name,
                                                         ScalarFieldLoadMethod method,
                                                         ToolFileFormat *format,
                                                         int priority);
GList*              scalarFieldGet_allLoadMethods       (void);
void                scalarFieldInit                     (void);

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 g_object_set_data(). Then V_Sim will be able to handle the structure file as a density file also.

Details

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.

struct ScalarField_struct

struct ScalarField_struct;

Structure that stores informations and data of a scalar field.


ScalarField

typedef struct ScalarField_struct ScalarField;

Short name to address ScalarField_struct objects.


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.


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.

scalarFieldLoad_fromFile ()

gboolean            scalarFieldLoad_fromFile            (const gchar *filename,
                                                         GList **fieldList,
                                                         GError **error,
                                                         GHashTable *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.

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.

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

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.

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_boxFull ()

void                scalarFieldSet_boxFull              (ScalarField *field,
                                                         double box[3][3]);

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

field :

a ScalarField object ;

box :

6 floating point values.

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.

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

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

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.

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.

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.

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.

scalarFieldAdd_option ()

void                scalarFieldAdd_option               (ScalarField *field,
                                                         ToolOption *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_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.

ScalarFieldLoadMethod ()

gboolean            (*ScalarFieldLoadMethod)            (const gchar *filename,
                                                         GList **fieldList,
                                                         GError **error,
                                                         GHashTable *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.

scalarFieldAdd_loadMethod ()

void                scalarFieldAdd_loadMethod           (const gchar *name,
                                                         ScalarFieldLoadMethod method,
                                                         ToolFileFormat *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 ToolFileFormat object ;

priority :

a priority value (the lower value, the higher priority).

scalarFieldGet_allLoadMethods ()

GList*              scalarFieldGet_allLoadMethods       (void);

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.

scalarFieldInit ()

void                scalarFieldInit                     (void);

Initialisation method, should not be used.