3D line

A 3D line using Plücker coordinates.

class Line3(v=None, w=None, check=True)[source]

Bases: spatialmath.baseposelist.BasePoseList

classmethod Alloc(n=1)

Construct an instance with N default values (BasePoseList superclass method)

Parameters: n (int, optional) – Number of values, defaults to 1
Return type: Self
Returns: pose instance with n default values

X.Alloc(N) creates an instance of the pose class X with N default values, ie. len(X) will be N.

X can be considered a vector of pose objects, and those elements can be referenced X[i] or assigned to X[i] = ....

Note

The default value depends on the pose class and is the result of the empty constructor. For SO2, SE2, SO3, SE3 it is an identity matrix, for a twist class Twist2 or Twist3 it is a zero vector, for a UnitQuaternion or Quaternion it is a zero vector.

Example:

>>> x = X.Alloc(10)
>>> len(x)
10

where X is any of the SMTB classes.

classmethod Empty()

Construct an empty instance (BasePoseList superclass method)

Return type: Self
Returns: pose instance with zero values

Example:

>>> x = X.Empty()
>>> len(x)
0

where X is any of the SMTB classes.

classmethod IntersectingPlanes(pi1, pi2)[source]

Return type: Self

classmethod Join(P, Q)[source]

Create 3D line from two 3D points

Parameters

P (array_like(3)) – First 3D point
Q (array_like(3)) – Second 3D point

Returns

3D line

Return type

Line3 instance

Line3.Join(P, Q) create a Line3 object that represents the line joining the 3D points P (3,) and Q (3,). The direction is from Q to P.

Seealso: IntersectingPlanes() PointDir()

classmethod PointDir(point, dir)[source]

Create 3D line from a point and direction

Parameters

point (array_like(3)) – A 3D point
dir (array_like(3)) – Direction vector

Returns

3D line

Return type

Line3 instance

