us.ihmc.euclid.geometry.interfaces

Interface LineSegment3DReadOnly

All Known Subinterfaces:

FixedFrameLineSegment3DBasics, FrameLineSegment3DBasics, FrameLineSegment3DReadOnly, LineSegment3DBasics

All Known Implementing Classes:

FrameLineSegment3D, LineSegment3D

public interface LineSegment3DReadOnly

Read-only interface for a line segment 3D.

A line segment 3D is a finite-length line defined in the XY-plane by its two 3D endpoints.

Method Summary

Modifier and Type	Method and Description
default double	distance(LineSegment3DReadOnly otherLineSegment) This methods computes the minimum distance between this line segment and the given one.
default double	distance(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly point) Returns the minimum distance between a point and this given line segment.
default double	distanceSquared(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly point) Returns the square of the minimum distance between a point and this given line segment.
default double	dotProduct(LineSegment3DReadOnly other) Computes the dot product of this line segment with the other line segment such that: this · other = Math.cos(α) * this.length() * other.length() where α is the angle from this to the other line segment.
default boolean	epsilonEquals(LineSegment3DReadOnly other, double epsilon) Tests on a per-component basis on both endpoints if this line segment is equal to other with the tolerance epsilon.
default boolean	equals(LineSegment3DReadOnly other) Tests on a per component basis, if this line segment 3D is exactly equal to other.
default boolean	firstEndpointContainsNaN() Test if the first endpoint of this line segment contains Double.NaN.
default boolean	geometricallyEquals(LineSegment3DReadOnly other, double epsilon) Compares this to other to determine if the two line segments are geometrically similar.
default void	get(us.ihmc.euclid.tuple3D.interfaces.Point3DBasics firstEndpointToPack, us.ihmc.euclid.tuple3D.interfaces.Point3DBasics secondEndpointToPack) Gets the endpoints defining this line segment by storing their coordinates in the given arguments.
default us.ihmc.euclid.tuple3D.interfaces.Vector3DBasics	getDirection(boolean normalize) Computes the vector going from the first to the second endpoint of this line segment.
default void	getDirection(boolean normalize, us.ihmc.euclid.tuple3D.interfaces.Vector3DBasics directionToPack) Computes the vector going from the first to the second endpoint of this line segment.
us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly	getFirstEndpoint() Gets the read-only reference to the first endpoint of this line segment.
default double	getFirstEndpointX() Gets the x-coordinate of the first endpoint defining this line segment.
default double	getFirstEndpointY() Gets the y-coordinate of the first endpoint defining this line segment.
default double	getFirstEndpointZ() Gets the z-coordinate of the first endpoint defining this line segment.
us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly	getSecondEndpoint() Gets the read-only reference to the second endpoint of this line segment.
default double	getSecondEndpointX() Gets the x-coordinate of the second endpoint defining this line segment.
default double	getSecondEndpointY() Gets the y-coordinate of the second endpoint defining this line segment.
default double	getSecondEndpointZ() Gets the z-coordinate of the second endpoint defining this line segment.
default boolean	isBetweenEndpoints(double x, double y, double z, double epsilon) Tests whether the projection of the given point onto this line segment is located between the two endpoints with a given conservative tolerance epsilon: if epsilon > 0, the point has to be between the endpoints and at a minimum distance of epsilon * this.length() from the closest endpoint.
default boolean	isBetweenEndpoints(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly point) Tests whether the projection of the given point onto this line segment is located between the two endpoints or exactly on an endpoint.
default boolean	isBetweenEndpoints(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly point, double epsilon) Tests whether the projection of the given point onto this line segment is located between the two endpoints with a given conservative tolerance epsilon: if epsilon > 0, the point has to be between the endpoints and at a minimum distance of epsilon * this.length() from the closest endpoint.
default double	length() Computes the length of this line segment.
default double	lengthSquared() Computes the squared value of the length of this line segment.
default us.ihmc.euclid.tuple3D.interfaces.Point3DBasics	midpoint() Computes and returns the coordinates of the point located exactly at the middle of this line segment.
default void	midpoint(us.ihmc.euclid.tuple3D.interfaces.Point3DBasics midpointToPack) Computes the coordinates of the point located exactly at the middle of this line segment.
default boolean	orthogonalProjection(us.ihmc.euclid.tuple3D.interfaces.Point3DBasics pointToProject) Computes the orthogonal projection of a 3D point on this 3D line segment.
default boolean	orthogonalProjection(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointToProject, us.ihmc.euclid.tuple3D.interfaces.Point3DBasics projectionToPack) Computes the orthogonal projection of a 3D point on this 3D line segment.
default us.ihmc.euclid.tuple3D.interfaces.Point3DBasics	orthogonalProjectionCopy(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointToProject) Computes the orthogonal projection of a 3D point on this 3D line segment.
default double	percentageAlongLineSegment(double x, double y, double z) Computes a percentage along the line segment representing the location of the given point once projected onto this line segment.
default double	percentageAlongLineSegment(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly point) Computes a percentage along the line segment representing the location of the given point once projected onto this line segment.
default us.ihmc.euclid.tuple3D.interfaces.Point3DBasics	pointBetweenEndpointsGivenPercentage(double percentage) Computes the coordinates of the point located at a given percentage on this line segment: pointToPack.interpolate(firstEndpoint, secondEndpoint, percentage)
default void	pointBetweenEndpointsGivenPercentage(double percentage, us.ihmc.euclid.tuple3D.interfaces.Point3DBasics pointToPack) Computes the coordinates of the point located at a given percentage on this line segment: pointToPack.interpolate(firstEndpoint, secondEndpoint, percentage)
default us.ihmc.euclid.tuple3D.interfaces.Point3DBasics	pointOnLineGivenPercentage(double percentage) Computes the coordinates of the point located on the line this line segment is lying on: pointToPack.interpolate(firstEndpoint, secondEndpoint, percentage)
default void	pointOnLineGivenPercentage(double percentage, us.ihmc.euclid.tuple3D.interfaces.Point3DBasics pointToPack) Computes the coordinates of the point located on the line this line segment is lying on: pointToPack.interpolate(firstEndpoint, secondEndpoint, percentage)
default boolean	secondEndpointContainsNaN() Test if the second endpoint of this line segment contains Double.NaN.

