![]() |
![]() |
![]() |
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); 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]); void scalarFieldAdd_option (ScalarField *field, Option *option); GList* scalarFieldGet_allLoadMethods (); GList* scalarFieldGet_allOptions (ScalarField *field); void scalarFieldGet_box (ScalarField *field, float 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); void scalarFieldSet_box (ScalarField *field, float 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); 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
.
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. |
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.
|
void scalarFieldFree (ScalarField *field);
Free the memory used by the given object.
field : |
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).
name : |
the name of the method ; |
method : |
a ScalarFieldLoadMethod function ; |
format : |
a FileFormat object ; |
priority : |
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
.
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. |
void scalarFieldDraw_map (ScalarField *field, Plane *plane, Shade *shade, OpenGLView *view, float precision, float drawnMinMax[2]);
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.
field : |
a ScalarField object ; |
plane : |
a Plane object ; |
shade : |
a Shade object ; |
view : |
a OpenGLView object ; |
precision : |
percentage of precision (100 is normal) ; |
drawnMinMax : |
store the min and max drawn value. |
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.
field : |
a ScalarField object ; |
option : |
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...
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.
|
void scalarFieldGet_box (ScalarField *field, float box[6]);
This method is used to get the definition of the bounding box.
field : |
a ScalarField object ; |
box : |
6 floating point locations. |
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. |
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). |
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). |
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. |
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. |
gboolean scalarFieldGet_value (ScalarField *field, float xyz[3], double *value);
Knowing the point coordinates, it interpolate a value from the scalar field.
field : |
a ScalarField object ; |
xyz : |
a point coordinate (in real space) ; |
value : |
a location to store the value. |
Returns : | TRUE if the value can be interpolate, FALSE otherwise, for instance,
when the point xyz is out of bounds.
|
void scalarFieldSet_box (ScalarField *field, float box[6]);
This method is used to set the definition of the bounding box.
field : |
a ScalarField object ; |
box : |
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.
field : |
a ScalarField object ; |
comment : |
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.
data : |
a VisuData object ; |
field : |
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.
field : |
a ScalarField object ; |
grid : |
3 integers. |
void scalarFieldSet_data (ScalarField *field, double *data);
Set the data of the given field
. The array data
should be stored in z direction
first, followed by y and x. 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. |