VisuBox

VisuBox — Defines a bounding box.

Synopsis

struct              VisuBox;
enum                VisuBoxBoundaries;
struct              VisuBoxCell;
struct              VisuBoxClass;
enum                VisuBoxVector;
struct              VisuBoxVertices;
gboolean            visu_box_constrainInside            (VisuBox *box,
                                                         float translat[3],
                                                         float xyz[3],
                                                         gboolean withExt);
void                visu_box_convertBoxCoordinatestoXYZ (VisuBox *box,
                                                         float xyz[3],
                                                         float boxCoord[3]);
void                visu_box_convertFullToCell          (VisuBox *box,
                                                         float cell[3],
                                                         float full[3]);
void                visu_box_convertReducedToXYZ        (VisuBox *box,
                                                         GArray *red,
                                                         float *x,
                                                         float *y,
                                                         float *z);
void                visu_box_convertXYZToReduced        (VisuBox *box,
                                                         GArray *xyz,
                                                         float *u,
                                                         float *v,
                                                         float *w);
void                visu_box_convertXYZtoBoxCoordinates (VisuBox *box,
                                                         float boxCoord[3],
                                                         float xyz[3]);
VisuBoxBoundaries   visu_box_getBoundary                (VisuBox *box);
void                visu_box_getCellMatrix              (VisuBox *box,
                                                         double matrix[3][3]);
void                visu_box_getCellMatrixv             (VisuBox *box,
                                                         double *m11,
                                                         double *m12,
                                                         double *m13,
                                                         double *m21,
                                                         double *m22,
                                                         double *m23,
                                                         double *m31,
                                                         double *m32,
                                                         double *m33);
void                visu_box_getCentre                  (VisuBox *box,
                                                         float centre[3]);
void                visu_box_getExtension               (const VisuBox *boxObj,
                                                         float extension[3]);
double              visu_box_getGeometry                (VisuBox *box,
                                                         VisuBoxVector vector);
float               visu_box_getGlobalSize              (VisuBox *box,
                                                         gboolean withExt);
void                visu_box_getInvMatrix               (VisuBox *box,
                                                         double matrix[3][3]);
void                visu_box_getPeriodicArray           (VisuBox *box,
                                                         float *array,
                                                         guint nEle);
void                visu_box_getPeriodicVector          (VisuBox *box,
                                                         float vect[3]);
void                visu_box_getPeriodicVectorv         (VisuBox *box,
                                                         float *x,
                                                         float *y,
                                                         float *z,
                                                         float vect[3]);
void                visu_box_getPeriodicity             (VisuBox *box,
                                                         gboolean per[3]);
ToolUnits           visu_box_getUnit                    (VisuBox *box);
void                visu_box_getVertices                (VisuBox *box,
                                                         float v[8][3],
                                                         gboolean withExtension);
VisuBox *           visu_box_new                        (double geometry[VISU_BOX_N_VECTORS],
                                                         VisuBoxBoundaries bc);
VisuBox *           visu_box_new_full                   (double full[3][3],
                                                         VisuBoxBoundaries bc);
gboolean            visu_box_setBoundary                (VisuBox *box,
                                                         VisuBoxBoundaries bc);
gboolean            visu_box_setExtension               (VisuBox *boxObj,
                                                         float extension[3]);
gboolean            visu_box_setGeometry                (VisuBox *box,
                                                         double geometry[VISU_BOX_N_VECTORS]);
gboolean            visu_box_setGeometryFull            (VisuBox *box,
                                                         double full[3][3]);
gboolean            visu_box_setMargin                  (VisuBox *box,
                                                         gfloat margin,
                                                         gboolean emit);
gboolean            visu_box_setUnit                    (VisuBox *box,
                                                         ToolUnits unit);

Object Hierarchy

  GObject
   +----VisuBox

Implemented Interfaces

VisuBox implements VisuBoxed.

Signals

  "BoundaryChanged"                                : No Hooks
  "ExtensionChanged"                               : No Hooks
  "SizeChanged"                                    : No Hooks
  "UnitChanged"                                    : No Hooks