Method Detail

getFirstEndpoint

us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly getFirstEndpoint()

Gets the read-only reference to the first endpoint of this line segment.

Returns:

the reference to the first endpoint of this line segment.

getSecondEndpoint

us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly getSecondEndpoint()

Gets the read-only reference to the second endpoint of this line segment.

Returns:

the reference to the second endpoint of this line segment.

get

default void get(us.ihmc.euclid.tuple3D.interfaces.Point3DBasics firstEndpointToPack,
                 us.ihmc.euclid.tuple3D.interfaces.Point3DBasics secondEndpointToPack)

Gets the endpoints defining this line segment by storing their coordinates in the given arguments.

Parameters:

firstEndpointToPack - point in which the coordinates of this line segment's first endpoint are stored. Modified.

secondEndpointToPack - point in which the coordinates of this line segment's second endpoint are stored. Modified.

getFirstEndpointX

default double getFirstEndpointX()

Gets the x-coordinate of the first endpoint defining this line segment.

Returns:

the first endpoint x-coordinate.

getFirstEndpointY

default double getFirstEndpointY()

Gets the y-coordinate of the first endpoint defining this line segment.

Returns:

the first endpoint y-coordinate.

getFirstEndpointZ

default double getFirstEndpointZ()

Gets the z-coordinate of the first endpoint defining this line segment.

Returns:

the first endpoint z-coordinate.

getSecondEndpointX

default double getSecondEndpointX()

Gets the x-coordinate of the second endpoint defining this line segment.

Returns:

the first endpoint x-coordinate.

getSecondEndpointY

default double getSecondEndpointY()

Gets the y-coordinate of the second endpoint defining this line segment.

Returns:

the first endpoint y-coordinate.

getSecondEndpointZ

default double getSecondEndpointZ()

