## toolMatrix

toolMatrix — Defines basic handlings on matrix.

## Synopsis

    void                tool_matrix_productMatrix           (float matRes[3][3],
                                                             float matA[3][3],
                                                             float matB[3][3]);
    void                tool_matrix_productVector           (float vectRes[3],
                                                             float mat[3][3],
                                                             float vect[3]);
    gboolean            tool_matrix_invert                  (float inv[3][3],
                                                             float mat[3][3]);
    float               tool_matrix_determinant             (float mat[3][3]);
    gboolean            tool_matrix_reducePrimitiveVectors  (double reduced[6],
                                                             double full[3][3]);
    gboolean            tool_matrix_getRotationFromFull     (float rot[3][3],
                                                             double full[3][3],
                                                             double box[6]);
    gboolean            tool_matrix_constrainInBox          (float translat[3],
                                                             float xyz[3],
                                                             float extension[3],
                                                             double XYZToBox[3][3],
                                                             double boxToXYZ[3][3]);
    enum                ToolMatrixSphericalCoord;
    void                tool_matrix_cartesianToSpherical    (float *spherical,
                                                             float *cartesian);
    void                tool_matrix_sphericalToCartesian    (float *cartesian,
                                                             float *spherical);
    enum                ToolMatrixScalingFlag;
    double              (*tool_matrix_getScaledValue)       (double x,
                                                             double minmax[2]);
    double              tool_matrix_getScaledLinear         (double x,
                                                             double minmax[2]);
    double              tool_matrix_getScaledLog            (double x,
                                                             double minmax[2]);
    double              tool_matrix_getScaledZeroCentredLog (double x,
                                                             double minmax[2]);
    double              tool_matrix_getScaledLinearInv      (double x,
                                                             double minmax[2]);
    double              tool_matrix_getScaledLogInv         (double x,
                                                             double minmax[2]);
    double              tool_matrix_getScaledZeroCentredLogInv
                                                            (double x,
                                                             double minmax[2]);
    gboolean            matrixGet_inter2D                   (float *lambda,
                                                             float a[2],
                                                             float b[2],
                                                             float A[2],
                                                             float B[2]);
    gboolean            matrixGet_inter2DFromList           (float i[2],
                                                             float *lambda,
                                                             float a[2],
                                                             float b[2],
                                                             GList *set);
    void                initToolMatrix                      (void);

## Description

Some very basic linear algebra are redefined here. It also gives access to coordinates conversion, essentially between cartesian and spherical.

## Details

### tool_matrix_productMatrix ()

    void                tool_matrix_productMatrix           (float matRes[3][3],
                                                             float matA[3][3],
                                                             float matB[3][3]);

Compute the mathematical product between `matA` and `matB` and put the result matrix in `matRes`.

`matRes` : | an array of floating point values of size 3x3 ;
`matA` : | an array of floating point values of size 3x3 ;
`matB` : | an array of floating point values of size 3x3.

Since 3.2

### tool_matrix_productVector ()

    void                tool_matrix_productVector           (float vectRes[3],
                                                             float mat[3][3],
                                                             float vect[3]);

Compute the mathematical product between `matA` and `vect` and put the result vector in `vectRes`.

`vectRes` : | an array of floating point values of size 3 ;
`mat` : | an array of floating point values of size 3x3 ;
`vect` : | an array of floating point values of size 3.

Since 3.2

### tool_matrix_invert ()

    gboolean            tool_matrix_invert                  (float inv[3][3],
                                                             float mat[3][3]);

Calculate the inverse matrix of matrix `mat` and store it in `inv`.

`inv` : | a matrix (out values).
`mat` : | a matrix.
Returns : | FALSE if `mat` is singular.

Since 3.6

### tool_matrix_determinant ()

    float               tool_matrix_determinant             (float mat[3][3]);

Calculate the determinant of matrix `mat`.

`mat` : | a matrix.
Returns : | the determinant value.

Since 3.6

### tool_matrix_reducePrimitiveVectors ()

    gboolean            tool_matrix_reducePrimitiveVectors  (double reduced[6],
                                                             double full[3][3]);

This routine transforms the given matrix `full` into a reduced array used by V_Sim to store box definition.

`reduced` : | a storage for 6 floating point values ;. out caller-allocates. array fixed-size=6.
`full` : | a full 3x3 matrix to be transformed.. in. array fixed-size=9.
Returns : | FALSE if the given matrix is planar.

### tool_matrix_getRotationFromFull ()

    gboolean            tool_matrix_getRotationFromFull     (float rot[3][3],
                                                             double full[3][3],
                                                             double box[6]);

There is a rotation matrix to transform from full cartesian coordinates into reduced box cartesian coordinates.

`rot` : | a rotation matrix (out values).
`full` : | the description of basis set in full development.
`box` : | the description of basis set in align X axis.
Returns : | TRUE if `full` does not describe properly a 3D box.

Since 3.6

### tool_matrix_constrainInBox ()

    gboolean            tool_matrix_constrainInBox          (float translat[3],
                                                             float xyz[3],
                                                             float extension[3],
                                                             double XYZToBox[3][3],
                                                             double boxToXYZ[3][3]);

Given the box difintion as the transformation matrices `XYZToBox` and `boxToXYZ` and the initial `xyz` cartesian coordinates, it returns the translation `translat` to be applied to `xyz` to move the node into the box.

`translat` : | a translation in cartesian coordinates (out values).
`xyz` : | a set of cartesian coordinates.
`extension` : | the box expansion in the three directions.
`XYZToBox` : | the transformation matrix to go from cartesian to reduced coordinates.
`boxToXYZ` : | the reverse transformation matrix.
Returns : | TRUE if `translat` is not (0;0;0).

Since 3.6