Description

Details

struct VisuBox

struct VisuBox;

Opaque structure to stores VisuBox object.


enum VisuBoxBoundaries

typedef enum {
    VISU_BOX_PERIODIC,
    VISU_BOX_SURFACE_XY,
    VISU_BOX_SURFACE_YZ,
    VISU_BOX_SURFACE_ZX,
    VISU_BOX_WIRE_X,
    VISU_BOX_WIRE_Y,
    VISU_BOX_WIRE_Z,
    VISU_BOX_FREE
} VisuBoxBoundaries;

This describes the periodicity of the bounding box in the three directions.

VISU_BOX_PERIODIC

the full 3D periodicity ;

VISU_BOX_SURFACE_XY

the Z axis is a free axis ;

VISU_BOX_SURFACE_YZ

the X axis is a free axis ;

VISU_BOX_SURFACE_ZX

the Y axis is a free axis ;

VISU_BOX_WIRE_X

the periodicity is along X axis only ;

VISU_BOX_WIRE_Y

the periodicity is along Y axis only ;

VISU_BOX_WIRE_Z

the periodicity is along Z axis only ;

VISU_BOX_FREE

the system is isolated.

struct VisuBoxCell

struct VisuBoxCell {
  double box[VISU_BOX_N_VECTORS];
};

Structure used for bindings.

double box[VISU_BOX_N_VECTORS];

. [array fixed-size=6][element-type gdouble]

Since 3.7


struct VisuBoxClass

struct VisuBoxClass {
  GObjectClass parent;
};

Class structure of VisuBox objects.

GObjectClass parent;

private.

enum VisuBoxVector

typedef enum {
    VISU_BOX_DXX,
    VISU_BOX_DYX,
    VISU_BOX_DYY,
    VISU_BOX_DZX,
    VISU_BOX_DZY,
    VISU_BOX_DZZ,
    VISU_BOX_N_VECTORS
} VisuBoxVector;

Identifier of every projection of the box super-cell on an orthogonal basis-set.

VISU_BOX_DXX

x box vector along X;

VISU_BOX_DYX

y box vector along X;

VISU_BOX_DYY

y box vector along Y;

VISU_BOX_DZX

z box vector along X;

VISU_BOX_DZY

z box vector along Y;

VISU_BOX_DZZ

z box vector along Z;

VISU_BOX_N_VECTORS

number of elements.

Since 3.7


struct VisuBoxVertices

struct VisuBoxVertices {
  float vertices[8][3];
};

Structure used for bindings.

float vertices[8][3];

. [array fixed-size=8][element-type ToolVector]

Since 3.7


visu_box_constrainInside ()

gboolean            visu_box_constrainInside            (VisuBox *box,
                                                         float translat[3],
                                                         float xyz[3],
                                                         gboolean withExt);

Given the box defintion box and the initial xyz cartesian coordinates, it returns the translation translat to be applied to xyz to move the node into the box.

box :

a VisuBox object.

translat :

a translation in cartesian coordinates (out values).

xyz :

a set of cartesian coordinates.

withExt :

TRUE to take into account the box expansions.

Returns :

TRUE if translat is not (0;0;0).

Since 3.7


visu_box_convertBoxCoordinatestoXYZ ()

void                visu_box_convertBoxCoordinatestoXYZ (VisuBox *box,
                                                         float xyz[3],
                                                         float boxCoord[3]);

Use this method to transform box coordinates into cartesian.

box :

a VisuBox object ;

xyz :

an array of floating point values to store the result ;

boxCoord :

an array of floating point values that describes the box coordinates.

Since 3.7


visu_box_convertFullToCell ()

void                visu_box_convertFullToCell          (VisuBox *box,
                                                         float cell[3],
                                                         float full[3]);

Convert given cartesian coordinates of a full matrix definition (see visu_box_setGeometryFull()) to cartesian coordinates in the cell definition used by V_Sim. It corresponds to two applied rotations.

box :

a VisuBox object.

cell :

. [out caller-allocates][array fixed-size=3]

full :