Gets the z-coordinate of the second endpoint defining this line segment.

Returns:

the first endpoint z-coordinate.

firstEndpointContainsNaN

default boolean firstEndpointContainsNaN()

Test if the first endpoint of this line segment contains Double.NaN.

Returns:

true if getFirstEndpoint() contains Double.NaN, false otherwise.

secondEndpointContainsNaN

default boolean secondEndpointContainsNaN()

Test if the second endpoint of this line segment contains Double.NaN.

Returns:

true if getSecondEndpoint() contains Double.NaN, false otherwise.

length

default double length()

Computes the length of this line segment.

Returns:

the length of this line segment.

lengthSquared

default double lengthSquared()

Computes the squared value of the length of this line segment.

Returns:

the length squared of this line segment.

distanceSquared

default double distanceSquared(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly point)

Returns the square of the minimum distance between a point and this given line segment.

Edge cases:

• if this.lengthSquared() < EuclidGeometryTools.ONE_TRILLIONTH, this method returns the distance between firstEndpoint and the given point.

Parameters:

point - 3D point to compute the distance from this line segment. Not modified.

Returns:

the minimum distance between the 3D point and this 3D line segment.

distance

default double distance(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly point)

Returns the minimum distance between a point and this given line segment.

Edge cases:

• if this.lengthSquared() < EuclidGeometryTools.ONE_TRILLIONTH, this method returns the distance between firstEndpoint and the given point.

Parameters:

point - 3D point to compute the distance from this line segment. Not modified.

Returns:

the minimum distance between the 3D point and this 3D line segment.

distance

default double distance(LineSegment3DReadOnly otherLineSegment)

This methods computes the minimum distance between this line segment and the given one. Useful link.

Parameters:

otherLineSegment - the other line segment to compute the distance from. Not modified.

Returns:

the minimum distance between the two line segments.

orthogonalProjectionCopy

default us.ihmc.euclid.tuple3D.interfaces.Point3DBasics orthogonalProjectionCopy(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointToProject)

Computes the orthogonal projection of a 3D point on this 3D line segment.

Edge cases:

• if the length of this line segment is too small, i.e. this.lengthSquared() < EuclidGeometryTools.ONE_TRILLIONTH, this method returns firstEndpoint.
• the projection can not be outside the line segment. When the projection on the corresponding line is outside the line segment, the result is the closest of the two endpoints.

WARNING: This method generates garbage.

Parameters:

pointToProject - the point to compute the projection of. Not modified.

Returns:

the projection of the point onto the line segment or null if the method failed.

orthogonalProjection

default boolean orthogonalProjection(us.ihmc.euclid.tuple3D.interfaces.Point3DBasics pointToProject)

Computes the orthogonal projection of a 3D point on this 3D line segment.

Edge cases:

• if the length of this line segment is too small, i.e. this.lengthSquared() < EuclidGeometryTools.ONE_TRILLIONTH, this method returns firstEndpoint.
• the projection can not be outside the line segment. When the projection on the corresponding line is outside the line segment, the result is the closest of the two endpoints.

Parameters:

pointToProject - the point to project on this line segment. Modified.

Returns:

whether the method succeeded or not.

orthogonalProjection

default boolean orthogonalProjection(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointToProject,
                                     us.ihmc.euclid.tuple3D.interfaces.Point3DBasics projectionToPack)

Computes the orthogonal projection of a 3D point on this 3D line segment.

Edge cases:

• if the length of this line segment is too small, i.e. this.lengthSquared() < EuclidGeometryTools.ONE_TRILLIONTH, this method returns firstEndpoint.
• the projection can not be outside the line segment. When the projection on the corresponding line is outside the line segment, the result is the closest of the two endpoints.

Parameters:

pointToProject - the point to compute the projection of. Not modified.

projectionToPack - point in which the projection of the point onto this line segment is stored. Modified.

Returns:

whether the method succeeded or not.

pointBetweenEndpointsGivenPercentage

default us.ihmc.euclid.tuple3D.interfaces.Point3DBasics pointBetweenEndpointsGivenPercentage(double percentage)

