geos::geom::LineSegment Class Reference

`#include <LineSegment.h>`

Inheritance diagram for geos::geom::LineSegment:

## Public Types

using | UnorderedSet = std::unordered_set<LineSegment, HashCode>

## Public Member Functions

| LineSegment (const Coordinate &c0, const Coordinate &c1)
| Segment end.
| LineSegment (double x0, double y0, double x1, double y1)
void | setCoordinates (const Coordinate &c0, const Coordinate &c1)
void | setCoordinates (const LineSegment &ls)
const Coordinate & | operator[] (std::size_t i) const
Coordinate & | operator[] (std::size_t i)
double | minX () const
| gets the minimum X ordinate value
double | maxX () const
| gets the maximum X ordinate value
double | minY () const
| gets the minimum Y ordinate value
double | maxY () const
| gets the maximum Y ordinate value
double | getLength () const
| Computes the length of the line segment.
bool | isHorizontal () const
bool | isVertical () const
int | orientationIndex (const LineSegment &seg) const
int | orientationIndex (const LineSegment *seg) const
int | orientationIndex (const CoordinateXY &p) const
int | orientationIndex (const Coordinate &p) const
| Determines the orientation index of a Coordinate relative to this segment.
void | reverse ()
| Reverses the direction of the line segment.
void | normalize ()
| Puts the line segment into a normalized form.
double | angle () const
CoordinateXY | midPoint () const
| Computes the midpoint of the segment.
double | distance (const LineSegment &ls) const
| Computes the distance between this line segment and another one.
double | distance (const CoordinateXY &p) const
| Computes the distance between this line segment and a point.
double | distancePerpendicular (const CoordinateXY &p) const
double | distancePerpendicularOriented (const CoordinateXY &p) const
void | pointAlong (double segmentLengthFraction, Coordinate &ret) const
| Computes the Coordinate that lies a given fraction along the line defined by this segment.
void | pointAlongOffset (double segmentLengthFraction, double offsetDistance, Coordinate &ret) const
| Computes the `Coordinate` that lies a given fraction along the line defined by this segment and offset from the segment by a given distance.
LineSegment | offset (double offsetDistance)
double | projectionFactor (const CoordinateXY &p) const
| Compute the projection factor for the projection of the point p onto this LineSegment.
double | segmentFraction (const CoordinateXY &inputPt) const
| Computes the fraction of distance (in [0.0, 1.0]) that the projection of a point occurs along this line segment.
void | project (const Coordinate &p, Coordinate &ret) const
| Compute the projection of a point onto the line determined by this line segment.
CoordinateXY | project (const CoordinateXY &p) const
bool | project (const LineSegment &seg, LineSegment &ret) const
| Project a line segment onto this line segment and return the resulting line segment.
void | closestPoint (const CoordinateXY &p, CoordinateXY &ret) const
| Computes the closest point on this line segment to another point.
bool | equalsTopo (const LineSegment &other) const
| Returns `true` if `other` is topologically equal to this LineSegment (e.g. irrespective of orientation).
std::array< Coordinate, 2 > | closestPoints (const LineSegment &line)
std::array< Coordinate, 2 > | closestPoints (const LineSegment *line)
Coordinate | intersection (const LineSegment &line) const
Coordinate | lineIntersection (const LineSegment &line) const
| Computes the intersection point of the lines defined by two segments, if there is one.
std::unique_ptr< LineString > | toGeometry (const GeometryFactory &gf) const
int | compareTo (const LineSegment &other) const
| Compares this object with the specified object for order.
std::ostream & | operator<< (std::ostream &o)
bool | operator== (const LineSegment &rhs) const
bool | operator< (const LineSegment &rhs) const
bool | operator> (const LineSegment &rhs) const

## Static Public Member Functions

static CoordinateXY | midPoint (const CoordinateXY &pt0, const CoordinateXY &pt1)

## Public Attributes

Coordinate | p0
Coordinate | p1
| Segment start.

## Detailed Description

Represents a line segment defined by two Coordinate. Provides methods to compute various geometric properties and relationships of line segments.

This class is designed to be easily mutable (to the extent of having its contained points public). This supports a common pattern of reusing a single LineSegment object as a way of computing segment properties on the segments defined by arrays or lists of `Coordinate`s.

TODO: have this class keep pointers rather then real Coordinates ?

## Member Function Documentation

## angle()

double geos::geom::LineSegment::angle | ( |  | ) | const

inline

Returns
  the angle this segment makes with the x-axis (in radians)

References p1.

## closestPoint()

void geos::geom::LineSegment::closestPoint | ( | const CoordinateXY & | p,
|  | CoordinateXY & | ret ) const

Computes the closest point on this line segment to another point.

Parameters

  p | the point to find the closest point to
  ret | the Coordinate to which the closest point on the line segment to the point p will be written

## closestPoints()

std::array< Coordinate, 2 > geos::geom::LineSegment::closestPoints | ( | const LineSegment & | line | ) |