. [in][array fixed-size=3]

Since 3.7


visu_box_convertReducedToXYZ ()

void                visu_box_convertReducedToXYZ        (VisuBox *box,
                                                         GArray *red,
                                                         float *x,
                                                         float *y,
                                                         float *z);

Use this method to transform box coordinates into cartesian.

box :

a VisuBox object ;

red :

floating point values that describes the cartesian coordinates. [in][array fixed-size=3][element-type gfloat]

x :

the x coordinate. [out caller-allocates]

y :

the y coordinate. [out caller-allocates]

z :

the z coordinate. [out caller-allocates]

Since 3.7


visu_box_convertXYZToReduced ()

void                visu_box_convertXYZToReduced        (VisuBox *box,
                                                         GArray *xyz,
                                                         float *u,
                                                         float *v,
                                                         float *w);

Use this method to transform cartesian into box coordinates.

box :

a VisuBox object ;

xyz :

floating point values that describes the cartesian coordinates. [in][array fixed-size=3][element-type gfloat]

u :

the x coordinate. [out caller-allocates]

v :

the y coordinate. [out caller-allocates]

w :

the z coordinate. [out caller-allocates]

Since 3.7


visu_box_convertXYZtoBoxCoordinates ()

void                visu_box_convertXYZtoBoxCoordinates (VisuBox *box,
                                                         float boxCoord[3],
                                                         float xyz[3]);

Use this method to transform cartesian coordinates to the box coordinates.

box :

a VisuBox object ;

boxCoord :

an array of floating point values to store the result ;

xyz :

an array of floating point values describing coordinates in cartesian.

Since 3.7


visu_box_getBoundary ()

VisuBoxBoundaries   visu_box_getBoundary                (VisuBox *box);

Get the boundary conditions defined for box.

box :

a VisuBox object.

Returns :

a VisuBoxBoundaries flag.

Since 3.7


visu_box_getCellMatrix ()

void                visu_box_getCellMatrix              (VisuBox *box,
                                                         double matrix[3][3]);

This method is used when the box matrix is required. This matrix can transform a vector given in box coordinates into a cartesian vector. If a simple vector multication is required, then the use of visu_box_convertBoxCoordinatestoXYZ() should be prefered.

box :

a VisuBox object ;

matrix :

an area to store the matrix.

Since 3.7


visu_box_getCellMatrixv ()

void                visu_box_getCellMatrixv             (VisuBox *box,
                                                         double *m11,
                                                         double *m12,
                                                         double *m13,
                                                         double *m21,
                                                         double *m22,
                                                         double *m23,
                                                         double *m31,
                                                         double *m32,
                                                         double *m33);

This method is a binding method for visu_box_getCellMatrix().

Rename to: visu_box_getCellMatrix

box :

a VisuBox object ;

m11 :

an area to store the matrix. [out]

m12 :

an area to store the matrix. [out]

m13 :

an area to store the matrix. [out]

m21 :

an area to store the matrix. [out]

m22 :

an area to store the matrix. [out]

m23 :

an area to store the matrix. [out]

m31 :

an area to store the matrix. [out]

m32 :

an area to store the matrix. [out]

m33 :

an area to store the matrix. [out]

Since 3.7


visu_box_getCentre ()

void                visu_box_getCentre                  (VisuBox *box,
                                                         float centre[3]);

centre contains on output the cartesian coordinates of the centre of the bounding box.

box :

a VisuBox object ;

centre :

coordinates of the centre. [out][array fixed-size=3]

Since 3.7


visu_box_getExtension ()

void                visu_box_getExtension               (const VisuBox *boxObj,
                                                         float extension[3]);

Using visu_data_replicate(), it is possible to duplicate the primitive box in each directions. Use this method to know the current extension. Returned values are positive floating point values. An extension of 0. means that only the primitive box exists, while a value of one means a duplication of one box in each direction of the coordinate.

boxObj :

a VisuBox object ;

extension :

an allocated array to store the values. [out][array fixed-size=3]

Since 3.7


visu_box_getGeometry ()