Line3.PointDir(P, W) is a Line3` object that represents the line containing the point P and parallel to the direction vector W.

Seealso: Join() IntersectingPlanes()

classmethod TwoPlanes(pi1, pi2)[source]

Create 3D line from intersection of two planes

Parameters

pi1 (array_like(4), or Plane) – First plane
pi2 (array_like(4), or Plane) – Second plane

Returns

3D line

Return type

Line3 instance

L = Line3.TwoPlanes(π1, π2) is a Line3 object that represents the line formed by the intersection of two planes π1 and π3.

Planes are represented by the 4-vector \([a, b, c, d]\) which describes the plane \(\pi: ax + by + cz + d=0\).

Seealso: Join() PointDir()

__eq__(l2)[source]

Test if two lines are equivalent

Parameters: l2 (Line3) – Second line
Returns: lines are equivalent
Return type: bool

L1 == L2 is True if the Line3 objects describe the same line in space. Note that because of the over parameterization, lines can be equivalent even if their coordinate vectors are different.

Note

There is a hardwired tolerance of 10eps.

Seealso: isequal() __ne__()

__init__(v=None, w=None, check=True)[source]

Create a Line3 object

Parameters

v (array_like(6) or array_like(3)) – Plucker coordinate vector, or Plucker moment vector
w (array_like(3), optional) – Plucker direction vector, optional
check (bool) – check that the parameters are valid, defaults to True

Raises

ValueError – bad arguments

Returns

3D line

Return type

Line3 instance

A representation of a 3D line using Plucker coordinates.

Line3(p) creates a 3D line from a Plucker coordinate vector p=[v, w]
where v (3,) is the moment and w (3,) is the line direction.
Line3(v, w) as above but the components v and w are provided separately.
Line3(L) creates a copy of the Line3 object L.

Notes

The Line3 object inherits from collections.UserList and has list-like behaviours.
A single Line3 object contains a 1D-array of Plucker coordinates.
The elements of the array are guaranteed to be Plucker coordinates.
The number of elements is given by len(L)
The elements can be accessed using index and slice notation, eg. L[1] or L[2:3]
The Line3 instance can be used as an iterator in a for loop or list comprehension.
Some methods support operations on the internal list.

Seealso

Join() TwoPlanes() PointDir()

__mul__(right)[source]

Reciprocal product

Parameters

left (Line3) – Left operand
right (Line3) – Right operand

Returns

reciprocal product

Return type

float

left * right is the scalar reciprocal product \(\hat{w}_L \dot m_R + \hat{w}_R \dot m_R\).

Note

Multiplication or composition of lines is not defined.
Pre-multiplication by an SE3 object is supported, see __rmul__.

Seealso: __rmul__()

__ne__(l2)[source]

Test if two lines are not equivalent

Parameters: l2 (Line3) – Second line
Returns: lines are not equivalent
Return type: bool

L1 != L2 is True if the Line3 objects describe different lines in space. Note that because of the over parameterization, lines can be equivalent even if their coordinate vectors are different.

Note

There is a hardwired tolerance of 10eps.

Seealso: __ne__()

__or__(l2)[source]

Overloaded | operator tests for parallelism

Parameters: l2 (Line3) – Second line
Returns: lines are parallel
Return type: bool

l1 | l2 is an operator which is true if the two lines are parallel.

Note

The | operator has low precendence.

Note

There is a hardwired tolerance of 10eps.

Seealso: isparallel() __xor__()

__rmul__(left)[source]

Rigid-body transformation of 3D line

Parameters

left (SE3) – Rigid-body transform
right (Line) – 3D line

Returns

transformed 3D line

Return type

Line3 instance

T * line is the line transformed by the rigid body transformation T.

Seealso: __mul__()

__xor__(l2)[source]

Overloaded ^ operator tests for intersection

Parameters: l2 (Line3) – Second line
Returns: lines intersect
Return type: bool

l1 ^ l2 is an operator which is true if the two lines intersect.

Note

The ^ operator has low precendence.
Is False if the lines are equivalent since they would intersect at an infinite number of points.

Note

There is a hardwired tolerance of 10eps.

Seealso: intersects() isparallel() isintersecting()

append(x)[source]

Append a line

Parameters: x (Line3) – line object
Raises: ValueError – Attempt to append a non Plucker object
Returns: Line3 object with new line appended
Return type: Line3 instance

arghandler(arg, convertfrom=(), check=True)

Standard constructor support (BasePoseList superclass method)

Parameters

arg (Any) – initial value
convertfrom (Tuple) – list of classes to accept and convert from
check (bool) – check value is valid, defaults to True

Type

tuple of typles

Raises

ValueError – bad type passed

The value arg can be any of:

None, an identity value is created
a numpy.ndarray of the appropriate shape and value which is valid for the subclass
a list whose elements all meet the criteria above
an instance of the subclass
a list whose elements are all singelton instances of the subclass

For cases 2 and 3, a NumPy array or a list of NumPy array is passed. Each NumPyarray is tested for validity (if check is False a cursory check of shape is made, if check is True the numerical value is inspected) and converted to the required internal format by the _import method. The default _import method calls the isvalid method for checking. This mechanism allows equivalent forms to be passed, ie. 6x1 or 4x4 for an se(3).

If self is an instance of class A, and an instance of class B is passed and B is an element of the convertfrom argument, then B.A() will be invoked to perform the type conversion.

Examples:

SE3()
SE3(np.identity(4))
SE3([np.identity(4), np.identity(4)])
SE3(SE3())
SE3([SE3(), SE3()])
Twist3(SE3())

Return type: bool

binop(right, op, op2=None, list1=True)

Perform binary operation

Parameters

left (BasePoseList subclass) – left operand
right (BasePoseList subclass, scalar or array) – right operand
op (callable) – binary operation
op2 (callable) – binary operation
list1 (bool) – return single array as a list, default True

Raises

ValueError – arguments are not compatible

Returns

list of values

Return type

list

The is a helper method for implementing binary operation with overloaded operators such as X * Y where X and Y are both subclasses of BasePoseList. Each operand has a list of one or more values and this methods computes a list of result values according to:

Inputs		Output
len(left)	len(right)	len	operation
1	1	1	`ret = op(left, right)`
1	M	M	`ret[i] = op(left, right[i])`
M	1	M	`ret[i] = op(left[i], right)`
M	M	M	`ret[i] = op(left[i], right[i])`

The arguments to op are the internal numeric values, ie. as returned by the ._A property.

The result is always a list, except for the first case above and list1 is False.

If the right operand is not a BasePoseList subclass, but is a numeric scalar or array then then op2 is invoked

For example:

X._binop(Y, lambda x, y: x + y)

Input	Output
len(left)	len	operation
1	1	`ret = op2(left, right)`
M	M	`ret[i] = op2(left[i], right)`

There is no check on the shape of right if it is an array. The result is always a list, except for the first case above and list1 is False.

clear() → None -- remove all items from S

closest_to_line(l2)[source]

Closest point between lines

Parameters: l2 (Line3) – second line
Returns: nearest points and distance between lines at those points
Return type: ndarray(3,N), ndarray(N)

There are four cases:

len(self) == len(other) == 1 find the point on the first line closest to the second line, as well as the minimum distance between the lines.
len(self) == 1, len(other) == N find the point of intersection between the first line and the N other lines, returning N intersection points and distances.
len(self) == N, len(other) == 1 find the point of intersection between the N first lines and the other line, returning N intersection points and distances.
len(self) == N, len(other) == M for each of the N first lines find the closest intersection with each of the M other lines, returning N intersection points and distances.

** this last one should be an option, default behavior would be to test self[i] against line[i] ** maybe different function

For two sets of lines, of equal size, return an array of closest points and distances.

Example:

.. runblock:: pycon

    >>> from spatialmath import Line3
    >>> line1 = Line3.Join([1, 1, 0], [1, 1, 1])
    >>> line2 = Line3.Join([0, 0, 0], [2, 3, 5])
    >>> line1.closest_to_line(line2)

Reference: Plucker coordinates
Seealso: distance()

closest_to_point(x)[source]

Point on line closest to given point

Parameters: x (array_like(3)) – An arbitrary 3D point
Returns: Point on the line and distance to line
Return type: ndarray(3), float

Find the point on the line closest to x as well as the distance at that closest point.

Example:

>>> from spatialmath import Line3
>>> line1 = Line3.Join([0, 0, 0], [2, 2, 3])
>>> line1.closest_to_point([1, 1, 1])
(array([0.8235, 0.8235, 1.2353]), 0.3429971702850176)

Seealso: meth:point

commonperp(l2)[source]

Common perpendicular to two lines

Parameters: l2 (Line3) – Second line
Returns: Perpendicular line
Return type: Line3 instance or None

l1.commonperp(l2) is the common perpendicular line between the two lines. Returns None if the lines are parallel.

Seealso: intersect()

contains(x, tol=20)[source]

Test if points are on the line

Parameters

x (3-element array_like, or ndarray(3,N)) – 3D point
tol (float, optional) – Tolerance in units of eps, defaults to 20

Raises

ValueError – Bad argument

Returns

Whether point is on the line

Return type

bool or numpy.ndarray(N) of bool

line.contains(X) is true if the point X lies on the line defined by the Line3 object self.

If X is an array with 3 rows, the test is performed on every column and an array of booleans is returned.

copy()

count(value) → integer -- return number of occurrences of value

distance(l2, tol=20)[source]

Minimum distance between lines

Parameters

l2 (Line3) – Second line
tol (float, optional) – Tolerance in multiples of eps, defaults to 20

Returns

Closest distance between lines

Return type

float

``l1.distance(l2) is the minimum distance between two lines.

Note

Works for parallel, skew and intersecting lines.

Seealso: closest_to_line()

extend(iterable)

Extend sequence of values in an instance (BasePoseList superclass method)

Parameters: x (instance of same type) – the value to extend
Raises: ValueError – incorrect type of appended object

Appends the argument’s values to the object’s internal list of values.

Example:

>>> x = X.Alloc(10)
>>> len(x)
10
>>> x.append(X.Alloc(5))   # extend the list
>>> len(x)
15

where X is any of the SMTB classes.

Return type: None

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, item)

Insert a value to an instance (BasePoseList superclass method)

Parameters

i (int) – element to insert value before
item (instance of same type) – the value to insert

Raises

ValueError – incorrect type of inserted value

Inserts the argument into the object’s internal list of values.

Example:

>>> x = X.Alloc(10)
>>> len(x)
10
>>> x.insert(0, X())   # insert at start of list
>>> len(x)
11
>>> x.insert(10, X())   # append to the list
>>> len(x)
11

where X is any of the SMTB classes.

Note

If i is beyond the end of the list, the item is appended to the list

Return type: None

intersect_plane(plane, tol=20)[source]

Line intersection with a plane

Parameters

plane (array_like(4) or Plane3) – A plane
tol (float, optional) – Tolerance in multiples of eps, defaults to 20

Returns

Intersection point, λ

Return type

ndarray(3), float

P, λ = line.intersect_plane(plane) is the point where the line intersects the plane, and the corresponding λ value. Return None, None if no intersection.

The plane can be specified as:

a 4-vector \([a, b, c, d]\) which describes the plane \(\pi: ax + by + cz + d=0\).

a Plane object

The return value is a named tuple with elements:

.p for the point on the line as a numpy.ndarray, shape=(3,)

.lam the lambda value for the point on the line.

Sealso: point() Plane

intersect_volume(bounds)[source]

Line intersection with a volume

Parameters: bounds (Union[List, Tuple[float, float, float, float, float, float], ndarray[Any, dtype[TypeVar(ScalarType, bound= generic, covariant=True)]]]) – Bounds of an axis-aligned rectangular cuboid
Returns: Intersection point, λ value
Return type: ndarray(3,N), ndarray(N)

P, λ = line.intersect_volume(bounds) is a matrix (3xN) with columns that indicate where the line intersects the faces of the volume and the corresponding λ values.

The volume is specified by bounds = [xmin xmax ymin ymax zmin zmax].

The number of columns N is either:

0, when the line is outside the plot volume or,
2 when the line pierces the bounding volume.

See also plot() point()

intersects(l2)[source]

Intersection point of two lines

Parameters: l2 (Line3) – Second line
Returns: 3D intersection point
Return type: ndarray(3) or None

l1.intersects(l2) is the point of intersection of the two lines, or None if the lines do not intersect or are equivalent.

Seealso: commonperp :meth:`eq() __xor__()

