kornia.geometry.line#

class kornia.geometry.line.ParametrizedLine(origin, direction)[source]#

Class that describes a parametrized line.

A parametrized line is defined by an origin point \(o\) and a direction vector \(d\) such that the line corresponds to the set

\[l(t) = o + t * d\]

Convention:

The constructor does not normalise or check direction, so point_at() steps t in units of its length. through() and fit_line() return a unit direction; after through(), t is the Euclidean distance from p0.
projection(), squared_distance() and distance() require a unit direction.
intersect() returns (lambda, point) with point = point_at(lambda): lambda is in units of the stored direction, and the plane’s normal need not be unit.

__init__(origin, direction)[source]#

Initialize a parametrized line of direction and origin.

Parameters:

origin (Tensor) – any point on the line of any dimension.
direction (Tensor) – the direction vector of the line, of the same dimension.

Raises:

TypeCheckError – if origin or direction is an integer or bool tensor.

Example

>>> o = torch.tensor([0.0, 0.0])
>>> d = torch.tensor([0.6, 0.8])
>>> l = ParametrizedLine(o, d)

dim()[source]#

Return the dimension in which the line holds.

Return type:: int

property direction: Tensor#: Return the line direction vector.

distance(point)[source]#

Return the distance of a point to its projection onto the line.

Parameters:: point (Tensor) – the point to calculate the distance onto the line.
Return type:: Tensor

intersect(plane, eps=1e-6)[source]#

Return the intersection point between the line and a given plane.

Parameters:

plane (Hyperplane) – the plane to compute the intersection point.
eps (float, optional) – absolute threshold on |normal . direction| below which the line counts as parallel to the plane. Default: 1e-6

Return type:

Tuple[Tensor, Tensor]

Returns:

the lambda value used to compute the look at point.
the intersected point.

Note

If the line is parallel to the plane (|normal . direction| < eps) there is no unique intersection; the function returns lambda 0 and the line origin as the point. Within this fallback branch, lambda has zero derivatives and the point differentiates as the origin.

property origin: Tensor#: Return the line origin point.

point_at(t)[source]#

Get the point at \(t\) along this line.

Parameters:: t (Union[float, Tensor, Scalar]) – step along the line: a number or a 0-d tensor for every row, or one step per row of shape \((B,)\) or \((B, 1)\) for a line of shape \((B, D)\).
Return type:: Tensor
Returns:: tensor with the point.

Example

>>> p0 = torch.tensor([0.0, 0.0])
>>> p1 = torch.tensor([1.0, 1.0])
>>> l = ParametrizedLine.through(p0, p1)
>>> p2 = l.point_at(0.1)

projection(point)[source]#

Return the projection of a point onto the line.

Parameters:: point (Tensor) – the point to be projected.
Return type:: Tensor

squared_distance(point)[source]#

Return the squared distance of a point to its projection onto the line.

Parameters:: point (Tensor) – the point to calculate the distance onto the line.
Return type:: Tensor

classmethod through(p0, p1)[source]#

Construct a parametrized line going from a point \(p0\) to \(p1\).

Parameters:

p0 (Tensor) – tensor with first point \((B, D)\) where D is the point dimension.
p1 (Tensor) – tensor with second point \((B, D)\) where D is the point dimension.

Raises:

ValueCheckError – if p0 and p1 coincide, so the line has no direction.

Return type:

ParametrizedLine

Example

>>> p0 = torch.tensor([0.0, 0.0])
>>> p1 = torch.tensor([1.0, 1.0])
>>> l = ParametrizedLine.through(p0, p1)

kornia.geometry.ray.Ray is an alias of ParametrizedLine.

kornia.geometry.line.fit_line(points, weights=None)[source]#

Fit a line from a set of points by total least squares.

Convention:

Returns a ParametrizedLine (see its conventions) through the centroid of the points, weighted when weights are given, whose unit direction minimises the (weighted) sum of squared perpendicular distances to the points, for every dimensionality. Each batch row is fitted on its own.
For 2-D points the direction is computed in closed form and has a non-negative x component, so an exactly vertical line gets the direction (0, 1) up to rounding. For \(D \ge 3\) it is the principal direction of the scatter matrix, whose sign is not specified.

Parameters:

points (Tensor) – tensor containing a batch of sets of n-dimensional points. The expected shape of the tensor is \((B, N, D)\).
weights (Optional[Tensor], optional) – per-point weights, used in the centroid and in the fit. The expected shape of the tensor is \((B, N)\). Default: None

Return type:

ParametrizedLine

Returns:

The fitted line, with origin and direction of shape \((B, D)\).

Raises:

ValueCheckError – if the points do not determine a line — fewer than two points, all points identical, or (with weights) a zero weight sum, a negative weight, or all points with positive weight identical.

Example

