java.lang.Object

org.djutils.draw.line.PolyLine2d

org.opentrafficsim.base.geometry.OtsLine2d

All Implemented Interfaces:: Serializable, nl.tudelft.simulation.dsol.animation.Locatable, org.djutils.draw.Drawable<org.djutils.draw.point.Point2d>, org.djutils.draw.Drawable2d, org.djutils.draw.line.PolyLine<org.djutils.draw.line.PolyLine2d,org.djutils.draw.point.Point2d,org.djutils.draw.line.Ray2d,org.djutils.draw.line.LineSegment2d>, org.djutils.draw.line.Project<org.djutils.draw.point.Point2d>

Direct Known Subclasses:: DirectionalPolyLine

public class OtsLine2d extends org.djutils.draw.line.PolyLine2d implements nl.tudelft.simulation.dsol.animation.Locatable, Serializable

This class supports fractional projection, radius, and has location methods .

Copyright (c) 2013-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
BSD-style license. See OpenTrafficSim License.

Author:

Alexander Verbraeck, Peter Knoppers, Guus Tamminga, Wouter Schakel

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type

Class

Description

static enum

OtsLine2d.FractionalFallback

Fallback method for when fractional projection fails as the point is beyond the line or from numerical limitations.

Nested classes/interfaces inherited from interface org.djutils.draw.line.PolyLine
org.djutils.draw.line.PolyLine.TransitionFunction
Field Summary

Fields inherited from interface org.djutils.draw.line.PolyLine
DEFAULT_CIRCLE_PRECISION, DEFAULT_OFFSET_FILTER_RATIO, DEFAULT_OFFSET_MAXIMUM_FILTER_VALUE, DEFAULT_OFFSET_MINIMUM_FILTER_VALUE, DEFAULT_OFFSET_PRECISION
Constructor Summary

Constructors

Constructor

Description

OtsLine2d(Iterator<org.djutils.draw.point.Point2d> line2d)

Creates a new OtsLine2d based on point iterator.

OtsLine2d(List<org.djutils.draw.point.Point2d> pointList)

Construct a new OtsLine2d from a List<OtsPoint3d>.

OtsLine2d(org.djutils.draw.line.PolyLine2d line2d)

Creates a new OtsLine2d based on 2d information.

OtsLine2d(org.djutils.draw.point.Point2d... points)

Construct a new OtsLine2d.
Method Summary

Modifier and Type

Method

Description

static OtsLine2d

concatenate(double toleranceSI, OtsLine2d... lines)

Concatenate several OtsLine2d instances.

static OtsLine2d

concatenate(double toleranceSI, OtsLine2d line1, OtsLine2d line2)

Concatenate two OtsLine2d instances.

static OtsLine2d

concatenate(OtsLine2d... lines)

Concatenate several OtsLine2d instances.

final OtsLine2d

extract(double start, double end)

Create a new OtsLine2d that covers a sub-section of this OtsLine2d.

final OtsLine2d

extract(org.djunits.value.vdouble.scalar.Length start, org.djunits.value.vdouble.scalar.Length end)

Create a new OtsLine2d that covers a sub-section of this OtsLine2d.

OtsLine2d

extractFractional(double start, double end)

Construct a new OtsLine2d covering the indicated fraction of this OtsLine2d.

final org.djutils.draw.point.Point2d

getCentroid()

Retrieve the centroid of this OtsLine2d.

org.djutils.draw.point.Point2d

getLocation()

final org.djutils.draw.point.OrientedPoint2d

getLocation(org.djunits.value.vdouble.scalar.Length position)

Get the location at a position on the line, with its direction.

final org.djutils.draw.point.OrientedPoint2d

getLocationExtended(org.djunits.value.vdouble.scalar.Length position)

Get the location at a position on the line, with its direction.

final org.djutils.draw.point.OrientedPoint2d

getLocationExtendedSI(double positionSI)

Get the location at a position on the line, with its direction.