isequal(l2, tol=20)[source]

Test if two lines are equivalent

Parameters

l2 (Line3) – Second line
tol (float, optional) – Tolerance in multiples of eps, defaults to 20

Returns

lines are equivalent

Return type

bool

L1 == L2 is True if the Line3 objects describe the same line in space. Note that because of the over parameterization, lines can be equivalent even if their coordinate vectors are different.

Seealso: __eq__()

isintersecting(l2, tol=20)[source]

Test if lines are intersecting

Parameters

l2 (Line3) – Second line
tol (float, optional) – Tolerance in multiples of eps, defaults to 20

Returns

lines intersect

Return type

bool

l1.isintersecting(l2) is true if the two lines intersect.

Note

Is False if the lines are equivalent since they would intersect at an infinite number of points.

Seealso: __xor__() intersects() isparallel()

isparallel(l2, tol=20)[source]

Test if lines are parallel

Parameters

l2 (Line3) – Second line
tol (float, optional) – Tolerance in multiples of eps, defaults to 20

Returns

lines are parallel

Return type

bool

l1.isparallel(l2) is true if the two lines are parallel.

l1 | l2 as above but in binary operator form

Seealso: __or__() intersects()

static isvalid(x, check=False)[source]

A decorator indicating abstract staticmethods.