>>> points = torch.rand(2, 10, 3)
>>> weights = torch.ones(2, 10)
>>> line = fit_line(points, weights)
>>> line.direction.shape
torch.Size([2, 3])

class kornia.geometry.plane.Hyperplane(n, d)[source]#

Represent a plane in 3D space by its normal \(n\) and offset \(d\).

Convention:

The plane is \(n \cdot x + d = 0\), and signed_distance() is \(n \cdot x + d\): positive on the side the normal points to, and d at the origin. from_vector() sets \(d = -n \cdot e\). depth_from_plane_equation() takes \(n \cdot X = d\) instead: pass it -offset.
The normal must be unit for signed_distance(), abs_distance() and projection() to give Euclidean distances and the closest point. through() and fit_plane() return a unit normal; the constructor and from_vector() do not normalise it.
through() points the normal along \((p_2 - p_0) \times (p_1 - p_0)\), as Eigen’s Hyperplane::Through does: the opposite of the right-hand normal of the loop \(p_0 \to p_1 \to p_2\). Swapping two points flips it.
The normal and offset are registered module state under the keys _n and _d, so state_dict(), load_state_dict() and .to() include both tensors. As in ParametrizedLine, a floating-point tensor without autograd history becomes an nn.Parameter: a plane built from plain tensors, including the result of through() and fit_plane() on points without autograd history, has trainable parameters, and the distances and projections it returns require grad. A caller’s nn.Parameter is kept, a tensor with autograd history keeps that history, and an integer tensor is stored as a buffer (ParametrizedLine rejects one).

Parameters:

n (Vector3) – The normal vector \(n\), a Vector3.
d (Scalar) – The offset \(d\), a Scalar.

abs_distance(p)[source]#

Compute unsigned distances from points to the hyperplane.

Parameters:: p (Vector3) – Point or batch of points wrapped as Vector3. The last coordinate dimension represents (x, y, z).
Return type:: Scalar
Returns:: Scalar with non-negative distance values. Leading batch dimensions follow the broadcasted point and plane inputs.

classmethod from_vector(n, e)[source]#

Create a hyperplane from a normal and one point on the plane.

Parameters:

n (Vector3) – Normal vector \(n\) defining the plane orientation.
e (Vector3) – Point \(e\) that lies on the target plane.

Return type:

Hyperplane

Returns:

Hyperplane whose offset is chosen so that \(n^T e + d = 0\).

property normal: Vector3#

Return the vector perpendicular to the hyperplane.

Returns:: Vector3 storing the normal direction. For a 3D plane this is the vector \(n\) in \(n^T x + d = 0\).

property offset: Scalar#

Return the scalar offset in the implicit plane equation.

Returns:: Scalar containing the d term in \(n^T x + d = 0\). The value controls where the plane sits relative to the origin for the stored normal direction.

projection(p)[source]#

Project points onto the hyperplane along the normal direction.

Parameters:: p (Vector3) – Point or batch of points wrapped as Vector3.
Return type:: Vector3
Returns:: Vector3 containing the closest point on the hyperplane for each input point, preserving leading batch dimensions.

signed_distance(p)[source]#

Compute signed distances from points to the hyperplane.

The sign is determined by the stored normal vector. Points in the normal direction have positive values; points on the opposite side have negative values; points on the plane evaluate to zero.

Parameters:: p (Vector3) – Point or batch of points as Vector3, or a compatible tensor-like vector accepted by the dot-product routine.
Return type:: Scalar
Returns:: Scalar containing signed distance values for each input point.

classmethod through(p0, p1, p2=None)[source]#

Construct the 3D plane through three points.

Only the three-point form is supported: Hyperplane stores its normal as a Vector3, so it cannot represent a 2D line, and calling through with two points raises.

Parameters:

p0 (Tensor) – First point tensor, shaped (..., 3).
p1 (Tensor) – Second point tensor with the same shape as p0.
p2 (Optional[Tensor], optional) – Third point tensor with the same shape as p0. It is required; the default of None only exists so that a two-point call fails with a clear error. Default: None

Return type:

Hyperplane

Returns:

Hyperplane passing through the three points.

Raises:

BaseError – if p2 is omitted, or if the points are not (..., 3) tensors of the same shape.
ValueCheckError – if the three points are collinear (or coincide), so they do not determine a plane.

kornia.geometry.plane.fit_plane(points)[source]#

Fit a plane from a set of points using SVD.

Convention:: Returns a Hyperplane (see its conventions) through the centroid of the points, with a unit normal of unspecified sign. Each batch row is fitted on its own.

Parameters:: points (Vector3) – a tensor or a Vector3 of 3D points, of shape \((N, 3)\) or \((B, N, 3)\). Another number of coordinates raises TypeError.
Return type:: Hyperplane
Returns:: The computed hyperplane object.
Raises:: ValueCheckError – if fewer than three points are given, or the points are collinear, so they do not determine a plane.