Geometry
The classes below provide an framework to manipulate geometric data such as points, tangent vectors, isometries, etc. All the core files are geometry independent. In particular, various methods need be overwritten for each geometry.
Remark.
For these classes, the constructor should a priori be different for each geometry.
In practice it often delegates the task to a build method — see Isometry.build()
— that can be overwritten easily unlike the constructor.
Another way to do would have been to implement for each geometry a new child class.
However it would produce a problem of simultaneous inheritance — see for instance the Position()
class whose methods may return an Isometry()
.
- class Isometry()
Isometry of the geometry.
- Isometry.Isometry
- Isometry.isIsometry
- Isometry.build()
Fake constructor If no argument is passed, should return the identity.
- Isometry.clone()
Return a new copy of the current isometry.
- Returns:
Isometry – The clone of the current isometry
- Isometry.copy(isom)
Set the current isometry with the given isometry
- Arguments:
isom (Isometry) – the isometry to copy
- Returns:
Isometry – The current isometry
- Isometry.diffExpMap(m)
Take as input a Matrix4 m, seen as an isometry of the tangent space at the origin (in the reference frame) and set the current isometry so that its differential is dexp * dm, where - dexp is the differential of the exponential map - dm is the differential of m
- Arguments:
m (Matrix4) – an isometry of the tangent space
- Returns:
Isometry – The current isometry
- Isometry.equals(isom)
Check if the current isometry and isom are the same. Mainly for debugging purposes.
- Arguments:
isom (Isometry) –
- Returns:
boolean – true if the isometries are equal, false otherwise
- Isometry.identity()
Set the current isometry to the identity.
- Returns:
Isometry – The current isometry
- Isometry.invert()
Set the current isometry to its inverse
- Returns:
Isometry – The current isometry
- Isometry.makeInvTranslation(point)
Set the current isometry to a preferred one sending the given point to the origin (typically in Nil, Sol, SL2, etc). The returned isometry should be the inverse of the one generated by makeTranslation.
- Arguments:
point (Point) – the point that is moved back to the origin
- Returns:
Isometry – The current isometry
- Isometry.makeTranslation(point)
Set the current isometry to a preferred one sending the origin to the given point (typically in Nil, Sol, SL2, etc).
- Arguments:
point (Point) – the target point
- Returns:
Isometry – The current isometry
- Isometry.makeTranslationFromDir(vec)
Set the current isometry to a preferred one sending the origin to the image of v by the exponential map.
- Arguments:
vec (Vector) – the vector in the tangent space
- Returns:
Isometry – The current isometry
- Isometry.multiply(isom)
Multiply the current isometry by isom on the left, i.e. replace this by this * isom.
- Arguments:
isom (Isometry) –
- Returns:
Isometry – The current isometry
- Isometry.premultiply(isom)
Multiply the current isometry by isom on the right, i.e. replace this by isom * this.
- Arguments:
isom (Isometry) –
- Returns:
Isometry – The current isometry
- Isometry.reduceError()
Reduce the eventual numerical errors of the current isometry (e.g. Gram-Schmidt for orthogonal matrices).
- Returns:
Isometry – The current isometry
- class Point()
Point in the geometry.
Constructor. Same remark as for Isometry.
- Point.Point
Constructor. Same remark as for Isometry.
- Point.isPoint
True if the object implements the class Point
- Point.applyIsometry(isom)
Translate the current point by the given isometry.
- Arguments:
isom (Isometry) – the isometry to apply
- Returns:
Point – The current point
- Point.build()
Fake constructor. If no argument is passed, return the origin of the space.
- Point.clone()
Return a new copy of the current point.
- Returns:
Point – the clone of the current point
- Point.copy(point)
Set the current point with the given point
- Arguments:
point (Point) – the point to copy
- Returns:
Point – The current point
- Point.equals(point)
Check if the current point and `point ` are the same. Mainly for debugging purposes.
- Arguments:
point (Point) –
- Returns:
boolean – true if the points are equal, false otherwise
- Point.reduceError()
Reduce possible errors
- Returns:
Point – The current point
- Point.set()
Set the coordinates of the point
- class Vector()
Tangent vector at the origin written in the reference frame. Are available form three.js: - all the linear algebra - the length of a vector
- Vector.isVector
True if the object implements the class Vector
- Vector.applyFacing(position)
Rotate the current vector by the facing component of the position. This method is geometry independent as the coordinates of the vector are given in a chosen reference frame. Only the reference frame depends on the geometry.
- Arguments:
position (Position) –
- Returns:
Vector – The current vector
- Vector.applyMatrix4(m)
Overload Three.js applyMatrix4. Indeed, Three.js considers the Vector3 as a 3D point. It multiplies the vector (with an implicit 1 in the 4th dimension) by the matrix, and divides by perspective. Here the data represents a vector, thus the implicit 4th coordinate is 0
- Arguments:
m (Matrix4) – The matrix to apply
- Returns:
Vector – The current vector
- class Position()
Location and facing (of the observer, an object, etc).
Constructor. Return the position corresponding to the origin with the reference frame.
- Position.Position
Constructor. Return the position corresponding to the origin with the reference frame.
- Position.boost
type: Isometry
The isometry component of the position.
- Position.facing
type: Matrix4
The facing as a Matrix4, representing an element of O(3). These are the data that actually passed to the shader
- Position.isPosition
True if the object implements the class Position
- Position.point
Return the underlying point
- Position.quaternion
type: Quaternion
The facing. We represent it as quaternion, whose action by conjugation on R^3 defines an element of O(3)
- Position.applyIsometry(isom)
Translate the current position by isom (left action of the isometry group G on the set of positions).
- Arguments:
isom (Isometry) – the isometry to apply
- Returns:
Position – The current position
- Position.applyQuaternion(quaternion)
Rotate the facing by m (right action of O(3) in the set of positions).
- Arguments:
quaternion (Quaternion) – the facing to apply (in the observer frame)
- Returns:
Position – The current position
- Position.clone()
Return a new copy of the current position.
- Returns:
Position – The clone of the current position
- Position.copy(position)
Set the current position with the given one.
- Arguments:
position (Position) – the position to copy
- Returns:
Position – the current position
- Position.equals(position)
Check if the current position and `position ` are the same.
- Arguments:
position (Position) –
- Returns:
boolean – true if the positions are equal, false otherwise
- Position.fakeDiffExpMap(matrix)
Fake version of the differential of the exponential map.
Assume that the current position is the (Id,Id). Take as input a Matrix4 matrix seen as an affine isometry of R^3 = T_oX with respect to the reference frame e = (e_1, e_2, e_3) (or more precisely, an isometry of the tangent bundle of T_oX) Update the position with the following properties. Let u = matrix . (0,0,0,1) that is the image of the origin of T_oX by matrix Let v = matrix . (0,0,1,0) that is the image of the vector e_3 by matrix The updated position (g,m) is such that g . origin = exp(u) and d_og m v = d_u exp v Or at least, this is the ideal goal.
We fake the behavior using parallel transport. Apparently the error made if of the order of O(|u|^2). https://mathoverflow.net/questions/126104/difference-between-parallel-transport-and-derivative-of-the-exponential-map Thus for controllers supposed to stay close to the user, it could be enough. (The overlay of the controllers and the seen is only correct at the first order.)
If the current position is not (Id, Id), then everything is made “relative” to the current position.
- Arguments:
matrix (Matrix4) – an affine isometry of the tangent space at the origin
- Returns:
Position –
- Position.flow(v)
Flow the current position. v is the pullback at the origin by the position of the direction in which we flow The time by which we flow is the norm of v.
The procedure goes as follows. Let e = (e1, e2, e3) be the reference frame in the tangent space at the origin. Assume that the current position is (g,m) The vector v = (v1, v2, v3) is given in the observer frame, that is v = d_og m u, where u = u1 . e1 + u2 . e2 + u3 . e3. - We first pull back the data at the origin by the inverse of g. - We compute the position (g’,m’) obtained from the initial position (id, id) by flowing in the direction w = m u. This position send the frame m e to d_o g’ . m ‘ . m . e ` - We move everything back using `g, so that the new observer frame is d_o (gg’) . m’ . m e.
Hence the new position (gg’, m’m) is obtained by multiplying (g,m) and (g’,m’)
- Arguments:
v (Vector) – the direction in the observer frame
- Returns:
Position – The current position
- Position.flowFromOrigin(v)
Replace the current position, by the one obtained by flowing the initial position (id, id) in the direction v (given in the reference frame).
- Arguments:
v (Vector) – the direction in the reference frame
- Returns:
Position – The current position
- Position.multiply(position)
Multiply the current position (g0,m0) on the right by the given position (g,m), i.e. return (g0 * g, m * m0)
- Arguments:
position (Position) –
- Returns:
Position – The current position
- Position.premultiply(position)
Multiply the current position (g0,m0) on the left by the given position (g,m), i.e. return (g * g0, m0 * m)
- Arguments:
position (Position) –
- Returns:
Position – The current position
- Position.reduceError()
Reduce the error of the boost part and the quaternion part.
- Returns:
Position – The current position
- Position.reduceErrorBoost()
Reduce the eventual numerical error of the current boost.
- Returns:
Position – The current position
- Position.reduceErrorQuaternion()
Make the quaternion has length one.
- Returns:
Position – The current position
- Position.reset()
Reset the position in its default position (boost = identity, quaternion = 1)
- Returns:
Position – The current position
- Position.setBoost(isom)
Set the boost part of the position.
- Arguments:
isom (Isometry) –
- Returns:
Position – The current position
- Position.setQuaternion(quaternion)
Set the facing part of the position.
- Arguments:
quaternion (Quaternion) –
- Returns:
Position – The current position
- class Group()
Group (in the mathematical sense). This class is mainly a container to receive the data common to all elements of the group.
Constructor
- Group.Group
Constructor
- Group.element()
Create an element in the group. If no data is passed, it should be the identity.
- Returns:
GroupElement –
- Group.shader(shaderBuilder)
Build the shader associated to the group.
- Arguments:
shaderBuilder (ShaderBuilder) –
- class GroupElement(group)
Group element. This class allows to define a “symbolic” representation for element of a discrete subgroup of isometries.
Constructor. The constructor should not be called directly. Use instead the element method of the class Group
- Arguments:
group (Group) – the underlying group
- GroupElement.GroupElement
Constructor. The constructor should not be called directly. Use instead the element method of the class Group
- GroupElement.name
type: string
The name of the item. This name is computed (from the uuid) the first time the getter is called.
- GroupElement.uuid
type: string
Universal unique ID. The dashes are replaced by underscored to avoid problems in the shaders
- GroupElement.clone()
Return a new copy of the current element.
- Returns:
GroupElement – The clone of the current element
- GroupElement.copy(elt)
Set the current element with the given element
- Arguments:
elt (GroupElement) – the element to copy
- Returns:
GroupElement – The current element
- GroupElement.equals(elt)
Check if the current element and isom are the same. Mainly for debugging purposes.
- Arguments:
elt (GroupElement) –
- Returns:
boolean – true if the elements are equal, false otherwise
- GroupElement.identity()
Set the current element to the identity.
- Returns:
GroupElement – the current element
- GroupElement.invert()
Invert the current element
- Returns:
GroupElement – the current element
- GroupElement.multiply(elt)
Multiply the current element by elt on the left, i.e. replace this by this * elt.
- Arguments:
elt (GroupElement) –
- Returns:
GroupElement – The current element
- GroupElement.premultiply(elt)
Multiply the current element by elt on the right, i.e. replace this by elt * this.
- Arguments:
elt (GroupElement) –
- Returns:
GroupElement – The current element
- GroupElement.toIsometry()
Convert the current element to an isometry