Similar to abstractmethod.

Usage:

class C(metaclass=ABCMeta):
@abstractstaticmethod def my_abstract_staticmethod(…):

…

‘abstractstaticmethod’ is deprecated. Use ‘staticmethod’ with ‘abstractmethod’ instead.

Return type: bool

lam(point)[source]

Parametric distance from principal point

Parameters: point (array_like(3)) – 3D point
Returns: parametric distance λ
Return type: float

line.lam(P) is the value of \(\lambda\) such that \(Q = P_p + \lambda \hat{d}\) is closest to P.

Seealso: point()

plot(*pos, bounds=None, ax=None, **kwargs)[source]

Plot a line

Parameters

bounds (Union[float, List[float], Tuple[float, ...], ndarray[Any, dtype[TypeVar(ScalarType, bound= generic, covariant=True)]], None]) – Bounds of an axis-aligned rectangular cuboid as [xmin xmax ymin ymax zmin zmax], optional
**kwargs –
Extra arguents passed to Line2D

Returns

Plotted line

Return type

Matplotlib artists

line.plot(bounds) adds a line segment to the current axes, and the handle of the line is returned. The line segment is defined by the intersection of the line and the given rectangular cuboid. If the line does not intersect the plotting volume None is returned.
line.plot() as above but the bounds are taken from the axis limits of the current axes.

The line color or style is specified by:

a MATLAB-style linestyle like ‘k–’

additional arguments passed to Line2D

Seealso: intersect_volume()

point(lam)[source]

Generate point on line

Parameters: lam (float) – Scalar distance from principal point
Returns: Distance from principal point to the origin
Return type: float

line.point(λ) is a point on the line, where λ is the parametric distance along the line from the principal point of the line such that \(P = P_p + \lambda \hat{d}\) and \(\hat{d}\) is the line direction given by line.uw.

Seealso: pp() closest() uw() lam()

pop(i=- 1)

Pop value from an instance (BasePoseList superclass method)

Parameters: i (int) – item in the list to pop, default is last
Returns: the popped value
Return type: instance of same type
Raises: IndexError – if there are no values to pop