Computes the closest points on two line segments.

Parameters

  line | the line segment to find the closest points to

Returns
  a pair of Coordinates which are the closest points on the line segments.

References closestPoints(), and LineSegment().

Referenced by closestPoints().

## compareTo()

int geos::geom::LineSegment::compareTo | ( | const LineSegment & | other | ) | const

inline

Compares this object with the specified object for order.

Uses the standard lexicographic ordering for the points in the LineSegment.

Parameters

  other | the LineSegment with which this LineSegment is being compared

Returns
  a negative integer, zero, or a positive integer as this LineSegment is less than, equal to, or greater than the specified LineSegment

References LineSegment(), and p1.

## distancePerpendicular()

double geos::geom::LineSegment::distancePerpendicular | ( | const CoordinateXY & | p | ) | const

inline

Computes the perpendicular distance between the (infinite) line defined by this line segment and a point. If the segment has zero length this returns the distance between the segment and the point.

Parameters

  p | the point to compute the distance to

Returns
  the perpendicular distance between the line and point

References p1, and geos::algorithm::Distance::pointToLinePerpendicular().

## distancePerpendicularOriented()

double geos::geom::LineSegment::distancePerpendicularOriented | ( | const CoordinateXY & | p | ) | const

Computes the oriented perpendicular distance between the (infinite) line defined by this line segment and a point. The oriented distance is positive if the point on the left of the line, and negative if it is on the right. If the segment has zero length this returns the distance between the segment and the point.

Parameters

  p | the point to compute the distance to

Returns
  the oriented perpendicular distance between the line and point

## equalsTopo()

bool geos::geom::LineSegment::equalsTopo | ( | const LineSegment & | other | ) | const

Returns `true` if `other` is topologically equal to this LineSegment (e.g. irrespective of orientation).

Parameters

  other | a `LineSegment` with which to do the comparison.

Returns
  true if other is a LineSegment with the same values for the x and y ordinates.

References LineSegment().

## intersection()

Coordinate geos::geom::LineSegment::intersection | ( | const LineSegment & | line | ) | const

Computes an intersection point between two segments, if there is one. There may be 0, 1 or many intersection points between two segments. If there are 0, null is returned. If there is 1 or more, a single one is returned (chosen at the discretion of the algorithm). If more information is required about the details of the intersection, the LineIntersector class should be used.

Parameters

  line |

Returns
  intersection if found, setNull() otherwise

References LineSegment().

## isHorizontal()

bool geos::geom::LineSegment::isHorizontal | ( |  | ) | const

inline

Tests whether the segment is horizontal.

Returns
  `true` if the segment is horizontal

References p1.

## isVertical()

bool geos::geom::LineSegment::isVertical | ( |  | ) | const

inline

Tests whether the segment is vertical.

Returns
  `true` if the segment is vertical

References p1.

## lineIntersection()

Coordinate geos::geom::LineSegment::lineIntersection | ( | const LineSegment & | line | ) | const

Computes the intersection point of the lines defined by two segments, if there is one.

There may be 0, 1 or an infinite number of intersection points between two lines. If there is a unique intersection point, it is returned. Otherwise, null is returned. If more information is required about the details of the intersection, the algorithms::LineIntersector class should be used.

Parameters

  line | a line segment defining a straight line

Returns
  intersection if found, setNull() otherwise

References LineSegment().

## midPoint()

CoordinateXY geos::geom::LineSegment::midPoint | ( |  | ) | const

inline

Computes the midpoint of the segment.

Returns
  the midpoint of the segment

References midPoint(), and p1.

Referenced by midPoint().

## normalize()

void geos::geom::LineSegment::normalize | ( |  | ) |

inline

Puts the line segment into a normalized form.

This is useful for using line segments in maps and indexes when topological equality rather than exact equality is desired.

References p1, and reverse().

## offset()

LineSegment geos::geom::LineSegment::offset | ( | double | offsetDistance | ) |

Computes the `LineSegment` that is offset from the segment by a given distance. The computed segment is offset to the left of the line if the offset distance is positive, to the right if negative.

Parameters

  offsetDistance | the distance the point is offset from the segment (positive is to the left, negative is to the right)

Returns
  a line segment offset by the specified distance

Exceptions

  IllegalStateException | if the segment has zero length

References LineSegment().

## orientationIndex() [1/3]

int geos::geom::LineSegment::orientationIndex | ( | const Coordinate & | p | ) | const

inline

Determines the orientation index of a Coordinate relative to this segment.

The orientation index is as defined in Orientation::index.

Parameters

  p | the Coordinate to compare

Returns
  1 if `p` is to the left of this segment
  -1 if `p` is to the right of this segment
  0 if `p` is collinear with this segment

See also
  Orientation::index(Coordinate, Coordinate, Coordinate)

References geos::algorithm::Orientation::index(), and p1.

