geoclide.vecope module#

Operations on vectors, points and normals.

This module provides the classical operations between Vector, Point and Normal objects: dot and cross products, normalization, creation of an orthogonal coordinate system from a single vector, distance between two points, flipping of a vector/normal such that it lies in the same hemisphere as another one, and component-wise utilities (maximum, minimum, argmax, argmin, absolute value and permutation). All the functions accept both single objects and sets of objects for vectorized calculations.

geoclide.vecope.coordinate_system(v1: Vector, method: str = 'm2') → tuple[Vector, Vector][source]#

Create orthogonal coordinate system(s) from a vector/set of vectors

Parameters:

v1Vector: The base vector(s) used to create the orthogonal coordinate system(s)
methodstr, optional: Default is ‘m2’ (method from pbrt v4), other choice is ‘m1’ (pbrt v2 and v3)

Returns:

v2Vector: The second vector(s) of the orthogonal coordinate system(s)
v3Vector: The third vector(s) of the orthogonal coordinate system(s)

Examples

>>> import geoclide as gc
>>> v1 = gc.Vector(0., 0., 1.)
>>> gc.coordinate_system(v1)
(Vector(1.0, -0.0, -0.0), Vector(-0.0, 1.0, -0.0))

geoclide.vecope.cross(a: Vector | Normal, b: Vector | Normal) → Vector[source]#

The cross product

Warning

The cross product of 2 normals is not allowed

Definition of the cross product:

\((a × b) = ((a.y*b.z)-(a.z*b.y))x̂ + ((a.z*b.x)-(a.x*b.z))ŷ + ((a.x*b.y)-(a.y*b.x))\)
\((a × b) = ||a||*||b||*sin(θ)\)

where x̂, ŷ and ẑ are the unitary vectors respectively in axes x, y and z

Parameters:

aVector or Normal: The first vector(s) or normal(s) used for the cross product
bVector or Normal: The second vector(s) or normal(s) used for the cross product

Returns:

Vector: The result(s) of the cross product

Examples

>>> import geoclide as gc
>>> a = gc.Vector(0.,0.,1.)
>>> b = gc.Vector(1.,0.,0.)
>>> gc.cross(a,b)
Vector(0.0, 1.0, 0.0)

geoclide.vecope.distance(p1: Point, p2: Point) → float | ndarray[source]#

Compute the distance(s) between 2 points/set of points

Parameters:

p1Point: The first point(s)
p2Point: The second point(s)

Returns:

float or ndarray: The distance(s) between the 2 points/set of points. In case of an ndarray, it is 1-D

Examples

>>> import geoclide as gc
>>> p1 = gc.Point(0., 0., 0.)
>>> p2 = gc.Point(0., 0., 10.)
>>> gc.distance(p1,p2)
10.0
>>> p1 = gc.Point(1., 2., 1.9)
>>> p2 = gc.Point(5., 15., 3.)
>>> gc.distance(p1,p2)
13.64587849865299

geoclide.vecope.dot(a: Vector | Normal, b: Vector | Normal) → float | ndarray[source]#

The dot/scalar product

Definition of the dot product:

\((a . b) = a.x*b.x + a.y*b.y + a.z*b.z\)
\((a . b) = ||a|| * ||b|| * cos(θ)\)

Parameters:

aVector or Normal: The first vector(s) or normal(s) used for the dot product
bVector or Normal: The second vector(s) or normal(s) used for the dot product

Returns:

float or ndarray: The result(s) of the dot product i.e. sum of products. In case of an ndarray, it is 1-D

Examples

>>> import geoclide as gc
>>> a = gc.Vector(0., 0., 1.)
>>> b = gc.Vector(math.sqrt(2.)/2., 0., math.sqrt(2.)/2.)
>>> gc.dot(a,b)
0.7071067811865476

geoclide.vecope.face_forward(a: Vector | Normal, b: Vector | Normal) → Vector | Normal[source]#

Flip the vector(s)/normal(s) a if the vector(s)/normal(s) b is/are in the opposite direction(s)

It can be useful to flip a surface normal so that it lies in the same hemisphere as a given vector.

Parameters:

aVector or Normal: The vector(s) or normal(s) to potentially flip
bVector or Normal: The base vector(s) or normal(s) used for the flip

Returns:

Vector or Normal: The potentially flipped vector(s) or normal(s)

Examples

>>> import geoclide as gc
>>> n1 = gc.Normal(1., 0., 0.)
>>> v1 = gc.Vector(-1., 0., 0.)
>>> gc.face_forward(v1, n1)
Vector(1.0, -0.0, -0.0)

