VisuScalarField

VisuScalarField — Gives capabilities to load a scalar field.

Functions

Properties

gboolean empty Read
gchar * label Read / Write / Construct Only

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── ToolDbgObj
        ╰── VisuScalarField
            ├── VisuScalarFieldBinaryOp
            ╰── VisuScalarFieldData

Implemented Interfaces

VisuScalarField implements VisuBoxed and VisuPointset.

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.

Functions

visu_scalar_field_new ()

VisuScalarField *
visu_scalar_field_new (const gchar *label);

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 label argument is copied.

Parameters

label

a label to identify the scalar field.

 

Returns

a newly created VisuScalarField object.

[transfer full]


visu_scalar_field_isEmpty ()

gboolean
visu_scalar_field_isEmpty (const VisuScalarField *field);

Since loading of scalar fields is asynchronous, this method can be used to inquire if field has been populated yet or not.

Parameters

field

a VisuScalarField object.

 

Returns

TRUE if field has not been populated yet.

Since: 3.8


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.

Parameters

field

a VisuScalarField object ;

 

comment

an UTF-8 string to store as a commentary.

 

visu_scalar_field_getGridSize ()

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

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

Parameters

field

a VisuScalarField object ;

 

grid

3 integer locations.

[out caller-allocates][type ToolGridSize]

visu_scalar_field_setGridSize ()

gboolean
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.

Parameters

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.

Parameters

field

a VisuScalarField object ;

 

meshtype

a VisuScalarFieldMeshFlags object.

 

visu_scalar_field_getMinMax ()

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

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

Parameters

field

a VisuScalarField object ;

 

minmax

two double values.

[array fixed-size=2]

visu_scalar_field_getMeshtype ()

VisuScalarFieldMeshFlags
visu_scalar_field_getMeshtype (const VisuScalarField *field);

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

Parameters

field

a VisuScalarField object ; to be added

 

Returns

a VisuScalarFieldMeshFlags (uniform or nonuniform).


visu_scalar_field_getMesh ()

double *
visu_scalar_field_getMesh (const VisuScalarField *field,
                           ToolXyzDir dir);

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

Parameters

field

a VisuScalarField object.

 

dir

a direction.

 

Returns

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


visu_scalar_field_setMesh ()

void
visu_scalar_field_setMesh (VisuScalarField *field,
                           const double *mesh,
                           ToolXyzDir dir);

Define the mesh in case of non regular one.

Parameters

field

a VisuScalarField object.

 

mesh

an array with the mesh description in one direction.

 

dir

a direction.

 

Since: 3.8


visu_scalar_field_getLabel ()

const gchar *
visu_scalar_field_getLabel (VisuScalarField *field);

The data are read from a file.

Parameters

field

a VisuScalarField object.

 

Returns

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


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.

Parameters

field

a VisuScalarField object.

 

Returns

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


visu_scalar_field_getMeshInside ()

void
visu_scalar_field_getMeshInside (const VisuScalarField *field,
                                 guint grid[3],
                                 int i,
                                 int j,
                                 int k);

Apply periodicity when required to convert a mesh coordinates (i,j,k) into a valid coordinate grid .

Parameters

field

a VisuScalarField object.

 

grid

a location to store the mesh coordinates.

[out][array fixed-size=3]

i

an integer.

 

j

an integer.

 

k

an integer.

 

Since: 3.8


visu_scalar_field_getCoordInside ()

gboolean
visu_scalar_field_getCoordInside (const VisuScalarField *field,
                                  guint grid[3],
                                  guint dgrid[3],
                                  gfloat factor[3],
                                  const gfloat xyz[3],
                                  const gfloat extension[3]);

From the coordinates xyz , compute the grid coordinate grid closest to xyz . Put also in dgrid the closest grid coordinate after xyz . On output, factor will contains three float in [0;1] defining where is xyz within the cube defined by grid and dgrid .

Parameters

field

a VisuScalarField object.

 

grid

a location to store grid coordinates.

[out][array fixed-size=3]

dgrid

a location to store grid coordinates.

[out][array fixed-size=3]

factor

a location to store factors in every directions.

[out][array fixed-size=3]

xyz

some cartesian coordinates.

[array fixed-size=3]

extension

extension to consider.

[array fixed-size=3]

Returns

TRUE if grid is valid.

Since: 3.8


visu_scalar_field_getAt ()

double
visu_scalar_field_getAt (const VisuScalarField *field,
                         int i,
                         int j,
                         int k);

Computes the scalarfield value at i , j and k .

Parameters

field

a VisuScalarField object.

 

i

an integer.

 

j

an integer.

 

k

an integer.

 

Returns

the value.

Since: 3.8


visu_scalar_field_getGradAt ()

double
visu_scalar_field_getGradAt (const VisuScalarField *field,
                             int i,
                             int j,
                             int k,
                             ToolXyzDir dir);

Computes the gradient along dir at i , j and k .

Parameters

field

a VisuScalarField object.

 

i

an integer.

 

j

an integer.

 

k

an integer.

 

dir

a direction.

 

Returns

the gradient value.

Since: 3.8


visu_scalar_field_getValue ()

gboolean
visu_scalar_field_getValue (const 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 .

Parameters

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_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.

Parameters

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...

Parameters

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*]

Types and Values

enum VisuScalarFieldMeshFlags

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

Members

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.

 

struct VisuScalarField

struct VisuScalarField;

An opaque structure for the scalar field.


struct VisuScalarFieldClass

struct VisuScalarFieldClass {
  VisuObjectClass parent;

  gboolean (*isEmpty)(const VisuScalarField *field);
  gboolean (*setGridSize)(VisuScalarField *field, const guint grid[3]);
  void (*getGridSize)(const VisuScalarField *field, guint grid[3]);
  double (*getAt)(const VisuScalarField *field, int i, int j, int k);
  gboolean (*getValue)(const VisuScalarField *field, float xyz[3],
                       double *value, float extension[3]);
  void (*getMinMax)(const VisuScalarField *field, double minmax[2]);
};

An opaque structure for the class.

Members

VisuObjectClass parent;

the parent class.

 

isEmpty ()

a method returning TRUE if the scalar field has no data yet.

 

setGridSize ()

a method to define the grid size.

 

getGridSize ()

a method returning the three grid dimensions.

 

getAt ()

a method to get the value on a grid point.

 

getValue ()

a method to get an interpolated value in space.

 

getMinMax ()

a method to get the minimum and maximum value reached by the scalar field.

 

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.

Property Details

The “empty” property

  “empty”                    gboolean

whether has data or not.

Flags: Read

Default value: TRUE


The “label” property

  “label”                    gchar *

description label.

Flags: Read / Write / Construct Only

Default value: ""

Signal Details

The “changed” signal

void
user_function (VisuScalarField *field,
               gpointer         user_data)

Gets emitted when the values stored in this field are changed.

Parameters

field

the object which received the signal ;

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks

Since: 3.8