genepy3d.util package

Module contents

Submodules

genepy3d.util.geo module

Support functions for geometrical calculus.

Functions:

l2(p1, p2)	L2 distance between two points p1, p2.
norm(p)	Norm of vectors.
vector2points(p1, p2[, normalize])	Calculate the vector from point p1 to point p2 with/without normalization.
vector_axes_angles(v)	Calculate the angles between vector v and the three axes x, y and z.
vector_spherical_angles(v)	Spherical angles of vector.
angle2vectors(a, b)	Return angle between two vectors a and b.
angle3points(a, b, c)	Return angle between three points where b is the center point.
geo_len(P)	Return geodesic length of a curve defined from an array of points.
active_brownian_2d(n[, v, omega, p0, dt, R, ...])	Generate an active Brownian motion in 2D.
active_brownian_3d(n[, v, omega, p0, dt, R, ...])	Generate an active Brownian motion in 3D.
emd(X, Y[, return_flows])	Compute the Earth Mover's Distance (EMD) [1] between two point clouds X and Y.
rotation_matrix(u, theta)	Calculate the rotation matrix corresponding to a rotation of angle theta around a vector u in 3D.

genepy3d.util.geo.l2(p1, p2)

L2 distance between two points p1, p2.

Parameters:

• p1 (ndarray) – first point.

• p2 (ndarray) – second point.

Returns:

a float.

genepy3d.util.geo.norm(p)

Norm of vectors.

Parameters:

p (ndarray) – a vector or an array of vectors. each vector is at one row of the array, the array columns are the vector positions.

Returns:

an array of float.

Examples

import numpy as np
from genepy3d.util import geo
vecarr = np.array([[1,2,3],[1,2,3]]) # two vectors with similar values
geo.norm(vecarr)

genepy3d.util.geo.vector2points(p1, p2, normalize=True)

Calculate the vector from point p1 to point p2 with/without normalization.

Parameters:

• p1 (ndarray) – first point.

• p2 (ndarray) – second point.

• normalized (bool) – if True, then normalize the vector.

Returns:

an ndarray.

genepy3d.util.geo.vector_axes_angles(v)

Calculate the angles between vector v and the three axes x, y and z.

Parameters:

v (ndarray) – a vector.

Returns:

tuple of floats of the angles between v and axes x, y and z respectively.

genepy3d.util.geo.vector_spherical_angles(v)

Spherical angles of vector.

Parameters:

v (ndarray) – a vector.

Returns:

a list [theta, phi] of spherical angles.

Notes

The spherical coordinates are specified by

• azimuthal angle (theta) between the orthogonal projection of the vector v (on xy plane) and the x-vector.

• polar angle (phi) between the vector v and the z-vector.

genepy3d.util.geo.angle2vectors(a, b)

Return angle between two vectors a and b.

Parameters:

• a (ndarray) – a vector.

• b (ndarray) – a vector.

Returns:

a float.

genepy3d.util.geo.angle3points(a, b, c)

Return angle between three points where b is the center point. It is the angle between two vectors (b->a) and (b->c).

Parameters:

• a (ndarray) – a point.

• b (ndarray) – a point.

• c (ndarray) – a point.

Returns:

a float.

genepy3d.util.geo.geo_len(P)

Return geodesic length of a curve defined from an array of points. The first point and the last point are the begin and the end of the curve.

Parameters:

P (ndarray) – array of points.

Returns:

a float.

Examples

import numpy as np
from genepy3d.util import geo
P = np.array([[1,1,1],[2,2,2],[3,3,3]]) # curve with three points (1,1,1), (2,2,2) and (3,3,3)
geo.geo_len(P)

genepy3d.util.geo.active_brownian_2d(n, v=1e-06, omega=0.0, p0=[0, 0], dt=0.001, R=1e-06, T=300.0, eta=0.001, seed_point=None)

Generate an active Brownian motion in 2D. We implemented the algorithm from the Volpe et al. paper [1].

Parameters:

• n (int) – number of positions generated from the simulation.

• p0 (ndarray) – init position.

• v (float) – translation speed.

• omega (float) – rotation speed.

• dt (float) – time step.

• R (float) – particle radius.

• T (float) – environment temperature.

• eta (float) – fluid viscocity.

Returns:

A tuple containing

• P (array of float): list of 2D positions.

• t (array of float): corresponding times.

References

[1]

Volpe, G., Gigan, S., & Volpe, G. (2014). Simulation of the active Brownian motion of a microswimmer. American Journal of Physics, 82(7), 659-664. DOI:10.1119/1.4870398.

genepy3d.util.geo.active_brownian_3d(n, v=1e-06, omega=0.0, p0=[0, 0, 0], dt=0.001, R=1e-06, T=300.0, eta=0.001, seed_point=None)

Generate an active Brownian motion in 3D. We adapted the algorithm of active brownian motion in 2D from the paper of Volpe et al. [1] for 3D case.

Parameters:

• n (int) – number of positions generated from the simulation.

• p0 (ndarray) – init position.

• v (float) – translation speed.

• omega (float) – rotation speed.

• dt (float) – time step.

• R (float) – particle radius.

• T (float) – environment temperature.

• eta (float) – fluid viscocity.

Returns:

A tuple containing

• P (array of float): list of 3D positions.

• t (array of float): corresponding times.

References

[1]