Computes the coordinates of the point located at a given percentage on this line segment:
pointToPack.interpolate(firstEndpoint, secondEndpoint, percentage)

WARNING: This method generates garbage.

Parameters:

percentage - the percentage along this line segment of the point. Must be in [0, 1].

Returns:

the computed point.

Throws:

{@link - RuntimeException} if percentage ∉ [0, 1].

pointBetweenEndpointsGivenPercentage

default void pointBetweenEndpointsGivenPercentage(double percentage,
                                                  us.ihmc.euclid.tuple3D.interfaces.Point3DBasics pointToPack)

Computes the coordinates of the point located at a given percentage on this line segment:
pointToPack.interpolate(firstEndpoint, secondEndpoint, percentage)

Parameters:

percentage - the percentage along this line segment of the point. Must be in [0, 1].

pointToPack - where the result is stored. Modified.

Throws:

{@link - RuntimeException} if percentage ∉ [0, 1].

pointOnLineGivenPercentage

default us.ihmc.euclid.tuple3D.interfaces.Point3DBasics pointOnLineGivenPercentage(double percentage)

Computes the coordinates of the point located on the line this line segment is lying on:
pointToPack.interpolate(firstEndpoint, secondEndpoint, percentage)

WARNING: This method generates garbage.

Parameters:

percentage - the percentage along this line segment of the point.

Returns:

the computed point.

pointOnLineGivenPercentage

default void pointOnLineGivenPercentage(double percentage,
                                        us.ihmc.euclid.tuple3D.interfaces.Point3DBasics pointToPack)

Computes the coordinates of the point located on the line this line segment is lying on:
pointToPack.interpolate(firstEndpoint, secondEndpoint, percentage)

Parameters:

percentage - the percentage along this line segment of the point.

pointToPack - where the result is stored. Modified.

midpoint

default us.ihmc.euclid.tuple3D.interfaces.Point3DBasics midpoint()

Computes and returns the coordinates of the point located exactly at the middle of this line segment.

WARNING: This method generates garbage.

Returns:

the mid-point of this line segment.

midpoint

default void midpoint(us.ihmc.euclid.tuple3D.interfaces.Point3DBasics midpointToPack)

Computes the coordinates of the point located exactly at the middle of this line segment.

Parameters:

midpointToPack - point in which the mid-point of this line segment is stored. Modified.

getDirection

default void getDirection(boolean normalize,
                          us.ihmc.euclid.tuple3D.interfaces.Vector3DBasics directionToPack)

Computes the vector going from the first to the second endpoint of this line segment.

Parameters:

normalize - whether the direction vector is to be normalized.

directionToPack - vector in which the direction is stored. Modified.

getDirection

default us.ihmc.euclid.tuple3D.interfaces.Vector3DBasics getDirection(boolean normalize)

Computes the vector going from the first to the second endpoint of this line segment.

WARNING: This method generates garbage.

Parameters:

normalize - whether the direction vector is to be normalized.

Returns:

the direction of this line segment.

isBetweenEndpoints

default boolean isBetweenEndpoints(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly point)

Tests whether the projection of the given point onto this line segment is located between the two endpoints or exactly on an endpoint.

Parameters:

point - the query. Not modified.

Returns:

true if the projection of the point is between the endpoints of this line segment, false otherwise.

isBetweenEndpoints

default boolean isBetweenEndpoints(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly point,
                                   double epsilon)

Tests whether the projection of the given point onto this line segment is located between the two endpoints with a given conservative tolerance epsilon:

• if epsilon > 0, the point has to be between the endpoints and at a minimum distance of epsilon * this.length() from the closest endpoint.
• if epsilon < 0, the point has to be between the endpoints or at a maximum distance of -epsilon * this.length() from the closest endpoint.
• if epsilon = 0, the point has to be between the endpoints or equal to one of the endpoints.

Parameters:

point - the query. Not modified.

epsilon - the tolerance to use.

Returns:

true if the projection of the point is between the endpoints of this line segment, false otherwise.

isBetweenEndpoints