## orientationIndex() [2/3]

int geos::geom::LineSegment::orientationIndex | ( | const CoordinateXY & | p | ) | const

inline

Determines the orientation index of a Coordinate relative to this segment. The orientation index is as defined in Orientation::index(Coordinate, Coordinate, Coordinate).

Parameters

  p | the coordinate to compare

Returns
  1 (LEFT) if "p" is to the left of this segment
  -1 (RIGHT) if "p" is to the right of this segment
  0 (COLLINEAR) if "p" is collinear with this segment

References geos::algorithm::Orientation::index(), and p1.

## orientationIndex() [3/3]

int geos::geom::LineSegment::orientationIndex | ( | const LineSegment & | seg | ) | const

Determines the orientation of a LineSegment relative to this segment. The concept of orientation is specified as follows: Given two line segments A and L,

- A is to the left of a segment L if A lies wholly in the closed half-plane lying to the left of L
- A is to the right of a segment L if A lies wholly in the closed half-plane lying to the right of L
- otherwise, A has indeterminate orientation relative to L. This happens if A is collinear with L or if A crosses the line determined by L.

Parameters

  seg | the LineSegment to compare

Returns
  1 if seg is to the left of this segment
  -1 if seg is to the right of this segment
  0 if seg has indeterminate orientation relative to this segment

References LineSegment(), and orientationIndex().

Referenced by orientationIndex().

## pointAlong()

void geos::geom::LineSegment::pointAlong | ( | double | segmentLengthFraction,
|  | Coordinate & | ret ) const

inline

Computes the Coordinate that lies a given fraction along the line defined by this segment.

A fraction of `0.0` returns the start point of the segment; a fraction of `1.0` returns the end point of the segment. If the fraction is < 0.0 or > 1.0 the point returned will lie before the start or beyond the end of the segment.

Parameters

  segmentLengthFraction | the fraction of the segment length along the line
  ret | will be set to the point at that distance

References p1.

## pointAlongOffset()

void geos::geom::LineSegment::pointAlongOffset | ( | double | segmentLengthFraction,
|  | double | offsetDistance,
|  | Coordinate & | ret ) const

Computes the `Coordinate` that lies a given fraction along the line defined by this segment and offset from the segment by a given distance.

A fraction of `0.0` offsets from the start point of the segment; a fraction of `1.0` offsets from the end point of the segment.

The computed point is offset to the left of the line if the offset distance is positive, to the right if negative.

Parameters

  segmentLengthFraction | the fraction of the segment length along the line
  offsetDistance | the distance the point is offset from the segment (positive is to the left, negative is to the right)
  ret | will be set to the point at that distance and offset

Exceptions

  IllegalStateException | if the segment has zero length

## project() [1/2]

void geos::geom::LineSegment::project | ( | const Coordinate & | p,
|  | Coordinate & | ret ) const

Compute the projection of a point onto the line determined by this line segment.

Note that the projected point may lie outside the line segment. If this is the case, the projection factor will lie outside the range [0.0, 1.0].

References project().

Referenced by project().

## project() [2/2]

bool geos::geom::LineSegment::project | ( | const LineSegment & | seg,
|  | LineSegment & | ret ) const

Project a line segment onto this line segment and return the resulting line segment.

The returned line segment will be a subset of the target line line segment. This subset may be null, if the segments are oriented in such a way that there is no projection.

Note that the returned line may have zero length (i.e. the same endpoints). This can happen for instance if the lines are perpendicular to one another.

Parameters

  seg | the line segment to project
  ret | the projected line segment

Returns
  true if there is an overlap, false otherwise

References LineSegment().

## projectionFactor()

double geos::geom::LineSegment::projectionFactor | ( | const CoordinateXY & | p | ) | const

Compute the projection factor for the projection of the point p onto this LineSegment.

The projection factor is the constant r by which the vector for this segment must be multiplied to equal the vector for the projection of p on the line defined by this segment.

The projection factor returned will be in the range (-inf, +inf)

Parameters

  p | the point to compute the factor for

Returns
  the projection factor for the point

## segmentFraction()

double geos::geom::LineSegment::segmentFraction | ( | const CoordinateXY & | inputPt | ) | const

Computes the fraction of distance (in [0.0, 1.0]) that the projection of a point occurs along this line segment.

If the point is beyond either ends of the line segment, the closest fractional value (0.0 or 1.0) is returned.

Essentially, this is the `projectionFactor` clamped to the range [0.0, 1.0].

Parameters

  inputPt | the point

Returns
  the fraction along the line segment the projection of the point occurs

## toGeometry()

std::unique_ptr< LineString > geos::geom::LineSegment::toGeometry | ( | const GeometryFactory & | gf | ) | const

Creates a LineString with the same coordinates as this segment

Parameters

  gf | the geometery factory to use

Returns
  a LineString with the same geometry as this segment

The documentation for this class was generated from the following file:

- LineSegment.h