![]() |
![]() |
![]() |
V_Sim API - Reference Manual | ![]() |
---|---|---|---|---|
#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], matrix_scaleflag scale, guint nIsoLines, float *rgb, float *inputMinMax); void scalarFieldAdd_option (ScalarField *field, Option *option); GList* scalarFieldGet_allLoadMethods (); GList* scalarFieldGet_allOptions (ScalarField *field); void scalarFieldGet_box (ScalarField *field, double 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, double 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, gboolean xyzOrder); void scalarFieldSet_periodic (ScalarField *field, gboolean periodic); void scalarFieldSet_meshtype (ScalarField *field, ScalarField_meshflag meshtype); void scalarFieldInit ();
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.
#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.
typedef struct ScalarField_struct ScalarField;
Short name to address ScalarField_struct objects.
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
.
|
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. |
typedef enum { uniform, nonuniform } ScalarField_meshflag;
flag (comment) standing at the begining of a Scalar field file, that gives informations concerning the mesh.
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. |
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).
|
the name of the method ; |
|
a ScalarFieldLoadMethod function ; |
|
a FileFormat object ; |
|
a priority value (the lower value, the higher priority). |
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
.
|
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 scalarFieldDraw_map (ScalarField *field, Plane *plane, Shade *shade, OpenGLView *view, float precision, float drawnMinMax[2], matrix_scaleflag scale, guint nIsoLines, float *rgb, float *inputMinMax);
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. If rgb
is NULL, then the colour inverse is used
instead. If inputMinMax
is given, the two values are used as the
boundaries for the scale.
|
a ScalarField object ; |
|
a Plane object ; |
|
a Shade object ; |
|
a OpenGLView object ; |
|
percentage of precision (100. is normal) ; |
|
store the min and max drawn value ; |
|
the transformation method ; |
|
the number of isolines to draw. |
|
a color, can be NULL ; |
|
two floats or NULL. |
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.
|
a ScalarField object ; |
|
a newly allocated option. |
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. |
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 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. |
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. |
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). |
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 scalarFieldGet_minMax (ScalarField *field, double minmax[2]);
Get the minimum and the maximum values of the given field
.
|
a ScalarField object ; |
|
two double values. |
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 scalarFieldGet_periodic (ScalarField *field);
Get the periodicity status of the scalar field.
|
a ScalarField object. |
Returns : |
TRUE if the scalar field is periodic. |
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_secondaryMin (ScalarField *field);
Get the second minimum value of the given field
.
|
a ScalarField object. |
Returns : |
the second minimum. |
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_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. |
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 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_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_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. |
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. |