VisuBox

VisuBox — Defines a bounding box.

Functions

Properties

guint boundary Read / Write
ToolVector * expansion Read / Write
guint hidding-scheme Read / Write
guint units Read / Write
gboolean use-expansion Read / Write

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── ToolDbgObj
        ╰── VisuBox

Implemented Interfaces

VisuBox implements VisuNodeMasker and VisuBoxed.

Description

Functions

visu_box_new ()

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

A VisuBox object store the definition of a cell.

Parameters

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 stores the definition of a cell. This may fail, if full does not define a 3D basis set (the three vectors are not linearly independant). To check this, use visu_box_getGeometry() to test if the first vector is G_MAXFLOAT.

Parameters

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

Parameters

box

a VisuBox object.

 

cell

.

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

full

.

[in][array fixed-size=3]

Since: 3.7


visu_box_convertXYZtoBoxCoordinates ()

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

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

[skip]

Parameters

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_convertXYZToReduced ()

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

Use this method to transform cartesian into box coordinates.

Parameters

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_convertBoxCoordinatestoXYZ ()

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

Use this method to transform box coordinates into cartesian.

[skip]

Parameters

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_convertReducedToXYZ ()

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

Use this method to transform box coordinates into cartesian.

Parameters

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

Parameters

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

[skip]

Parameters

box

a VisuBox object ;

 

matrix

an area to store the matrix.

 

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.

[skip]

Parameters

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

Parameters

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

Parameters

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_getExtension ()

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

Using visu_box_setExtension(), 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.

Parameters

boxObj

a VisuBox object ;

 

extension

an allocated array to store the values.

[out][array fixed-size=3]

Since: 3.7


visu_box_getBoundary ()

VisuBoxBoundaries
visu_box_getBoundary (VisuBox *box);

Get the boundary conditions defined for box .

Parameters

box

a VisuBox object.

 

Returns

a VisuBoxBoundaries flag.

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.

Parameters

box

a VisuBox object.

 

per

a location to store three periodicties.

[out caller-allocates][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.

Parameters

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_getCentre ()

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

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

Parameters

box

a VisuBox object ;

 

centre

coordinates of the centre.

[out][array fixed-size=3]

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.

Parameters

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_getUnit ()

ToolUnits
visu_box_getUnit (VisuBox *box);

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

Parameters

box

a VisuBox object.

 

Returns

the ToolUnits of box or TOOL_UNITS_UNDEFINED.

Since: 3.7


visu_box_getInside ()

gboolean
visu_box_getInside (VisuBox *box,
                    float vect[3],
                    float ratio);

Update vect , taking into consideration the particular periodicity of box , for vect expressed in reduced coordinates to be within [-ratio;ratio].

Parameters

box

a VisuBox object.

 

vect

some cartesian coordinates.

[array fixed-size=3][inout]

ratio

a ratio in [0;1].

 

Returns

TRUE if vect is actually changed.

Since: 3.8


visu_box_getPeriodicVector ()

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

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

[skip]

Parameters

box

a VisuBox object.

 

vect

a vector.

[inout][array fixed-size=3]

Returns

TRUE if vect has been modified.

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.

Parameters

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_getPeriodicArray ()

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

Used for bindings.

Parameters

box

a VisuBox object.

 

array

an array of nEle * 3 floats.

[type gint64]

nEle

number of elements in array

 

Since: 3.7


visu_box_getExtensionActive ()

gboolean
visu_box_getExtensionActive (VisuBox *box);

Retrieve if extensions are applied or not.

Parameters

box

a VisuBox object.

 

Returns

TRUE if extensions are applied.

Since: 3.8


visu_box_getHiddingStatus ()

VisuBoxHiddingStatus
visu_box_getHiddingStatus (const VisuBox *box);

Retrieves the masking status of box .

Parameters

box

a VisuBox object.

 

Returns

the current masking status.

Since: 3.8


visu_box_setExtensionActive ()

gboolean
visu_box_setExtensionActive (VisuBox *box,
                             gboolean status);

Change if extension values are used not not.

Parameters

box

a VisuBox object.

 

status

a boolean.

 

Returns

TRUE if status has changed.

Since: 3.8


visu_box_setBoundary ()

gboolean
visu_box_setBoundary (VisuBox *box,
                      VisuBoxBoundaries bc);

Set up the boundary conditions of box .

Parameters

box

a VisuBox object.

 

bc

a boundary condition.

 

Returns

TRUE if the boundary conditions of box are 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.

Parameters

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.

Parameters

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 .

Parameters

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_setExtension ()

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

Change the duplication of the box in the three directions.

Parameters

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

Parameters

box

a VisuBox object.

 

unit

a ToolUnits flag.

 

Returns

TRUE if the unit has been changed.

Since: 3.7


visu_box_setOrigin ()

gboolean
visu_box_setOrigin (VisuBox *box,
                    const float orig[3]);

Change the origin of box .

Parameters

box

a VisuBox orbject.

 

orig

the new origin.

[array fixed-size=3]

Returns

TRUE if origin is indeed changed.

Since: 3.8


visu_box_setHiddingStatus ()

gboolean
visu_box_setHiddingStatus (VisuBox *box,
                           VisuBoxHiddingStatus status);

Changes the masking status of box for status .

Parameters

box

a VisuBox object.

 

status

a status.

 

Returns

TRUE if the status is actually changed.

Since: 3.8

Types and Values

struct VisuBox

struct VisuBox;

Opaque structure to stores VisuBox object.


struct VisuBoxClass

struct VisuBoxClass {
  VisuObjectClass parent;
};

Class structure of VisuBox objects.

Members

VisuObjectClass parent;

private.

 

enum VisuBoxVector

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

Members

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


enum VisuBoxBoundaries

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

Members

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.

 

enum VisuBoxHiddingStatus

This describes the possibilty to use the box as a masking objects for nodes.

Members

VISU_BOX_HIDE_NONE

don't apply masking.

 

VISU_BOX_HIDE_OUTSIDE

hide nodes outside the box.

 

VISU_BOX_HIDE_INSIDE

hide nodes inside the box.

 

Since: 3.8


struct VisuBoxVertices

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

Structure used for bindings.

Members

float vertices[8][3];

.

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

Since: 3.7


struct VisuBoxCell

struct VisuBoxCell {
  double box[VISU_BOX_N_VECTORS];
};

Structure used for bindings.

Members

double box[VISU_BOX_N_VECTORS];

.

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

Since: 3.7

Property Details

The “boundary” property

  “boundary”                 guint

Boundary conditions.

Flags: Read / Write

Allowed values: <= 7

Default value: 7


The “expansion” property

  “expansion”                ToolVector *

Expanion on all axis.

Flags: Read / Write


The “hidding-scheme” property

  “hidding-scheme”           guint

hidding scheme used by the box.

Flags: Read / Write

Allowed values: <= 2

Default value: 0


The “units” property

  “units”                    guint

Units of dimensions.

Flags: Read / Write

Allowed values: <= 3

Default value: 0


The “use-expansion” property

  “use-expansion”            gboolean

Expanion is active or not.

Flags: Read / Write

Default value: FALSE

Signal Details

The “SizeChanged” signal

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

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

Parameters

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.

 

Flags: No Hooks

Since: 3.7


The “UnitChanged” signal

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

Gets emitted when the units are changed.

Parameters

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.

 

Flags: No Hooks

Since: 3.7