Removes a value from the value list and returns it. The original instance is modified.

Example:

>>> x = X.Alloc(10)
>>> len(x)
10
>>> y = x.pop()  # pop the last value x[9]
>>> len(x)
9
>>> y = x.pop(0)  # pop the first value x[0]
>>> len(x)
8

where X is any of the SMTB classes.

remove(item): S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse(): S.reverse() – reverse IN PLACE

side(other)[source]

Plucker side operator

Parameters: other (Line3) – second line
Returns: permuted dot product
Return type: float

This permuted dot product operator is zero whenever the lines intersect or are parallel.

skew()[source]

Line as a Plucker skew-symmetric matrix

Returns: Skew-symmetric matrix form of Plucker coordinates
Return type: ndarray(4,4)

line.skew() is the Plucker matrix, a 4x4 skew-symmetric matrix representation of the line whose six unique elements are the Plucker coordinates of the line.

\[\begin{split}\sk{L} = \begin{bmatrix} 0 & v_z & -v_y & \omega_x \\ -v_z & 0 & v_x & \omega_y \\ v_y & -v_x & 0 & \omega_z \\ -\omega_x & -\omega_y & -\omega_z & 0 \end{bmatrix}\end{split}\]

Note

For two homogeneous points P and Q on the line, \(PQ^T-QP^T\) is

also skew symmetric. - The projection of Plucker line by a perspective camera is a homogeneous line (3x1) given by \(\vee C M C^T\) where \(C \in \mathbf{R}^{3 \times 4}\) is the camera matrix.

sort(*args, **kwds)

unop(op, matrix=False)

Perform unary operation

Parameters

self (BasePoseList subclass) – operand
op (callable) – unnary operation
matrix (bool) – return array instead of list, default False

Returns

operation results

Return type

list or NumPy array

The is a helper method for implementing unary operations where the operand has multiple value. This method computes the value of the operation for all input values and returns the result as either a list or as a matrix which vertically stacks the results.

Input	Output
len(self)	len	operation
1	1	`ret = op(self)`
M	M	`ret[i] = op(self[i])`
M	M	`ret[i,;] = op(self[i])`

The result is:

a list of values if matrix==False, or
a 2D NumPy stack of values if matrix==True, it is assumed that the value is a 1D array.

property A: numpy.ndarray[Any, numpy.dtype[numpy.floating]]

Array value of an instance (BasePoseList superclass method)

Returns: NumPy array value of this instance
Return type: ndarray

X.A is a NumPy array that represents the value of this instance, and has a shape given by X.shape.

Note

This assumes that len(X) == 1, ie. it is a single-valued instance.

property pp: numpy.ndarray[Any, numpy.dtype[numpy.floating]]

Principal point of the 3D line

Returns: Principal point of the line
Return type: ndarray(3)

line.pp is the point on the line that is closest to the origin.

Notes:

Same as Plucker.point(0)

Seealso: ppd() :meth`point`

property ppd: float

Distance from principal point to the origin

Returns: Distance from principal point to the origin
Return type: float

line.ppd is the distance from the principal point to the origin. This is the smallest distance of any point on the line to the origin.

Seealso: pp()

property shape: Tuple[int]

Return type: Tuple[int]

property uw: numpy.ndarray[Any, numpy.dtype[numpy.floating]]

Line direction as a unit vector

Returns: Line direction as a unit vector
Return type: ndarray(3,)

line.uw is a unit-vector parallel to the line.

The line is represented by a vector \((\vec{v}, \vec{w}) \in \mathbb{R}^6\).

Seealso: w()

property v: numpy.ndarray[Any, numpy.dtype[numpy.floating]]

Moment vector

Returns: the moment vector
Return type: ndarray(3)

The line is represented by a vector \((\vec{v}, \vec{w}) \in \mathbb{R}^6\).

Seealso: w()

property vec: numpy.ndarray[Any, numpy.dtype[numpy.floating]]

Line as a Plucker coordinate vector

Returns: Plucker coordinate vector
Return type: ndarray(6,)

line.vec is the Plucker coordinate vector \((\vec{v}, \vec{w}) \in \mathbb{R}^6\).

property w: numpy.ndarray[Any, numpy.dtype[numpy.floating]]

Direction vector

Returns: the direction vector
Return type: ndarray(3)

The line is represented by a vector \((\vec{v}, \vec{w}) \in \mathbb{R}^6\).

Seealso: v() uw()