VisuScalarField

VisuScalarField — Gives capabilities to load a scalar field.

Synopsis

#define             VISU_SCALAR_FIELD_DEFINED_IN_STRUCT_FILE
struct              VisuScalarField;
struct              VisuScalarFieldClass;
enum                VisuScalarFieldMeshFlags;
                    VisuScalarFieldMethod;
                    VisuScalarFieldMethodClass;
gboolean            (*VisuScalarFieldMethodLoadFunc)    (VisuScalarFieldMethod *meth,
                                                         const gchar *filename,
                                                         GList **fieldList,
                                                         GError **error);
void                visu_scalar_field_addOption         (VisuScalarField *field,
                                                         ToolOption *option);
GList *             visu_scalar_field_getAllOptions     (VisuScalarField *field);
const gchar *       visu_scalar_field_getCommentary     (VisuScalarField *field);
double ***          visu_scalar_field_getData           (VisuScalarField *field);
const GArray *      visu_scalar_field_getDataArray      (const VisuScalarField *field);
const gchar *       visu_scalar_field_getFilename       (VisuScalarField *field);
void                visu_scalar_field_getGridSize       (VisuScalarField *field,
                                                         guint grid[3]);
VisuScalarFieldMeshFlags visu_scalar_field_getMeshtype  (VisuScalarField *field);
double *            visu_scalar_field_getMeshx          (VisuScalarField *field);
double *            visu_scalar_field_getMeshy          (VisuScalarField *field);
double *            visu_scalar_field_getMeshz          (VisuScalarField *field);
void                visu_scalar_field_getMinMax         (VisuScalarField *field,
                                                         double minmax[2]);
void                visu_scalar_field_getOriginShift    (VisuScalarField *field,
                                                         float shift[3]);
gboolean            visu_scalar_field_getValue          (VisuScalarField *field,
                                                         float xyz[3],
                                                         double *value,
                                                         float extension[3]);
GList *             visu_scalar_field_method_getAll     (void);
gboolean            visu_scalar_field_method_load       (VisuScalarFieldMethod *fmt,
                                                         const gchar *filename,
                                                         GList **fieldList,
                                                         GError **error);
VisuScalarFieldMethod * visu_scalar_field_method_new    (const gchar *descr,
                                                         const gchar **patterns,
                                                         VisuScalarFieldMethodLoadFunc method,
                                                         int priority);
VisuScalarField *   visu_scalar_field_new               (const gchar *filename);
gboolean            visu_scalar_field_new_fromFile      (const gchar *filename,
                                                         GList **fieldList,
                                                         GHashTable *table,
                                                         GError **error);
void                visu_scalar_field_setCommentary     (VisuScalarField *field,
                                                         const gchar *comment);
void                visu_scalar_field_setData           (VisuScalarField *field,
                                                         GArray *data,
                                                         gboolean xyzOrder);
void                visu_scalar_field_setGridSize       (VisuScalarField *field,
                                                         const guint grid[3]);
void                visu_scalar_field_setMeshtype       (VisuScalarField *field,
                                                         VisuScalarFieldMeshFlags meshtype);
void                visu_scalar_field_setOriginShift    (VisuScalarField *field,
                                                         const float shift[3]);

Object Hierarchy

  GObject
   +----VisuScalarField
  GObject
   +----ToolFileFormat
         +----VisuScalarFieldMethod

Implemented Interfaces

VisuScalarField implements VisuBoxed.

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.

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.

In coordination with VisuPlane and ToolShade, 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 VISU_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

VISU_SCALAR_FIELD_DEFINED_IN_STRUCT_FILE

#define VISU_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 VisuScalarField

struct VisuScalarField;

An opaque structure for the scalar field.


struct VisuScalarFieldClass

struct VisuScalarFieldClass {
  GObjectClass parent;
};

An opaque structure for the class.

GObjectClass parent;

the parent class.

enum VisuScalarFieldMeshFlags

typedef enum {
    VISU_SCALAR_FIELD_MESH_UNIFORM,
    VISU_SCALAR_FIELD_MESH_NON_UNIFORM
} VisuScalarFieldMeshFlags;

flag (comment) standing at the begining of a Scalar field file, that gives informations concerning the mesh.

VISU_SCALAR_FIELD_MESH_UNIFORM

the mesh has constant divisions along x, y and z axis ;

VISU_SCALAR_FIELD_MESH_NON_UNIFORM