final org.djutils.draw.point.OrientedPoint2d

getLocationPointFraction(double fraction)

Get the location at a fraction of the line, with its direction.

final org.djutils.draw.point.OrientedPoint2d

getLocationPointFraction(double fraction, double tolerance)

Get the location at a fraction of the line, with its direction.

final org.djutils.draw.point.OrientedPoint2d

getLocationPointFractionExtended(double fraction)

Get the location at a fraction of the line (or outside the line), with its direction.

final org.djutils.draw.point.OrientedPoint2d

getLocationSI(double positionSI)

Get the location at a position on the line, with its direction.

org.djunits.value.vdouble.scalar.Length

getProjectedRadius(double fraction)

Returns the projected directional radius of the line at a given fraction.

org.djunits.value.vdouble.scalar.Length

getProjectedVertexRadius(int index)

Calculates the directional radius at a vertex.

final org.djunits.value.vdouble.scalar.Length

getTypedLength()

Return the length of this OtsLine2d in meters.

double

getVertexFraction(int index)

Returns the length fraction at the vertex.

final OtsLine2d

offsetLine(double offset)

Construct parallel line.

final OtsLine2d

offsetLine(double[] relativeFractions, double[] offsets)

Create a line at linearly varying offset from this line.

final OtsLine2d

offsetLine(double offsetAtStart, double offsetAtEnd)

Create a line at linearly varying offset from this line.

final double

projectFractional(org.djunits.value.vdouble.scalar.Direction start, org.djunits.value.vdouble.scalar.Direction end, double x, double y, OtsLine2d.FractionalFallback fallback)

Returns the fractional projection of a point to a line.

final double

projectOrthogonalSnap(double x, double y)

Returns the fractional position along this line of the orthogonal projection of point (x, y) on this line.

final OtsLine2d

reverse()

Construct a new OtsLine2d with all points of this OtsLine2d in reverse order.

final OtsLine2d

truncate(double lengthSI)

Truncate a line at the given length (less than the length of the line, and larger than zero) and return a new line.

Methods inherited from class org.djutils.draw.line.PolyLine2d
closestPointOnPolyLine, concatenate, concatenate, concatenate, equals, get, getBounds, getLength, getLocation, getLocationExtended, getPoints, getSegment, getX, getY, hashCode, instantiate, iteratorToList, lengthAtIndex, makeArray, noiseFilteredLine, offsetLine, offsetLine, projectOrthogonal, projectOrthogonalExtended, projectOrthogonalFractional, projectOrthogonalFractionalExtended, projectRay, size, toExcel, toPath2D, toPlot, toString, toString, transitionLine

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.djutils.draw.Drawable
getPointList, toString, toString

Methods inherited from interface org.djutils.draw.Drawable2d
getDimensions

Methods inherited from interface nl.tudelft.simulation.dsol.animation.Locatable
getBounds, getDirZ, getZ

Methods inherited from interface org.djutils.draw.line.PolyLine
find, getFirst, getLast, getLocationFraction, getLocationFraction, getLocationFractionExtended

Constructor Details
- OtsLine2d
  
  public OtsLine2d(org.djutils.draw.point.Point2d... points)
  
  Construct a new OtsLine2d.
  
  Parameters:
  
  points - the array of points to construct this OtsLine2d from.
- OtsLine2d
  
  public OtsLine2d(org.djutils.draw.line.PolyLine2d line2d)
  
  Creates a new OtsLine2d based on 2d information.
  
  Parameters:
  
  line2d - 2d information.
- OtsLine2d
  
  public OtsLine2d(Iterator<org.djutils.draw.point.Point2d> line2d)
  
  Creates a new OtsLine2d based on point iterator.
  
  Parameters:
  
  line2d - point iterator.
- OtsLine2d
  
  public OtsLine2d(List<org.djutils.draw.point.Point2d> pointList)
  
  Construct a new OtsLine2d from a List<OtsPoint3d>.
  
  Parameters:
  
  pointList - the list of points to construct this OtsLine2d from.
