![]() |
![]() |
![]() |
V_Sim API - Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces |
#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]
);
GObject +----VisuScalarField
GObject +----ToolFileFormat +----VisuScalarFieldMethod
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.
#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 VisuScalarFieldClass { GObjectClass parent; };
An opaque structure for the class.
GObjectClass |
the parent class. |
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.
typedef struct _VisuScalarFieldMethod VisuScalarFieldMethod;
An opaque structure.
typedef struct _VisuScalarFieldMethodClass VisuScalarFieldMethodClass;
An opaque structure.
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
.
|
a VisuScalarFieldMethod object ; |
|
the filename (path) the field should be loaded from ;. [type filename] |
|
a GList to store read field(s) ;. [out][element-type VisuScalarField] |
|
a location on a error pointer. |
Returns : |
TRUE if the read file is in a valid format (even with minor errors), FALSE otherwise. |
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.
|
a VisuScalarField object ; |
|
a newly allocated option. |
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...
|
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*]
|
const gchar * visu_scalar_field_getCommentary (VisuScalarField *field
);
If the file format support a commentary, this is a good method to get it.
|
a VisuScalarField object. |
Returns : |
a pointer on the commentary (it should not be freed), can be NULL. |
double *** visu_scalar_field_getData (VisuScalarField *field
);
The data are stored as a 3 indexes array in x, y and z increasing.
|
a VisuScalarField object. |
Returns : |
a pointer on the allocated data array (it should not be freed). |
const GArray * visu_scalar_field_getDataArray (const VisuScalarField *field
);
The data are stored z first in a flatten array.
|
a VisuScalarField object. |
Returns : |
a pointer on the allocated data array. [transfer none][element-type double] |
Since 3.7
const gchar * visu_scalar_field_getFilename (VisuScalarField *field
);
The data are read from a file.
|
a VisuScalarField object. |
Returns : |
a pointer on the filename (it should not be freed). |
void visu_scalar_field_getGridSize (VisuScalarField *field
,guint grid[3]
);
This method is used to get the division in x, y, and z directions.
|
a VisuScalarField object ; |
|
3 integer locations. [out caller-allocates][type ToolGridSize] |
VisuScalarFieldMeshFlags visu_scalar_field_getMeshtype (VisuScalarField *field
);
The vertex may be distributed linearly along the different directions or customily distributed.
|
a VisuScalarField object ; to be added |
Returns : |
a VisuScalarFieldMeshFlags (uniform or nonuniform). |
double * visu_scalar_field_getMeshx (VisuScalarField *field
);
The mesh along x is stored as an array in x increasing.
|
a VisuScalarField object. |
Returns : |
a pointer on the allocated meshx array (it should not be freed). |
double * visu_scalar_field_getMeshy (VisuScalarField *field
);
The mesh along y is stored as an array in y increasing.
|
a VisuScalarField object. |
Returns : |
a pointer on the allocated meshy array (it should not be freed). |
double * visu_scalar_field_getMeshz (VisuScalarField *field
);
The mesh along z is stored as an array in z increasing.
|
a VisuScalarField object. |
Returns : |
a pointer on the allocated meshz array (it should not be freed). |
void visu_scalar_field_getMinMax (VisuScalarField *field
,double minmax[2]
);
Get the minimum and the maximum values of the given field
.
|
a VisuScalarField object ; |
|
two double values. [array fixed-size=2] |
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
.
|
a VisuScalarField object. |
|
a location to store the shift
of field . [out caller-allocates][type ToolVector]
|
Since 3.7
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
.
|
a VisuScalarField object ; |
|
a point coordinate (in real space) ;. [array fixed-size=3] |
|
a location to store the value ;. [out caller-allocates] |
|
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. |
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*] |
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
.
|
a VisuScalarFieldMethod object ; |
|
a path ;. [type filename] |
|
a location to store a list ;. [out][element-type VisuScalarField*] |
|
a location to an error. |
Returns : |
TRUE on success. |
Since 3.7
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).
|
the name of the method ; |
|
a NULL terminated list of strings ;. [array zero-terminated=1] |
|
a VisuScalarFieldMethodLoadFunc method ;. [scope call] |
|
a priority value (the lower value, the higher priority). |
Returns : |
a newly create method to load scalar fields. [transfer full] |
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.
|
the path to the filename the field should be read from. [type filename] |
Returns : |
a newly created VisuScalarField object. [transfer full] |
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
.
|
the path to the file to be loaded ;. [type filename] |
|
a GList to store read field(s) ;. [transfer full][out][element-type VisuScalarField*] |
|
a set of different options (can be NULL). [allow-none] |
|
a location on a error pointer ; |
Returns : |
TRUE if everything goes with no error. [skip] |
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.
|
a VisuScalarField object ; |
|
an UTF-8 string to store as a commentary. |
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.
|
a VisuScalarField object ; |
|
an array containing data to be copied ;. [element-type double] |
|
a boolean. |
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.
|
a VisuScalarField object ; |
|
3 integers. [array fixed-size=3] |
void visu_scalar_field_setMeshtype (VisuScalarField *field
,VisuScalarFieldMeshFlags meshtype
);
Change the distribution of the vertex of the scalarfield between regular or custom.
|
a VisuScalarField object ; |
|
a VisuScalarFieldMeshFlags object. |
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
.
|
a VisuScalarField object. |
|
a shift to apply to. [array fixed-size=3] |
Since 3.7