default boolean isBetweenEndpoints(double x,
                                   double y,
                                   double z,
                                   double epsilon)

Tests whether the projection of the given point onto this line segment is located between the two endpoints with a given conservative tolerance epsilon:

• if epsilon > 0, the point has to be between the endpoints and at a minimum distance of epsilon * this.length() from the closest endpoint.
• if epsilon < 0, the point has to be between the endpoints or at a maximum distance of -epsilon * this.length() from the closest endpoint.
• if epsilon = 0, the point has to be between the endpoints or equal to one of the endpoints.

Parameters:

x - the x-coordinate of the query point.

y - the y-coordinate of the query point.

z - the z-coordinate of the query point.

epsilon - the tolerance to use.

Returns:

true if the projection of the point is between the endpoints of this line segment, false otherwise.

percentageAlongLineSegment

default double percentageAlongLineSegment(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly point)

Computes a percentage along the line segment representing the location of the given point once projected onto this line segment. The returned percentage is in ] -∞; ∞ [, 0.0 representing firstEndpoint, and 1.0 representing secondEndpoint.

For example, if the returned percentage is 0.5, it means that the projection of the given point is located at the middle of this line segment. The coordinates of the projection of the point can be computed from the percentage as follows:
Point3D projection = new Point3D();
projection.interpolate(lineSegmentStart, lineSegmentEnd, percentage);


Edge cases:

• if the length of the given line segment is too small, i.e. this.lengthSquared() < EuclidGeometryTools.ONE_TRILLIONTH, this method fails and returns 0.0.

Parameters:

point - the query point. Not modified.

Returns:

the computed percentage along the line segment representing where the point projection is located.

percentageAlongLineSegment

default double percentageAlongLineSegment(double x,
                                          double y,
                                          double z)

Computes a percentage along the line segment representing the location of the given point once projected onto this line segment. The returned percentage is in ] -∞; ∞ [, 0.0 representing firstEndpoint, and 1.0 representing secondEndpoint.

For example, if the returned percentage is 0.5, it means that the projection of the given point is located at the middle of this line segment. The coordinates of the projection of the point can be computed from the percentage as follows:
Point3D projection = new Point3D();
projection.interpolate(lineSegmentStart, lineSegmentEnd, percentage);


Edge cases:

• if the length of the given line segment is too small, i.e. this.lengthSquared() < EuclidGeometryTools.ONE_TRILLIONTH, this method fails and returns 0.0.

Parameters:

x - the x-coordinate of the query point.

y - the y-coordinate of the query point.

z - the z-coordinate of the query point.

Returns:

the computed percentage along the line segment representing where the point projection is located.

dotProduct

default double dotProduct(LineSegment3DReadOnly other)

Computes the dot product of this line segment with the other line segment such that:
this · other = Math.cos(α) * this.length() * other.length()
where α is the angle from this to the other line segment.

Parameters:

other - the other line segment used to compute the dot product. Not modified.

Returns:

the value of the dot product.

epsilonEquals

default boolean epsilonEquals(LineSegment3DReadOnly other,
                              double epsilon)

Tests on a per-component basis on both endpoints if this line segment is equal to other with the tolerance epsilon.

Parameters:

other - the query. Not modified.

epsilon - the tolerance to use.

Returns:

true if the two line segments are equal, false otherwise.

equals

default boolean equals(LineSegment3DReadOnly other)

Tests on a per component basis, if this line segment 3D is exactly equal to other.

Parameters:

other - the other line segment 3D to compare against this. Not modified.

Returns:

true if the two line segments are exactly equal component-wise, false otherwise.

geometricallyEquals

default boolean geometricallyEquals(LineSegment3DReadOnly other,
                                    double epsilon)

Compares this to other to determine if the two line segments are geometrically similar.

The comparison is based on comparing the line segments' endpoints. Two line segments are considered geometrically equal even if they are defined with opposite direction.

Parameters:

other - the line segment to compare to. Not modified.

epsilon - the tolerance of the comparison.

Returns:

true if the two line segments represent the same geometry, false otherwise.