Method Details
- offsetLine
  
  public final OtsLine2d offsetLine(double offset)
  
  Construct parallel line.
  
  Specified by:
  
  offsetLine in interface org.djutils.draw.line.PolyLine<org.djutils.draw.line.PolyLine2d,org.djutils.draw.point.Point2d,org.djutils.draw.line.Ray2d,org.djutils.draw.line.LineSegment2d>
  
  Parameters:
  
  offset - offset distance from the reference line; positive is LEFT, negative is RIGHT
  
  Returns:
  
  the line that has the specified offset from the reference line
- offsetLine
  
  public final OtsLine2d offsetLine(double offsetAtStart, double offsetAtEnd)
  
  Create a line at linearly varying offset from this line. The offset may change linearly from its initial value at the start of the reference line to its final offset value at the end of the reference line.
  
  Specified by:
  
  offsetLine in interface org.djutils.draw.line.PolyLine<org.djutils.draw.line.PolyLine2d,org.djutils.draw.point.Point2d,org.djutils.draw.line.Ray2d,org.djutils.draw.line.LineSegment2d>
  
  Parameters:
  
  offsetAtStart - offset at the start of the reference line (positive value is Left, negative value is Right)
  
  offsetAtEnd - offset at the end of the reference line (positive value is Left, negative value is Right)
  
  Returns:
  
  the OtsLine2d of the line at linearly changing offset of the reference line
- offsetLine
  
  public final OtsLine2d offsetLine(double[] relativeFractions, double[] offsets)
  
  Create a line at linearly varying offset from this line. The offset may change linearly from its initial value at the start of the reference line via a number of intermediate offsets at intermediate positions to its final offset value at the end of the reference line.
  
  Parameters:
  
  relativeFractions - positional fractions for which the offsets have to be generated
  
  offsets - offsets at the relative positions (positive value is Left, negative value is Right)
  
  Returns:
  
  the Geometry of the line at linearly changing offset of the reference line
- concatenate
  
  public static OtsLine2d concatenate(OtsLine2d... lines)
  
  Concatenate several OtsLine2d instances.
  
  Parameters:
  
  lines - OtsLine2d... one or more OtsLine2d. The last point of the first <strong>must</strong> match the first of the second, etc.
  
  Returns:
  
  OtsLine2d
- concatenate
  
  public static OtsLine2d concatenate(double toleranceSI, OtsLine2d line1, OtsLine2d line2)
  
  Concatenate two OtsLine2d instances. This method is separate for efficiency reasons.
  
  Parameters:
  
  toleranceSI - the tolerance between the end point of a line and the first point of the next line
  
  line1 - first line
  
  line2 - second line
  
  Returns:
  
  OtsLine2d
- concatenate
  
  public static OtsLine2d concatenate(double toleranceSI, OtsLine2d... lines)
  
  Concatenate several OtsLine2d instances.
  
  Parameters:
  
  toleranceSI - the tolerance between the end point of a line and the first point of the next line
  
  lines - OtsLine2d... one or more OtsLine2d. The last point of the first <strong>must</strong> match the first of the second, etc.
  
  Returns:
  
  OtsLine2d
- reverse
  
  public final OtsLine2d reverse()
  
  Construct a new OtsLine2d with all points of this OtsLine2d in reverse order.
  
  Specified by:
  
  reverse in interface org.djutils.draw.line.PolyLine<org.djutils.draw.line.PolyLine2d,org.djutils.draw.point.Point2d,org.djutils.draw.line.Ray2d,org.djutils.draw.line.LineSegment2d>
  
  Returns:
  
  the new OtsLine2d
- extractFractional
  
  public OtsLine2d extractFractional(double start, double end)
  
  Construct a new OtsLine2d covering the indicated fraction of this OtsLine2d.
  
  Specified by:
  
  extractFractional in interface org.djutils.draw.line.PolyLine<org.djutils.draw.line.PolyLine2d,org.djutils.draw.point.Point2d,org.djutils.draw.line.Ray2d,org.djutils.draw.line.LineSegment2d>
  
  Parameters:
  
  start - starting point, valid range [0..end)
  
  end - ending point, valid range (start..1]
  
  Returns:
  
  the new OtsLine2d