Volpe, G., Gigan, S., & Volpe, G. (2014). Simulation of the active Brownian motion of a microswimmer. American Journal of Physics, 82(7), 659-664. DOI:10.1119/1.4870398.

genepy3d.util.geo.emd(X, Y, return_flows=False)

Compute the Earth Mover’s Distance (EMD) [1] between two point clouds X and Y. We used the emd func from POT library. Detail is here: https://pythonot.github.io/all.html#ot.emd

Parameters:

• X (ndarray) – array of points.

• Y (ndarray) – array of points.

• return_flows (bool) – if True return travelled flows between X and Y.

Returns:

if return_flows is False, then only the emd distance is returned, otherwise a tuple of distance and array of flows.

References

[1]

https://en.wikipedia.org/wiki/Earth_mover%27s_distance

Examples

import numpy as np
from genepy3d.util import geo
X = np.array([[1,1,1],[2,2,2]])
Y = np.array([[3,3,3],[4,4,4]])
loss = geo.emd(X,Y)

genepy3d.util.geo.rotation_matrix(u, theta)

Calculate the rotation matrix corresponding to a rotation of angle theta around a vector u in 3D.

Parameters:

• u (ndarray) – 3D vector for rotation direction.

• theta (float) – rotation angle in radians.

Returns:

rotation matrix.

Return type:

(ndarray of shape (3,3))

Examples

import numpy as np
from genepy3d.util import geo
u = np.array([1.,0.,0.]) # unit x-vector
theta = np.pi/2. # rotation of 90 degrees
M = geo.rotation_matrix(u,theta) # rotation matrix of 90 degrees around the unit x-vector

genepy3d.util.plot module

Plot objects using matplotlib.

This module contains basic plotting functions using the matplotlib library.

Functions:

plot_line(ax, projection, x, y, z[, scales, ...])	Wrapper for plot() in matplotlib.
plot_point(ax, projection, x, y, z[, ...])	Wrapper for scatter() in matplotlib.
fix_equal_axis(data)	Fix unequal axis bug in matplotlib 3d plot.

genepy3d.util.plot.plot_line(ax, projection, x, y, z, scales=(1.0, 1.0, 1.0), line_args={})

Wrapper for plot() in matplotlib. Support 3D, xy, xz and yz projections.

Parameters:

• ax – axis to be plotted.

• projection (str) – support 3d, xy, xz, yz.

• x (ndarray) – x coordinates.

• y (ndarray) – y coordinates.

• z (ndarray) – z coordinates.

• scales (tuple) – axis scales.

• line_args (dic) – matplotlib args for plot() func.

Returns:

matplotlib plot object.

Examples

import numpy as np
from genepy3d.util import plot as mypl
import matplotlib.pyplot as plt

# coordinates
x = np.array([1.,2.,3.])
y = np.array([1.,2.,3.])
z = np.array([1.,2.,3.])

# 3D plot
fig = plt.figure()
ax = fig.add_subplot(111,projection='3d')
mypl.plot_line(ax,'3d',x,y,z)

# 2D plot (XY projection)
fig = plt.figure()
ax = fig.add_subplot(111)
mypl.plot_line(ax,'xy',x,y,z)

genepy3d.util.plot.plot_point(ax, projection, x, y, z, scales=(1.0, 1.0, 1.0), point_args={})

Wrapper for scatter() in matplotlib. Support 3D, xy, xz and yz projections.

Parameters:

• ax – axis to be plotted.

• projection (str) – support 3d, xy, xz, yz.

• x (ndarray) – x coordinates.

• y (ndarray) – y coordinates.

• z (ndarray) – z coordinates.

• scales (tuple) – axis scales.

• point_args (dic) – matplotlib args for scatter() func.

Returns:

matplotlib scatter object.

Examples

import numpy as np
from genepy3d.util import plot as mypl
import matplotlib.pyplot as plt

# coordinates
x = np.array([1.,2.,3.])
y = np.array([1.,2.,3.])
z = np.array([1.,2.,3.])

# 3D plot
fig = plt.figure()
ax = fig.add_subplot(111,projection='3d')
mypl.plot_point(ax,'3d',x,y,z)

# 2D plot (XY projection)
fig = plt.figure()
ax = fig.add_subplot(111)
mypl.plot_point(ax,'xy',x,y,z)

genepy3d.util.plot.fix_equal_axis(data)

Fix unequal axis bug in matplotlib 3d plot.

The option ax.axis(‘equal’) doesn’t seem to work in 3D. Assuming a plot of 3D point cloud. This function attemps to fix this issue.

Parameters:

data (ndarray) – 3D points.

Returns:

min and max values in each axis.

Notes

The returned values are then used in ax.set_xlim(), ax.set_ylim(), ax.set_zlim() to correct the unequal axis.

Examples

import numpy as np
from genepy3d.util import plot as mypl
import matplotlib.pyplot as plt

# Coordinates
x = np.array([1.,50.,100.])
y = np.array([1.,50.,100.])
z = np.array([1.,50.,100.])

# 3D plot
fig = plt.figure()
ax = fig.add_subplot(111,projection='3d')
mypl.plot_point(ax,'3d',x,y,z)

# Fix unequal axis
data = np.array([x,y,z]).T # array of points whose columns are x, y and z positions
param = mypl.fix_equal_axis(data)
ax.set_xlim(param['xmin'],param['xmax']);
ax.set_ylim(param['ymin'],param['ymax']);
ax.set_zlim(param['zmin'],param['zmax']);