double              visu_box_getGeometry                (VisuBox *box,
                                                         VisuBoxVector vector);

Retrieve the value of a vector defining the bounding box. The vector is chosen with an int, see the VisuBoxVector enum for more details.

box :

a VisuBox object ;

vector :

an int corresponding to a vector of the box.

Returns :

the value of the required vector (always a positive value for vector = 0, 2 or 5 !), or G_MAXFLOAT if the box has not been initialised.

Since 3.7


visu_box_getGlobalSize ()

float               visu_box_getGlobalSize              (VisuBox *box,
                                                         gboolean withExt);

The box has a whole size that contains it (including margin, see visu_box_setMargin()), this size can be retrieve taking into account the extension of the box, or not.

box :

a VisuBox object.

withExt :

a boolean.

Returns :

G_MAXFLOAT on failure, otherwise a length for the biggest diagonal distance of the box, with or without extension.

Since 3.7


visu_box_getInvMatrix ()

void                visu_box_getInvMatrix               (VisuBox *box,
                                                         double matrix[3][3]);

This method is used when the inverse box matrix is required. This matrix can transform a vector given in cartesian coordinates into a box vector. If a simple vector multication is required, then the use of visu_box_convertXYZtoBoxCoordinates() should be prefered.

box :

a VisuBox object ;

matrix :

an area to store the matrix.

Since 3.7


visu_box_getPeriodicArray ()

void                visu_box_getPeriodicArray           (VisuBox *box,
                                                         float *array,
                                                         guint nEle);

Used for bindings.

box :

a VisuBox object.

array :

an array of nEle * 3 floats. [type gint64]

nEle :

number of elements in array

Since 3.7


visu_box_getPeriodicVector ()

void                visu_box_getPeriodicVector          (VisuBox *box,
                                                         float vect[3]);

Modify vect to get the shortest equivalent vector, taking into account the periodicity.

box :

a VisuBox object.

vect :

a vector. [inout][array fixed-size=3]

Since 3.7


visu_box_getPeriodicVectorv ()

void                visu_box_getPeriodicVectorv         (VisuBox *box,
                                                         float *x,
                                                         float *y,
                                                         float *z,
                                                         float vect[3]);

Equivalent of visu_box_getPeriodicVector() used for bindings.

Rename to: visu_box_getPeriodicVector

box :

a VisuBox object.

x :

the new x part. [out]

y :

the new y part. [out]

z :

the new z part. [out]

vect :

a vector. [array fixed-size=3]

Since 3.7


visu_box_getPeriodicity ()

void                visu_box_getPeriodicity             (VisuBox *box,
                                                         gboolean per[3]);

Get for each {x, y, z} directions if the box is periodic.

box :

a VisuBox object.

per :

a location to store three periodicties. [out caller-allocates][array fixed-size=3]

Since 3.7


visu_box_getUnit ()

ToolUnits           visu_box_getUnit                    (VisuBox *box);

The lengths of box may be given in a certain unit using visu_box_setUnit().

box :

a VisuBox object.

Returns :

the ToolUnits of box or TOOL_UNITS_UNDEFINED.

Since 3.7


visu_box_getVertices ()

void                visu_box_getVertices                (VisuBox *box,
                                                         float v[8][3],
                                                         gboolean withExtension);

All nodes are rendered inside a bounding box, this method can be used to retrieve it. This box is not the drawn box but the box containing all the nodes, included possible extension. To get the box itself, use visu_box_getCellMatrix() instead. One can also get the vertices of the box itself using FALSE as withExtension argument.

box :

a VisuBox object.

v :

the position of the eight vertices of the bounding box. [out caller-allocates][type VisuBoxVertices*]

withExtension :

a boolean.

visu_box_new ()

VisuBox *           visu_box_new                        (double geometry[VISU_BOX_N_VECTORS],
                                                         VisuBoxBoundaries bc);

A VisuBox object store the definition of a cell.

geometry :

a cell definition. [array fixed-size=6]

bc :

a boundary condition.

Returns :

create a new VisuBox object. [transfer full]

Since 3.7


visu_box_new_full ()

