![]() |
![]() |
![]() |
V_Sim API - Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
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
);
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.
typedef enum { uniform, nonuniform } ScalarField_meshflag;
flag (comment) standing at the begining of a Scalar field file, that gives informations concerning the mesh.
struct ScalarField_struct;
Structure that stores informations and data of a scalar field.
typedef struct ScalarField_struct ScalarField;
Short name to address ScalarField_struct objects.
#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.
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.
|
the path to the filename the field should be read from. |
Returns : |
a newly created ScalarField object. Use scalarFieldFree() to
delete it.
|
void scalarFieldFree (ScalarField *field
);
Free the memory used by the given object.
|
a ScalarField object. |
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
.
|
the path to the file to be loaded ; |
|
a GList to store read field(s) ; |
|
a location on a error pointer ; |
|
a set of different options (can be NULL). |
Returns : |
TRUE if everything goes with no error. |
void scalarFieldGet_minMax (ScalarField *field
,double minmax[2]
);
Get the minimum and the maximum values of the given field
.
|
a ScalarField object ; |
|
two double values. |
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.
|
a ScalarField object ; |
|
array containing data to be copied ; |
|
a boolean. |
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.
|
a VisuData object ; |
|
a ScalarField object. |
void scalarFieldGet_box (ScalarField *field
,double box[6]
);
This method is used to get the definition of the bounding box.
|
a ScalarField object ; |
|
6 floating point locations. |
void scalarFieldSet_box (ScalarField *field
,double box[6]
);
This method is used to set the definition of the bounding box.
|
a ScalarField object ; |
|
6 floating point values. |
void scalarFieldSet_boxFull (ScalarField *field
,double box[3][3]
);
This method is used to set the definition of the bounding box.
|
a ScalarField object ; |
|
6 floating point values. |
void scalarFieldGet_gridSize (ScalarField *field
,int grid[3]
);
This method is used to get the division in x, y, and z directions.
|
a ScalarField object ; |
|
3 integer locations. |
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.
|
a ScalarField object ; |
|
3 integers. |
void scalarFieldSet_meshtype (ScalarField *field
,ScalarField_meshflag meshtype
);
Change the distribution of the vertex of the scalarfield between regular or custom.
|
a ScalarField object ; |
|
a ScalarField_meshflag object. |
ScalarField_meshflag scalarFieldGet_meshtype (ScalarField *field
);
The vertex may be distributed linearly along the different directions or customily distributed.
|
a ScalarField object ; to be added |
Returns : |
a ScalarField_meshflag (uniform or nonuniform). |
double* scalarFieldGet_meshx (ScalarField *field
);
The mesh along x is stored as an array in x increasing.
|
a ScalarField object. |
Returns : |
a pointer on the allocated meshx array (it should not be freed). |
double* scalarFieldGet_meshy (ScalarField *field
);
The mesh along y is stored as an array in y increasing.
|
a ScalarField object. |
Returns : |
a pointer on the allocated meshy array (it should not be freed). |
double* scalarFieldGet_meshz (ScalarField *field
);
The mesh along z is stored as an array in z increasing.
|
a ScalarField object. |
Returns : |
a pointer on the allocated meshz array (it should not be freed). |
double*** scalarFieldGet_data (ScalarField *field
);
The data are stored as a 3 indexes array in x, y annd z increasing.
|
a ScalarField object. |
Returns : |
a pointer on the allocated data array (it should not be freed). |
gchar* scalarFieldGet_filename (ScalarField *field
);
The data are read from a file.
|
a ScalarField object. |
Returns : |
a pointer on the filename (it should not be freed). |
gchar* scalarFieldGet_commentary (ScalarField *field
);
If the file format support a commentary, this is a good method to get it.
|
a ScalarField object. |
Returns : |
a pointer on the commentary (it should not be freed), can be NULL. |
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.
|
a ScalarField object ; |
|
an UTF-8 string to store as a commentary. |
gboolean scalarFieldGet_periodic (ScalarField *field
);
Get the periodicity status of the scalar field.
|
a ScalarField object. |
Returns : |
TRUE if the scalar field is 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.
|
a ScalarField object ; |
|
a boolean. |
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...
|
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.
|
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.
|
a ScalarField object ; |
|
a newly allocated option. |
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
.
|
a ScalarField object ; |
|
a point coordinate (in real space) ; |
|
a location to store the value ; |
|
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.
|
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
.
|
the filename (path) the field should be loaded from ; |
|
a GList to store read field(s) ; |
|
a location on a error pointer ; |
|
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. |
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).
|
the name of the method ; |
|
a ScalarFieldLoadMethod function ; |
|
a ToolFileFormat object ; |
|
a priority value (the lower value, the higher priority). |
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. |