geoclide.vecope.normalize(v: Vector) → Vector[source]#

geoclide.vecope.normalize(v: Normal) → Normal

Normalize a vector/normal or a set of vectors/normals

Parameters:

vVector or Normal: The vector(s) or normal(s) to be normalized

Returns:

Vector or Normal: The normalized vector(s)/normal(s)

Examples

>>> import geoclide as gc
>>> v = gc.Vector(1.,0.,1.)
>>> gc.normalize(v)
Vector(0.7071067811865475, 0.0, 0.7071067811865475)

Permutes the vector(s)/point(s)/normal(s) x, y, z values according to the given indices

Parameters:

aVector or Point or Normal: The vector(s), point(s) or normal(s) used for permutation
ixint or np.ndarray or list, optional: The index/indices of the value(s) we want to keep as a remplacement for the x component(s)
iyint or np.ndarray or list, optional: The index/indices of the value(s) we want to keep as a remplacement for the y component(s)
izint or np.ndarray or list, optional: The index/indices of the value(s) we want to keep as a remplacement for the z component(s)

Returns:

Vector or Point or Normal: The vector(s)/point(s)/normal(s) after the permute operation

Examples

>>> import geoclide as gc
>>> v1 = gc.Vector(2., 3., 1.)
>>> gc.permute(v1, 1, 0, 2)
Vector(3.0, 2.0, 1.0)
>>> import numpy as np
>>> p_set = np.array(
...     [[0.,0.,3.], [1.,0.,0.], [-0.5,0.,0.], [0.,-3.,0.]]
... )
>>> p_set = gc.Point(p_set)
>>> gc.permute(p_set, [2,0,0,1], 1, 2).to_numpy()
array([[ 3. ,  0. ,  3. ],
       [ 1. ,  0. ,  0. ],
       [-0.5,  0. ,  0. ],
       [-3. , -3. ,  0. ]])

geoclide.vecope.vabs(a: Vector | Point | Normal) → Vector | Point | Normal[source]#

Calculate the absolute value(s) of each component of the vector(s)/point(s)/normal(s)

Parameters:

aVector or Point or Normal: The vector(s)/point(s)/normal(s) used

Returns:

Vector or Point or Normal or ndarray: The vector(s)/point(s)/normal(s) with absolute values. In case of an ndarray, it is 1-D

geoclide.vecope.vargmax(a: Vector | Point | Normal) → int | ndarray[source]#

Get the index/indices of the vector(s)/point(s)/normal(s) components with the largest value(s)

Parameters:

aVector or Point or Normal: The vector(s)/point(s)/normal(s) used

Returns:

int or ndarray: The index/indices of the largest vector(s)/point(s)/normal(s) value(s). In case of an ndarray, it is 1-D

Examples

>>> import geoclide as gc
>>> v1 = gc.Vector(2.,3.,1.)
>>> gc.vargmax(v1)
1

geoclide.vecope.vargmin(a: Vector | Point | Normal) → int | ndarray[source]#

Get the index/indices of the vector(s)/point(s)/normal(s) components with the smallest value(s)

Parameters:

aVector or Point or Normal: The vector(s)/point(s)/normal(s) used

Returns:

int or ndarray: The index/indices of the smallest vector(s)/point(s)/normal(s) value(s). In case of an ndarray, it is 1-D

Examples

>>> import geoclide as gc
>>> v1 = gc.Vector(2.,3.,1.)
>>> gc.vargmin(v1)
2

geoclide.vecope.vmax(a: Vector | Point | Normal) → float | ndarray[source]#

Get the largest components value(s) of the vector(s)/point(s)/normal(s)

Parameters:

aVector or Point or Normal: The vector(s)/point(s)/normal(s) used

Returns:

float or ndarray: The largest vector(s)/point(s)/normal(s) value(s). In case of an ndarray, it is 1-D

Examples

>>> import geoclide as gc
>>> v1 = gc.Vector(2.,3.,1.)
>>> gc.vmax(v1)
3.0

geoclide.vecope.vmin(a: Vector | Point | Normal) → float | ndarray[source]#

Get the smallest components value(s) of the vector(s)/point(s)/normal(s)

Parameters:

aVector or Point or Normal: The vector(s)/point(s)/normal(s) used

Returns:

float or ndarray: The smallest vector(s)/point(s)/normal(s) value(s). In case of an ndarray, it is 1-D

Examples

>>> import geoclide as gc
>>> v1 = gc.Vector(2.,3.,1.)
>>> gc.vmin(v1)
1.0