- extract
  
  public final OtsLine2d extract(org.djunits.value.vdouble.scalar.Length start, org.djunits.value.vdouble.scalar.Length end)
  
  Create a new OtsLine2d that covers a sub-section of this OtsLine2d.
  
  Parameters:
  
  start - the length along this OtsLine2d where the sub-section starts, valid range [0..end)
  
  end - length along this OtsLine2d where the sub-section ends, valid range (start..length (length is the length of this OtsLine2d)
  
  Returns:
  
  the selected sub-section
- extract
  
  public final OtsLine2d extract(double start, double end)
  
  Create a new OtsLine2d that covers a sub-section of this OtsLine2d.
  
  Specified by:
  
  extract in interface org.djutils.draw.line.PolyLine<org.djutils.draw.line.PolyLine2d,org.djutils.draw.point.Point2d,org.djutils.draw.line.Ray2d,org.djutils.draw.line.LineSegment2d>
  
  Overrides:
  
  extract in class org.djutils.draw.line.PolyLine2d
  
  Parameters:
  
  start - length along this OtsLine2d where the sub-section starts, valid range [0..end)
  
  end - length along this OtsLine2d where the sub-section ends, valid range (start..length (length is the length of this OtsLine2d)
  
  Returns:
  
  the selected sub-section
- getTypedLength
  
  public final org.djunits.value.vdouble.scalar.Length getTypedLength()
  
  Return the length of this OtsLine2d in meters. (Assuming that the coordinates of the points constituting this line are expressed in meters.)
  
  Returns:
  
  the length of the line
- getLocationExtended
  
  public final org.djutils.draw.point.OrientedPoint2d getLocationExtended(org.djunits.value.vdouble.scalar.Length position)
  
  Get the location at a position on the line, with its direction. Position can be below 0 or more than the line length. In that case, the position will be extrapolated in the direction of the line at its start or end.
  
  Parameters:
  
  position - the position on the line for which to calculate the point on, before, of after the line
  
  Returns:
  
  a directed point
- getLocationExtendedSI
  
  public final org.djutils.draw.point.OrientedPoint2d getLocationExtendedSI(double positionSI)
  
  Get the location at a position on the line, with its direction. Position can be below 0 or more than the line length. In that case, the position will be extrapolated in the direction of the line at its start or end.
  
  Parameters:
  
  positionSI - the position on the line for which to calculate the point on, before, of after the line, in SI units
  
  Returns:
  
  a directed point
- getLocationPointFraction
  
  public final org.djutils.draw.point.OrientedPoint2d getLocationPointFraction(double fraction) throws org.djutils.draw.DrawRuntimeException
  
  Get the location at a fraction of the line, with its direction. Fraction should be between 0.0 and 1.0.
  
  Parameters:
  
  fraction - the fraction for which to calculate the point on the line
  
  Returns:
  
  a directed point
  
  Throws:
  
  org.djutils.draw.DrawRuntimeException - when fraction less than 0.0 or more than 1.0.
- getLocationPointFraction
  
  public final org.djutils.draw.point.OrientedPoint2d getLocationPointFraction(double fraction, double tolerance) throws org.djutils.draw.DrawRuntimeException
  
  Get the location at a fraction of the line, with its direction. Fraction should be between 0.0 and 1.0.
  
  Parameters:
  
  fraction - the fraction for which to calculate the point on the line
  
  tolerance - the delta from 0.0 and 1.0 that will be forgiven
  
  Returns:
  
  a directed point
  
  Throws:
  
  org.djutils.draw.DrawRuntimeException - when fraction less than 0.0 or more than 1.0.
- getLocationPointFractionExtended
  
  public final org.djutils.draw.point.OrientedPoint2d getLocationPointFractionExtended(double fraction)
  
  Get the location at a fraction of the line (or outside the line), with its direction.
  
  Parameters:
  
  fraction - the fraction for which to calculate the point on the line
  
  Returns:
  
  a directed point
- getLocation
  
  public final org.djutils.draw.point.OrientedPoint2d getLocation(org.djunits.value.vdouble.scalar.Length position) throws org.djutils.draw.DrawRuntimeException
  
  Get the location at a position on the line, with its direction. Position should be between 0.0 and line length.
  
  Parameters:
  
  position - the position on the line for which to calculate the point on the line
  
  Returns:
  
  a directed point
  
  Throws:
  
  org.djutils.draw.DrawRuntimeException - when position less than 0.0 or more than line length.
- getLocationSI
  
  public final org.djutils.draw.point.OrientedPoint2d getLocationSI(double positionSI) throws org.djutils.draw.DrawRuntimeException
  
  Get the location at a position on the line, with its direction. Position should be between 0.0 and line length.
  
  Parameters:
  
  positionSI - the position on the line for which to calculate the point on the line
  
  Returns:
  
  a directed point
  
  Throws:
  
  org.djutils.draw.DrawRuntimeException - when position less than 0.0 or more than line length.
- truncate
  
  public final OtsLine2d truncate(double lengthSI)
  
  Truncate a line at the given length (less than the length of the line, and larger than zero) and return a new line.
  
  Specified by:
  
  truncate in interface org.djutils.draw.line.PolyLine<org.djutils.draw.line.PolyLine2d,org.djutils.draw.point.Point2d,org.djutils.draw.line.Ray2d,org.djutils.draw.line.LineSegment2d>
  
  Overrides:
  
  truncate in class org.djutils.draw.line.PolyLine2d
  
  Parameters:
  
  lengthSI - the location where to truncate the line
  
  Returns:
  
  a new OtsLine2d truncated at the exact position where line.getLength() == lengthSI
- projectOrthogonalSnap
  
  public final double projectOrthogonalSnap(double x, double y)
  
  Returns the fractional position along this line of the orthogonal projection of point (x, y) on this line. If the point is not orthogonal to the closest line segment, the nearest point is selected.
  
  Parameters:
  
  x - x-coordinate of point to project
  
  y - y-coordinate of point to project
  
  Returns:
  
  fractional position along this line of the orthogonal projection on this line of a point
- projectFractional
  
  public final double projectFractional(org.djunits.value.vdouble.scalar.Direction start, org.djunits.value.vdouble.scalar.Direction end, double x, double y, OtsLine2d.FractionalFallback fallback)
  Returns the fractional projection of a point to a line. The projection works by taking slices in space per line segment as shown below. A point is always projected to the nearest segment, but not necessarily to the closest point on that segment. The slices in space are analogous to a Voronoi diagram, but for the line segments instead of points. If fractional projection fails, a fallback projection is returned.
  
  The point 'A' is projected to point 'B' on the 3rd segment of line 'C-D'. The line from 'A' to 'B' extends towards point 'E', which is the intersection of lines 'E-F' and 'E-G'. Line 'E-F' cuts the first bend of the 3rd segment (at point 'H') in half, while the line 'E-G' cuts the second bend of the 3rd segment (at point 'I') in half.
  ____________________________ G . . | | . . . | . . . . helper lines | . . . | _.._.._ projection line | I. . . |____________________________| _.'._ . L F. _.' . '-. . .. B _.' . '-. . . _.\ . . D . . _.' : . . J . . _.' \ . . .. . _.' : . M . . ..-' \ . . . /H. A . . . / . . C _________/ . . . . . . K . . . . . . . . . . . . N . . . . . . . . . . . . . . . . . .E . . . . . .
  Fractional projection may fail in three cases.
  
  Numerical difficulties at slight bend, orthogonal projection returns the correct point.
  
  Fractional projection is possible only to segments that aren't the nearest segment(s).
  
  Fractional projection is possible for no segment.
  
  In the latter two cases the projection is undefined and the provided fallback is used to provide a point.
  Parameters:
  
  start - direction in first point
  
  end - direction in last point
  
  x - x-coordinate of point to project
  
  y - y-coordinate of point to project
  
  fallback - fallback method for when fractional projection fails
  
  Returns:
  
  fractional position along this line of the fractional projection on that line of a point
- getProjectedRadius
  
  public org.djunits.value.vdouble.scalar.Length getProjectedRadius(double fraction) throws IllegalArgumentException
  
  Returns the projected directional radius of the line at a given fraction. Negative values reflect right-hand curvature in the design-line direction. The radius is taken as the minimum of the radii at the vertices before and after the given fraction. The radius at a vertex is calculated as the radius of a circle that is equidistant from both edges connected to the vertex. The circle center is on a line perpendicular to the shortest edge, crossing through the middle of the shortest edge. This method ignores Z components.
  
  Parameters:
  
  fraction - fraction along the line, between 0.0 and 1.0 (both inclusive)
  
  Returns:
  
  radius; the local radius; or si field set to Double.NaN if line is totally straight
  
  Throws:
  
  IllegalArgumentException - fraction out of bounds
- getProjectedVertexRadius
  
  public org.djunits.value.vdouble.scalar.Length getProjectedVertexRadius(int index) throws IndexOutOfBoundsException
  
  Calculates the directional radius at a vertex. Negative values reflect right-hand curvature in the design-line direction. The radius at a vertex is calculated as the radius of a circle that is equidistant from both edges connected to the vertex. The circle center is on a line perpendicular to the shortest edge, crossing through the middle of the shortest edge. This function ignores Z components.
  
  Parameters:
  
  index - index of the vertex in range [1 ... size() - 2]
  
  Returns:
  
  radius at the vertex
  
  Throws:
  
  IndexOutOfBoundsException - if the index is out of bounds
- getVertexFraction
  
  public double getVertexFraction(int index) throws IndexOutOfBoundsException
  
  Returns the length fraction at the vertex.
  
  Parameters:
  
  index - index of vertex [0 ... size() - 1]
  
  Returns:
  
  length fraction at the vertex
  
  Throws:
  
  IndexOutOfBoundsException - if the index is out of bounds
- getCentroid
  
  public final org.djutils.draw.point.Point2d getCentroid()
  
  Retrieve the centroid of this OtsLine2d.
  
  Returns:
  
  the centroid of this OtsLine2d
- getLocation
  
  public org.djutils.draw.point.Point2d getLocation()
  
  Specified by:
  
  getLocation in interface nl.tudelft.simulation.dsol.animation.Locatable

Class OtsLine2d

Nested Class Summary

Nested classes/interfaces inherited from interface org.djutils.draw.line.PolyLine

Field Summary

Fields inherited from interface org.djutils.draw.line.PolyLine

Constructor Summary

Method Summary

Methods inherited from class org.djutils.draw.line.PolyLine2d

Methods inherited from class java.lang.Object

Methods inherited from interface org.djutils.draw.Drawable

Methods inherited from interface org.djutils.draw.Drawable2d

Methods inherited from interface nl.tudelft.simulation.dsol.animation.Locatable

Methods inherited from interface org.djutils.draw.line.PolyLine

Constructor Details

OtsLine2d

OtsLine2d

OtsLine2d

OtsLine2d

Method Details

offsetLine

offsetLine

offsetLine

concatenate

concatenate

concatenate

reverse

extractFractional

extract

extract

getTypedLength

getLocationExtended

getLocationExtendedSI

getLocationPointFraction

getLocationPointFraction

getLocationPointFractionExtended

getLocation

getLocationSI

truncate

projectOrthogonalSnap

projectFractional

getProjectedRadius

getProjectedVertexRadius

getVertexFraction

getCentroid

getLocation