### enum ToolMatrixSphericalCoord

    typedef enum
      {
        TOOL_MATRIX_SPHERICAL_MODULUS,
        TOOL_MATRIX_SPHERICAL_THETA,
        TOOL_MATRIX_SPHERICAL_PHI
      } ToolMatrixSphericalCoord;

This is used to access the ordering of the vectors with `tool_matrix_cartesianToSpherical()` or with `tool_matrix_sphericalToCartesian()`.

`TOOL_MATRIX_SPHERICAL_MODULUS` | the modulus of a spherical vector.
`TOOL_MATRIX_SPHERICAL_THETA` | the theta angle of a spherical vector.
`TOOL_MATRIX_SPHERICAL_PHI` | the phi angle of a spherical vector.

Since 3.6

### tool_matrix_cartesianToSpherical ()

    void                tool_matrix_cartesianToSpherical    (float *spherical,
                                                             float *cartesian);

A method to transform cartesian coordinates in spherical coordinates (radius, phi and theta).

`spherical` : | an allocated array of 3 floating point values to store the result ;
`cartesian` : | an allocated array of 3 floating point values to read the input.

Since 3.3

### tool_matrix_sphericalToCartesian ()

    void                tool_matrix_sphericalToCartesian    (float *cartesian,
                                                             float *spherical);

A method to transform spherical coordinates (radius, phi and theta) to cartesian coordinates.

`cartesian` : | an allocated array of 3 floating point values to store the result ;
`spherical` : | an allocated array of 3 floating point values to read the input.

Since 3.3

### enum ToolMatrixScalingFlag

    typedef enum
      {
        linear,
        logarithm,
        zeroCentredLog,
        n_scaleflag
      } ToolMatrixScalingFlag;

Flag used to specify the transformation for `scalarFieldDraw_map()` routine.

`linear` | a linear convertion from [min,max] to [0,1] ;
`logarithm` | a logarithmic transformation from [min,max] to [0,1], the formula is -(f(x) - f(m) / f(m) where f(x) = ln((x-xmin)/(xmax-xmin)) ;
`zeroCentredLog` | a logarithmic transformation for data that are zero centred, the formula is 0.5+s*(log(MAX*SEUIL)-log(max(abs(x),MAX*SEUIL)))/(2*log(SEUIL)) where s is the sign, max=max(xmax,-xmin) and seuil a parameter (1e-5).
`n_scaleflag` | number of available scale functions.

Since 3.4

### tool_matrix_getScaledValue ()

    double              (*tool_matrix_getScaledValue)       (double x,
                                                             double minmax[2]);

Transform `x` into [0;1] using the given `minmax` values.

`x` : | the initial value ;
`minmax` : | the boundaries for the `x` argument.
Returns : | a value into [0;1].

Since 3.4

### tool_matrix_getScaledLinear ()

    double              tool_matrix_getScaledLinear         (double x,
                                                             double minmax[2]);

Transform `x` into [0;1] with a linear scale.

`x` : | the initial value ;
`minmax` : | the boundaries for the `x` argument ;
Returns : | a value into [0;1].

Since 3.5

### tool_matrix_getScaledLog ()

    double              tool_matrix_getScaledLog            (double x,
                                                             double minmax[2]);

Transform `x` into [0;1] with a log scale.

`x` : | the initial value ;
`minmax` : | the boundaries for the `x` argument.
Returns : | a value into [0;1].

Since 3.5

### tool_matrix_getScaledZeroCentredLog ()

    double              tool_matrix_getScaledZeroCentredLog (double x,
                                                             double minmax[2]);

Transform `x` into [0;1] with a log scale with zero centred values.

`x` : | the initial value ;
`minmax` : | the boundaries for the `x` argument.
Returns : | a value into [0;1].

Since 3.5

### tool_matrix_getScaledLinearInv ()

    double              tool_matrix_getScaledLinearInv      (double x,
                                                             double minmax[2]);

Reverse function for `tool_matrix_getScaledLinear()`.

`x` : | the initial value ;
`minmax` : | the boundaries for the `x` argument.
Returns : | a value into [0;1].

Since 3.5

### tool_matrix_getScaledLogInv ()

    double              tool_matrix_getScaledLogInv         (double x,
                                                             double minmax[2]);

Reverse function for `tool_matrix_getScaledLog()`.

`x` : | the initial value ;
`minmax` : | the boundaries for the `x` argument.
Returns : | a value into [0;1].

Since 3.5

### tool_matrix_getScaledZeroCentredLogInv ()

    double              tool_matrix_getScaledZeroCentredLogInv
                                                            (double x,
                                                             double minmax[2]);

Reverse function for `tool_matrix_getScaledZeroCentredLog()`.

`x` : | the initial value ;
`minmax` : | the boundaries for the `x` argument.
Returns : | a value into [0;1].

Since 3.5

### matrixGet_inter2D ()

    gboolean            matrixGet_inter2D                   (float *lambda,
                                                             float a[2],
                                                             float b[2],
                                                             float A[2],
                                                             float B[2]);

Get the intersection coeeficient of lines [ab] and [AB].

`lambda` : | a location to store a float.
`a` : | a point.
`b` : | another point.
`A` : | a point.
`B` : | another point.
Returns : | TRUE if [ab] and [AB] have an intersection.

### matrixGet_inter2DFromList ()

    gboolean            matrixGet_inter2DFromList           (float i[2],
                                                             float *lambda,
                                                             float a[2],
                                                             float b[2],
                                                             GList *set);

Same as `matrixGet_inter2D()`, but from a list of points.

`i` : | a location to store a point.
`lambda` : | a location to store a float.
`a` : | a point.
`b` : | another point.
`set` : | a list of points.
Returns : | TRUE if an intersection exists.

### initToolMatrix ()

    void                initToolMatrix                      (void);