the mesh has non linear divisions along x, y or z axis.

VisuScalarFieldMethod

typedef struct _VisuScalarFieldMethod VisuScalarFieldMethod;

An opaque structure.


VisuScalarFieldMethodClass

typedef struct _VisuScalarFieldMethodClass VisuScalarFieldMethodClass;

An opaque structure.


VisuScalarFieldMethodLoadFunc ()

gboolean            (*VisuScalarFieldMethodLoadFunc)    (VisuScalarFieldMethod *meth,
                                                         const gchar *filename,
                                                         GList **fieldList,
                                                         GError **error);

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.

meth :

a VisuScalarFieldMethod object ;

filename :

the filename (path) the field should be loaded from ;. [type filename]

fieldList :

a GList to store read field(s) ;. [out][element-type VisuScalarField]

error :

a location on a error pointer.

Returns :

TRUE if the read file is in a valid format (even with minor errors), FALSE otherwise.

visu_scalar_field_addOption ()

void                visu_scalar_field_addOption         (VisuScalarField *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 VisuScalarField object ;

option :

a newly allocated option.

visu_scalar_field_getAllOptions ()

GList *             visu_scalar_field_getAllOptions     (VisuScalarField *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 VisuScalarField 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. [transfer container][element-type ToolOption*]

visu_scalar_field_getCommentary ()

const gchar *       visu_scalar_field_getCommentary     (VisuScalarField *field);

If the file format support a commentary, this is a good method to get it.

field :

a VisuScalarField object.

Returns :

a pointer on the commentary (it should not be freed), can be NULL.

visu_scalar_field_getData ()

double ***          visu_scalar_field_getData           (VisuScalarField *field);

The data are stored as a 3 indexes array in x, y and z increasing.

field :

a VisuScalarField object.

Returns :

a pointer on the allocated data array (it should not be freed).

visu_scalar_field_getDataArray ()

const GArray *      visu_scalar_field_getDataArray      (const VisuScalarField *field);

The data are stored z first in a flatten array.

field :

a VisuScalarField object.

Returns :

a pointer on the allocated data array. [transfer none][element-type double]

Since 3.7


visu_scalar_field_getFilename ()

const gchar *       visu_scalar_field_getFilename       (VisuScalarField *field);

The data are read from a file.

field :

a VisuScalarField object.

Returns :

a pointer on the filename (it should not be freed).

visu_scalar_field_getGridSize ()

void                visu_scalar_field_getGridSize       (VisuScalarField *field,
                                                         guint grid[3]);

This method is used to get the division in x, y, and z directions.

field :

a VisuScalarField object ;

grid :

3 integer locations. [out caller-allocates][type ToolGridSize]

visu_scalar_field_getMeshtype ()

VisuScalarFieldMeshFlags visu_scalar_field_getMeshtype  (VisuScalarField *field);

The vertex may be distributed linearly along the different directions or customily distributed.

field :

a VisuScalarField object ; to be added

Returns :

a VisuScalarFieldMeshFlags (uniform or nonuniform).

visu_scalar_field_getMeshx ()

double *            visu_scalar_field_getMeshx          (VisuScalarField *field);

The mesh along x is stored as an array in x increasing.

field :

a VisuScalarField object.

Returns :

a pointer on the allocated meshx array (it should not be freed).

visu_scalar_field_getMeshy ()

double *            visu_scalar_field_getMeshy          (VisuScalarField *field);

The mesh along y is stored as an array in y increasing.

field :

a VisuScalarField object.

Returns :

a pointer on the allocated meshy array (it should not be freed).

visu_scalar_field_getMeshz ()

double *            visu_scalar_field_getMeshz          (VisuScalarField *field);

The mesh along z is stored as an array in z increasing.

field :

a VisuScalarField object.

Returns :

a pointer on the allocated meshz array (it should not be freed).

visu_scalar_field_getMinMax ()

void                visu_scalar_field_getMinMax         (VisuScalarField *field,
                                                         double minmax[2]);

Get the minimum and the maximum values of the given field.

field :

a VisuScalarField object ;

minmax :

two double values. [array fixed-size=2]

visu_scalar_field_getOriginShift ()

void                visu_scalar_field_getOriginShift    (VisuScalarField *field,
                                                         float shift[3]);

The scalar field can be shifted with respect to the origin of the VisuData box. Use this routine to get this shift.

field :

a VisuScalarField object.

shift :

a location to store the shift of field. [out caller-allocates][type ToolVector]

Since 3.7


visu_scalar_field_getValue ()

gboolean            visu_scalar_field_getValue          (VisuScalarField *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, then it allow the coordinates to extend inside the given extension.

field :

a VisuScalarField object ;

xyz :

a point coordinate (in real space) ;. [array fixed-size=3]

value :

a location to store the value ;. [out caller-allocates]

extension :

a possible extension in box coordinates. [array fixed-size=3]

Returns :

TRUE if the value can be interpolate, FALSE otherwise, for instance, when the point xyz is out of bounds.

visu_scalar_field_method_getAll ()

GList *             visu_scalar_field_method_getAll     (void);

This routine gives access to all the registered load method for scamlar fields.

Returns :

returns a list of V_Sim owned VisuScalarFieldMethod objects. [transfer none][element-type VisuScalarFieldMethod*]

visu_scalar_field_method_load ()

gboolean            visu_scalar_field_method_load       (VisuScalarFieldMethod *fmt,
                                                         const gchar *filename,
                                                         GList **fieldList,
                                                         GError **error);

Call the load routine of the given scalar field file format fmt.

fmt :

a VisuScalarFieldMethod object ;

filename :

a path ;. [type filename]

fieldList :

a location to store a list ;. [out][element-type VisuScalarField*]

error :

a location to an error.

Returns :

TRUE on success.

Since 3.7


visu_scalar_field_method_new ()

VisuScalarFieldMethod * visu_scalar_field_method_new    (const gchar *descr,
                                                         const gchar **patterns,
                                                         VisuScalarFieldMethodLoadFunc method,
                                                         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 is 300 for instance).

descr :

the name of the method ;

patterns :

a NULL terminated list of strings ;. [array zero-terminated=1]

method :

a VisuScalarFieldMethodLoadFunc method ;. [scope call]

priority :

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

Returns :

a newly create method to load scalar fields. [transfer full]

visu_scalar_field_new ()

VisuScalarField *   visu_scalar_field_new               (const gchar *filename);

Create a new VisuScalarField 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. [type filename]

Returns :

a newly created VisuScalarField object. [transfer full]

visu_scalar_field_new_fromFile ()

gboolean            visu_scalar_field_new_fromFile      (const gchar *filename,
                                                         GList **fieldList,
                                                         GHashTable *table,
                                                         GError **error);

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 ;. [type filename]

fieldList :

a GList to store read field(s) ;. [transfer full][out][element-type VisuScalarField*]

table :

a set of different options (can be NULL). [allow-none]

error :

a location on a error pointer ;

Returns :

TRUE if everything goes with no error. [skip]

visu_scalar_field_setCommentary ()

void                visu_scalar_field_setCommentary     (VisuScalarField *field,
                                                         const gchar *comment);

A commentary can be associated to a VisuScalarField, use this method to set it. The value of comment is NOT copied.

field :

a VisuScalarField object ;

comment :

an UTF-8 string to store as a commentary.

visu_scalar_field_setData ()

void                visu_scalar_field_setData           (VisuScalarField *field,
                                                         GArray *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->priv->nElements. Then use visu_scalar_field_setGridSize() before using this method.

field :

a VisuScalarField object ;

data :

an array containing data to be copied ;. [element-type double]

xyzOrder :

a boolean.

visu_scalar_field_setGridSize ()

void                visu_scalar_field_setGridSize       (VisuScalarField *field,
                                                         const guint 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 visu_scalar_field_getData() to get a pointer on this data array.

field :

a VisuScalarField object ;

grid :

3 integers. [array fixed-size=3]

visu_scalar_field_setMeshtype ()

void                visu_scalar_field_setMeshtype       (VisuScalarField *field,
                                                         VisuScalarFieldMeshFlags meshtype);

Change the distribution of the vertex of the scalarfield between regular or custom.

field :

a VisuScalarField object ;

meshtype :

a VisuScalarFieldMeshFlags object.

visu_scalar_field_setOriginShift ()

void                visu_scalar_field_setOriginShift    (VisuScalarField *field,
                                                         const float shift[3]);

The scalar field can be shifted with respect to the origin of the VisuData box. Use this routine to set this shift.

field :

a VisuScalarField object.

shift :

a shift to apply to. [array fixed-size=3]

Since 3.7