From aed7ab03677a40432aec7bbc2e3fa671d00c42cb Mon Sep 17 00:00:00 2001 From: marioalexis Date: Mon, 30 May 2022 16:57:42 -0300 Subject: [PATCH] Base: Improve docstrings in MatrixPy.xml --- src/Base/MatrixPy.xml | 242 ++++++++++++++++++++++++------------------ 1 file changed, 138 insertions(+), 104 deletions(-) diff --git a/src/Base/MatrixPy.xml b/src/Base/MatrixPy.xml index ea6d965794..843a33e71d 100644 --- a/src/Base/MatrixPy.xml +++ b/src/Base/MatrixPy.xml @@ -16,303 +16,337 @@ This is the Matrix export class - A 4x4 Matrix + Base.Matrix class.\n +A 4x4 Matrix. +In particular, this matrix can represent an affine transformation, that is, given a +3D vector `x`, apply the transformation y = M*x + b, where the matrix `M` is a linear +map and the vector `b` is a translation. +`y` can be obtained using a linear transformation represented by the 4x4 matrix `A` +conformed by the augmented 3x4 matrix (M|b), augmented by row with (0,0,0,1), therefore: +(y, 1) = A*(x, 1).\n +The following constructors are supported:\n +Matrix() +Empty constructor.\n +Matrix(matrix) +Copy constructor. +matrix : Base.Matrix.\n +Matrix(*coef) +Define from 16 coefficients of the 4x4 matrix. +coef : sequence of float\n The sequence can have up to 16 elements which complete the matrix by rows.\n +Matrix(vector1, vector2, vector3, vector4) +Define from four 3D vectors which represent the columns of the 3x4 submatrix, useful +to represent an affine transformation. The fourth row is made up by (0,0,0,1). +vector1 : Base.Vector +vector2 : Base.Vector +vector3 : Base.Vector +vector4 : Base.Vector\n Default to (0,0,0). Optional. - -move(Vector) -Move the matrix along the vector - + move(vector) -> None +move(x, y, z) -> None\n +Move the matrix along a vector, equivalent to left multiply the matrix +by a pure translation transformation.\n +vector : Base.Vector, tuple +x : float\n `x` translation. +y : float\n `y` translation. +z : float\n `z` translation. - -scale(Vector) -Scale the matrix with the vector - + scale(vector) -> None +scale(x, y, z) -> None +scale(factor) -> None\n +Scale the first three rows of the matrix.\n +vector : Base.Vector +x : float\n First row factor scale. +y : float\n Second row factor scale. +z : float\n Third row factor scale. +factor : float\n global factor scale. - -hasScale(tol=0.0) + hasScale(tol=0) -> ScaleType\n Return an enum value of ScaleType. Possible values are: Uniform, NonUniformLeft, NonUniformRight, NoScaling or Other -if it's not a scale matrix - +if it's not a scale matrix.\n +tol : float - nullify() - make this the null matrix + nullify() -> None\n +Make this the null matrix. - isNull() - check if this is the null matrix + isNull() -> bool\n +Check if this is the null matrix. - unity() - make this matrix to unity + unity() -> None\n +Make this matrix to unity (4D identity matrix). - isUnity() - check if this is the unit matrix + isUnity() -> bool\n +Check if this is the unit matrix (4D identity matrix). - transform(Vector,Matrix) - return the dot product of the two vectors + transform(vector, matrix2) -> None\n +Transform the matrix around a given point. +Equivalent to left multiply the matrix by T*M*T_inv, where M is `matrix2`, T the +translation generated by `vector` and T_inv the inverse translation. +For example, if `matrix2` is a rotation, the result is the transformation generated +by the current matrix followed by a rotation around the point represented by `vector`.\n +vector : Base.Vector +matrix2 : Base.Matrix - -col(index) -Return the vector of a column - + col(index) -> Base.Vector\n +Return the vector of a column, that is, the vector generated by the three +first elements of the specified column. +index : int\n Required column index. - -setCol(index, Vector) -Set the vector of a column - + setCol(index, vector) -> None\n +Set the vector of a column, that is, the three first elements of the specified +column by index.\n +index : int\n Required column index. +vector : Base.Vector - -row(index) -Return the vector of a row - + row(index) -> Base.Vector\n +Return the vector of a row, that is, the vector generated by the three +first elements of the specified row.\n +index : int\n Required row index. - -setRow(index, Vector) -Set the vector of a row - + setRow(index, vector) -> None\n +Set the vector of a row, that is, the three first elements of the specified +row by index.\n +index : int\n Required row index. +vector : Base.Vector - -trace() -Return the trace of the 3x3 sub-matrix as vector - + trace() -> Base.Vector\n +Return the diagonal of the 3x3 leading principal submatrix as vector. - -setTrace(Vector) -Set the trace of the 3x3 sub-matrix - + setTrace(vector) -> None\n +Set the diagonal of the 3x3 leading principal submatrix.\n +vector : Base.Vector - rotateX(float) - rotate around X + rotateX(angle) -> None\n +Rotate around X axis. +angle : float\n Angle in radians. - rotateY(float) - rotate around Y + rotateY(angle) -> None\n +Rotate around Y axis. +angle : float\n Angle in radians. - rotateZ(float) - rotate around Z + rotateZ(angle) -> None\n +Rotate around Z axis. +angle : float\n Angle in radians. - -multiply(Matrix|Vector) -Multiply a matrix or vector with this matrix - + multiply(matrix) -> Base.Matrix +multiply(vector) -> Base.Vector\n +Right multiply the matrix by the given object. +If the argument is a vector, this is augmented to the 4D vector (`vector`, 1).\n +matrix : Base.Matrix +vector : Base.Vector - -multVec(Vector) -> Vector -Compute the transformed vector using the matrix - + multVec(vector) -> Base.Vector\n +Compute the transformed vector using the matrix. +vector : Base.Vector - -invert() -> None -Compute the inverse matrix, if possible - + invert() -> None\n +Compute the inverse matrix in-place, if possible. - - -inverse() -> Matrix -Compute the inverse matrix, if possible - + inverse() -> Base.Matrix\n +Compute the inverse matrix, if possible. - -transpose() -> None -Transpose the matrix. - + transpose() -> None\n +Transpose the matrix in-place. - -transposed() -> Matrix -Returns a transposed copy of this matrix. - + transposed() -> Base.Matrix\n +Returns a transposed copy of this matrix. - -determinant() -> Float -Compute the determinant of the matrix - + determinant() -> float\n +Compute the determinant of the matrix. - -isOrthogonal([Float]) -> Float + isOrthogonal(tol=1e-6) -> float\n Checks if the matrix is orthogonal, i.e. M * M^T = k*I and returns -the multiple of the identity matrix. If it's not orthogonal 0 is returned. -As argument you can set a tolerance which by default is 1.0e-6. - +the multiple of the identity matrix. If it's not orthogonal 0 is returned.\n +tol : float\n Tolerance used to check orthogonality. - -submatrix(int) -> Matrix -Get the sub-matrix. The parameter must be in the range [1,4]. - + submatrix(dim) -> Base.Matrix\n +Get the leading principal submatrix of the given dimension. +The (4 - `dim`) remaining dimensions are completed with the +corresponding identity matrix.\n +dim : int\n Dimension parameter must be in the range [1,4]. - -analyze() -> string -Analyzes the type of transformation. - + analyze() -> str\n +Analyzes the type of transformation. - The matrix elements + The (1,1) matrix element. - The matrix elements + The (1,2) matrix element. - The matrix elements + The (1,3) matrix element. - The matrix elements + The (1,4) matrix element. - The matrix elements + The (2,1) matrix element. - The matrix elements + The (2,2) matrix element. - The matrix elements + The (2,3) matrix element. - The matrix elements + The (2,4) matrix element. - The matrix elements + The (3,1) matrix element. - The matrix elements + The (3,2) matrix element. - The matrix elements + The (3,3) matrix element. - The matrix elements + The (3,4) matrix element. - The matrix elements + The (4,1) matrix element. - The matrix elements + The (4,2) matrix element. - The matrix elements + The (4,3) matrix element. - The matrix elements + The (4,4) matrix element. - The matrix elements + The matrix elements.