VisuBox *           visu_box_new_full                   (double full[3][3],
                                                         VisuBoxBoundaries bc);

A VisuBox object store the definition of a cell.

full :

a cell definition (full matrix). [array fixed-size=9]

bc :

a boundary condition.

Returns :

create a new VisuBox object. [transfer full]

Since 3.7


visu_box_setBoundary ()

gboolean            visu_box_setBoundary                (VisuBox *box,
                                                         VisuBoxBoundaries bc);

Set up the boundary conditions of box.

box :

a VisuBox object.

bc :

a boundary condition.

Returns :

TRUE if the boundary conditions of box are changed.

Since 3.7


visu_box_setExtension ()

gboolean            visu_box_setExtension               (VisuBox *boxObj,
                                                         float extension[3]);

Using visu_data_replicate(), it is possible to duplicate the primitive box in each directions. Use this method to know the current extension. Returned values are positive floating point values. An extension of 0. means that only the primitive box exists, while a value of one means a duplication of one box in each direction of the coordinate.

boxObj :

a VisuBox object ;

extension :

an allocated array to store the values. [in][array fixed-size=3]

Returns :

TRUE if the extension of box is actually changed.

Since 3.7


visu_box_setGeometry ()

gboolean            visu_box_setGeometry                (VisuBox *box,
                                                         double geometry[VISU_BOX_N_VECTORS]);

This methods set the size of the box.

box :

a VisuBox object ;

geometry :

a 6 floating point array ;. [in][array fixed-size=6]

Returns :

TRUE if the geometry is indeed changed.

Since 3.7


visu_box_setGeometryFull ()

gboolean            visu_box_setGeometryFull            (VisuBox *box,
                                                         double full[3][3]);

As visu_box_setGeometry(), but using a full matrix.

box :

a VisuBox object.

full :

a matrix defining a basis-set.

Returns :

TRUE if the geometry is valid and changed.

Since 3.7


visu_box_setMargin ()

gboolean            visu_box_setMargin                  (VisuBox *box,
                                                         gfloat margin,
                                                         gboolean emit);

This routine add some margin to defined the OpenGL rendering zone of box.

box :

a VisuBox object.

margin :

a float value.

emit :

TRUE to emit "SizeChanged" signal.

Returns :

TRUE if the margin is actually changed.

Since 3.7


visu_box_setUnit ()

gboolean            visu_box_setUnit                    (VisuBox *box,
                                                         ToolUnits unit);

The lengths of box may be given in a certain unit by calling this routine. If the unit is different from the previously defined, the coordinate are scaled accordingly.

box :

a VisuBox object.

unit :

a ToolUnits flag.

Returns :

TRUE if the unit has been changed.

Since 3.7

Signal Details

The "BoundaryChanged" signal

void                user_function                      (VisuBox *box,
                                                        gpointer user_data)      : No Hooks

Gets emitted when the boundary conditions are changed.

box :

the object which received the signal ;

user_data :

user data set when the signal handler was connected.

Since 3.7


The "ExtensionChanged" signal

void                user_function                      (VisuBox *box,
                                                        gpointer user_data)      : No Hooks

Gets emitted when the extension of the box is changed. The new size of the box is not yet computed, listen to VisuBox::SizeChanged instead.

box :

the object which received the signal ;

user_data :

user data set when the signal handler was connected.

Since 3.7


The "SizeChanged" signal

void                user_function                      (VisuBox *box,
                                                        gfloat   extens,
                                                        gpointer user_data)      : No Hooks

Gets emitted when the box size is changed (because of box duplication for instance).

box :

the object which received the signal ;

extens :

the new longuest distance in the box taking into account the extension.

user_data :

user data set when the signal handler was connected.

Since 3.7


The "UnitChanged" signal

void                user_function                      (VisuBox *box,
                                                        gfloat   factor,
                                                        gpointer user_data)      : No Hooks

Gets emitted when the units are changed.

box :

the object which received the signal ;

factor :

the factor that has been applied.

user_data :

user data set when the signal handler was connected.

Since 3.7