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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
Returns:

GroupElement – The current element

GroupElement.equals(elt)

Check if the current element and isom are the same. Mainly for debugging purposes.

Arguments:
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:
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:
Returns:

GroupElement – The current element

GroupElement.toIsometry()

Convert the current element to an isometry