class Geometry · Computations

Points

Computations on points: distances, closest points on lines, segments, arcs and polylines, moving, rotating and placing points, and points of a set (centroid, bounding box, nearest).

Static methods

angleAroundstatic

static angleAround(center: Point | VectorLike, point: Point | VectorLike, result?: Real | null): Real

The angle of a point around a center, measured from the positive X axis clockwise on the screen (y pointing down), in [0, 2π): the inverse of placeOnCircle, in the convention of Arcs.arcAt. 0 when the point is the center.

E.g. arcs that follow a handle on a ring: Arcs.arcAt(center, r, Points.angleAround(center, handle), sweep). Pins.angle measures counter-clockwise.

center
The center.
point
The point.
result optional
Optional Real to write the result into; it is returned. Without it, a new Real is returned.

Returns The angle of point around center, in radians.

areCollinearstatic

static areCollinear(p1: Point | VectorLike, p2: Point | VectorLike, p3: Point | VectorLike, result?: Bool | null): Bool

Determines whether three points are collinear (lie on the same line).

p1
The first point.
p2
The second point.
p3
The third point.
result optional
Optional Bool to write the result into; it is returned. Without it, a new Bool is returned.

Returns true if p1, p2, and p3 are collinear; otherwise false.

arraystatic

static array(count: number, result?: Point[] | null): Point[]

Creates an array of points with the specified capacity.

count
The number of points to allocate space for in the array.
result optional
Optional array to store the result; if null, a new array is created.

Returns An array of points with capacity for the specified count.

boundingBoxstatic

static boundingBox(points: Sequence<Vector> | VectorsLike, result?: Box | null): Box

Computes the axis-aligned bounding box that contains all points in the given sequence.

points
The sequence of points to enclose in the bounding box.
result optional
Optional box to store the result; if null, a new box is created.

Returns A box representing the bounds of all points in the sequence; the zero box at the origin if there are no points (like the bounding box of an empty polygon).

centroidstatic

static centroid(points: Sequence<Vector> | VectorsLike, result?: Point | null): Point

Computes the centroid (geometric average) of a collection of points.

points
The points to average.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns The centroid of points.

closestPointOnArcstatic

static closestPointOnArc(p: Point | VectorLike, center: Point | VectorLike, radius: Real | NumberLike, startDir: Vector | VectorLike, endDir: Vector | VectorLike, clockwise: Bool | BoolLike, result?: Point | null): Point

Computes the closest point on a circular arc to a given query point.

p
The point from which the closest point is sought.
center
The center of the circle on which the arc lies.
radius
The radius of the arc.
startDir
The starting direction of the arc.
endDir
The ending direction of the arc.
clockwise
Whether the arc sweeps from startDir to endDir clockwise in the mathematical sense (y axis up), so true runs counterclockwise on the screen: the other way than Arcs.arcBetween and Vectors.angle. For example, from the direction (1, 0) to (-1, 0) true passes the top of the circle. To keep one convention, build the arc with Arcs.arcBetween and use Arcs.pointAt, Arcs.pinAt or Arcs.closestPoint.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns The point on the circular arc closest to p.

closestPointOnDirectedLinestatic

static closestPointOnDirectedLine(point: Point | VectorLike, start: Point | VectorLike, dir: Vector | VectorLike, result?: Point | null): Point

Computes the closest point on a line, defined by a start point and direction, to a given point.

point
The point from which the closest point is sought.
start
A point on the line.
dir
The direction of the line.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns The point on the line defined by start and dir that is closest to point.

closestPointOnLinestatic

static closestPointOnLine(point: Point | VectorLike, line: Segment | ShapeLike, result?: Point | null): Point

Computes the closest point on a line to a given point.

point
The point from which the closest point is sought.
line
The line onto which the point is projected.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns The point on line closest to point.

closestPointOnPolylinestatic

static closestPointOnPolyline(p: Point | VectorLike, polyline: Polyline | ShapeLike, result?: Point | null): Point

Returns the closest point on a polyline to a given point.

p
The point to project.
polyline
The polyline to project onto.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns The point on polyline closest to p.

closestPointOnSegmentstatic

static closestPointOnSegment(p: Point | VectorLike, segment: Segment | ShapeLike, result?: Point | null): Point

Returns the closest point on a line segment to a given point.

p
The point to project.
segment
The segment to project onto.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns The point on segment closest to p.

closestPositionOnDirectedLinestatic

static closestPositionOnDirectedLine(point: Point | VectorLike, start: Point | VectorLike, direction: Vector | VectorLike, result?: Real | null): Real

Computes the relative position of a point along a line defined by a starting point and direction.

point
The point to measure.
start
A point on the line.
direction
The direction of the line.
result optional
Optional Real to write the result into; it is returned. Without it, a new Real is returned.

Returns The relative position of point along the line defined by start and direction.

closestPositionOnLinestatic

static closestPositionOnLine(point: Point | VectorLike, line: Segment | ShapeLike, result?: Real | null): Real

Returns the relative position of a point along a line as a real number.

point
The point to measure.
line
The line along which to measure.
result optional
Optional Real to write the result into; it is returned. Without it, a new Real is returned.

Returns A real number representing the relative position along line.

closestStepOnSegmentstatic

static closestStepOnSegment(p: Point | VectorLike, segment: Segment | ShapeLike, steps: Integer | NumberLike, result?: Point | null): Point

Returns the closest of evenly spaced positions on a segment: steps equal steps, ends included, e.g. a slider that snaps: Points.closestStepOnSegment(handle, track, 4, handle) puts the handle at 0, ¼, ½, ¾ or 1 of the track.

The continuous counterpart is closestPointOnSegment; with steps 0 (or less) this function gives the same point, so one call can switch snapping on and off. The slider's value is then Points.relativePositionOnSegment(handle, track). A segment of length 0 gives its start.

p
The point to move onto the segment, e.g. a dragged handle.
segment
The segment.
steps
The number of equal steps (steps + 1 positions); 0: no snapping.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns The closest step position on segment.

copystatic

static copy(point: Point | VectorLike, result?: Point | null): Point

Creates a copy of the specified point.

point
The point to copy.
result optional
Optional point to store the result; if null, a new point is created.

Returns A copy of the specified point.

diagonalstatic

static diagonal(points: Sequence<Vector> | VectorsLike, result?: Segment | null): Segment

Returns the diagonal line segment connecting two extreme points in a sequence.

points
The points from which to compute the diagonal.
result optional
Optional Segment to write the result into; it is returned. Without it, a new Segment is returned.

Returns The segment connecting the farthest-apart points in points.

distanceToLinestatic

static distanceToLine(p: Point | VectorLike, line: Segment | ShapeLike, result?: Real | null): Real

Computes the perpendicular distance from a point to a line.

p
The point.
line
The line.
result optional
Optional Real to write the result into; it is returned. Without it, a new Real is returned.

Returns The perpendicular distance from p to line.

distanceToPointstatic

static distanceToPoint(p1: Point | VectorLike, p2: Point | VectorLike, result?: Real | null): Real

Computes the distance between two points.

p1
The first point.
p2
The second point.
result optional
Optional Real to write the result into; it is returned. Without it, a new Real is returned.

Returns The distance between p1 and p2.

distanceToSegmentstatic

static distanceToSegment(p: Point | VectorLike, segment: Segment | ShapeLike, result?: Real | null): Real

Computes the shortest distance from a point to a line segment.

p
The point.
segment
The line segment.
result optional
Optional Real to write the result into; it is returned. Without it, a new Real is returned.

Returns The distance from p to segment.

horizontalDistancestatic

static horizontalDistance(p1: Point | VectorLike, p2: Point | VectorLike, result?: Real | null): Real

Computes the horizontal (X-axis) distance between two points.

p1
The first point.
p2
The second point.
result optional
Optional Real to write the result into; it is returned. Without it, a new Real is returned.

Returns The horizontal distance between p1 and p2.

isLeftOfstatic

static isLeftOf(p: Point | VectorLike, p1: Point | VectorLike, p2: Point | VectorLike, result?: Bool | null): Bool

Whether a point lies left of the direction from p1 to p2, as seen on the screen (y pointing down): e.g. which side of a segment a handle is on.

"Left" as everywhere in the GDK (e.g. Offsets, the side of Separate): for a direction to the right, left is up on the screen. A point on the line (or a coordinate that is not a number) gives false.

p
The point to test.
p1
The start of the direction.
p2
A second point the direction points to.
result optional
Optional Bool to write the result into; it is returned. Without it, a new Bool is returned.

Returns true when p is left of the direction p1 → p2.

lengthAlongAxisstatic

static lengthAlongAxis(p1: Point | VectorLike, p2: Point | VectorLike, horizontal: Bool | BoolLike, result?: Real | null): Real

Computes the distance between two points along a specified axis.

p1
The first point.
p2
The second point.
horizontal
true for horizontal distance; false for vertical.
result optional
Optional Real to write the result into; it is returned. Without it, a new Real is returned.

Returns The axis-aligned distance between the points.

mapToCirclestatic

static mapToCircle(point: Point | VectorLike, center: Point | VectorLike, radius: Real | NumberLike, result?: Point | null): Point

Maps a point to a corresponding point on a circle defined by a center and radius: the point on the circle in the direction of point as seen from the center.

point
The point to map.
center
The center of the target circle.
radius
The radius of the target circle.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns A point on the circle specified by center and radius.

maxDistanceTostatic

static maxDistanceTo(point: Point | VectorLike, positions: Sequence<Vector> | VectorsLike, result?: Real | null): Real

Computes the maximum distance from a point to a set of points.

point
The reference point.
positions
The set of points to compare.
result optional
Optional Real to write the result into; it is returned. Without it, a new Real is returned.

Returns The largest distance from point to any point in positions; 0 if positions is empty.

midPointstatic

static midPoint(p1: Point | VectorLike, p2: Point | VectorLike, result?: Point | null): Point

Computes the midpoint between two points.

p1
The first point.
p2
The second point.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns The midpoint between p1 and p2.

minDistanceTostatic

static minDistanceTo(point: Point | VectorLike, positions: Sequence<Vector> | VectorsLike, result?: Real | null): Real

Computes the minimum distance from a point to any point in a set.

point
The reference point.
positions
The set of points to compare.
result optional
Optional Real to write the result into; it is returned. Without it, a new Real is returned.

Returns The smallest distance from point to any point in positions; positive infinity if positions is empty.

movestatic

static move(point: Point | VectorLike, dx: Real | NumberLike, dy: Real | NumberLike, result?: Point | null): Point

Moves a point by the specified horizontal and vertical distances.

point
The point to move.
dx
The distance to move along the X axis.
dy
The distance to move along the Y axis.
result optional
Optional point to store the result; if null, a new point is created.

Returns A point moved by dx horizontally and dy vertically.

moveDownstatic

static moveDown(point: Point | VectorLike, distance: Real | NumberLike, result?: Point | null): Point

Moves a point downward (in the positive Y direction) by the specified distance.

point
The point to move.
distance
The distance to move downward.
result optional
Optional point to store the result; if null, a new point is created.

Returns A point moved downward by the specified distance.

moveLeftstatic

static moveLeft(point: Point | VectorLike, distance: Real | NumberLike, result?: Point | null): Point

Moves a point leftward (in the negative X direction) by the specified distance.

point
The point to move.
distance
The distance to move leftward.
result optional
Optional point to store the result; if null, a new point is created.

Returns A point moved leftward by the specified distance.

moveRightstatic

static moveRight(point: Point | VectorLike, distance: Real | NumberLike, result?: Point | null): Point

Moves a point rightward (in the positive X direction) by the specified distance.

point
The point to move.
distance
The distance to move rightward.
result optional
Optional point to store the result; if null, a new point is created.

Returns A point moved rightward by the specified distance.

moveUpstatic

static moveUp(point: Point | VectorLike, distance: Real | NumberLike, result?: Point | null): Point

Moves a point upward (in the negative Y direction) by the specified distance.

point
The point to move.
distance
The distance to move upward.
result optional
Optional point to store the result; if null, a new point is created.

Returns A point moved upward by the specified distance.

placeBesideSegmentstatic

static placeBesideSegment(p1: Point | VectorLike, p2: Point | VectorLike, ratio: Real | NumberLike, distance: Real | NumberLike, left: Bool | BoolLike, result?: Point | null): Point

Places a point beside a line segment at a specified relative position and distance.

p1
The start point of the segment.
p2
The end point of the segment.
ratio
A value between 0 and 1 specifying the relative position along the segment, where 0 corresponds to p1 and 1 to p2.
distance
The perpendicular distance from the segment at which the point is placed.
left
Determines the side of the segment on which the point is placed, relative to the direction from p1 to p2.
result optional
Optional point to store the result; if null, a new point is created.

Returns A point positioned beside the segment at the specified ratio and distance.

placeInRectanglestatic

static placeInRectangle(anchorX: Real | NumberLike, anchorY: Real | NumberLike, target: Rectangle | ShapeLike, result?: Point | null): Point

Places a point inside a rectangle using normalized anchor coordinates.

anchorX
The horizontal anchor position within the rectangle, typically in the range [0, 1], where 0 represents the left edge and 1 represents the right edge.
anchorY
The vertical anchor position within the rectangle, typically in the range [0, 1], where 0 represents the top edge and 1 represents the bottom edge.
target
The rectangle in which the point is placed.
result optional
Optional point to store the result; if null, a new point is created.

Returns A point placed inside the rectangle at the specified anchor position.

placeOnArcstatic

static placeOnArc(center: Point | VectorLike, radius: Real | NumberLike, startDir: Vector | VectorLike, endDir: Vector | VectorLike, ratio: Real | NumberLike, clockwise: Bool | BoolLike, result?: Point | null): Point

Places a point at a specified ratio along a circular arc.

center
The center of the circle defining the arc.
radius
The radius of the circle.
startDir
The direction from the center marking the start of the arc.
endDir
The direction from the center marking the end of the arc.
ratio
A value between 0 and 1 specifying the relative position along the arc, where 0 corresponds to startDir and 1 to endDir.
clockwise
The direction from startDir to endDir: clockwise in the mathematical sense (y axis up), so true runs counterclockwise on the screen: the other way than Arcs.arcBetween and Vectors.angle. For example, from the direction (1, 0) to (-1, 0) true passes the top of the circle. To keep one convention, build the arc with Arcs.arcBetween and use Arcs.pointAt, Arcs.pinAt or Arcs.closestPoint.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns The point on the arc at the specified ratio.

placeOnCirclestatic

static placeOnCircle(center: Point | VectorLike, radius: Real | NumberLike, angle: Real | NumberLike, result?: Point | null): Point

Places a point on the circumference of a circle at the specified angle.

center
The center of the circle.
radius
The radius of the circle.
angle
The angle at which to place the point, measured from the positive X axis.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns The point on the circle's circumference at angle.

placeOnSegmentstatic

static placeOnSegment(p1: Point | VectorLike, p2: Point | VectorLike, ratio: Real | NumberLike, result?: Point | null): Point

Places a point on a line segment at a specified relative position.

p1
The start point of the segment.
p2
The end point of the segment.
ratio
A value between 0 and 1 specifying the relative position along the segment, where 0 corresponds to p1 and 1 to p2.
result optional
Optional point to store the result; if null, a new point is created.

Returns A point located on the segment at the specified ratio.

pointWithMaxDistancestatic

static pointWithMaxDistance(point: Point | VectorLike, positions: Sequence<Vector> | VectorsLike, result?: Point | null): Point

Returns the point with the maximum distance from a reference point among a set of points.

point
The reference point.
positions
The points to compare.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns The point farthest from point.

pointWithMinDistancestatic

static pointWithMinDistance(point: Point | VectorLike, positions: Sequence<Vector> | VectorsLike, result?: Point | null): Point

Returns the point with the minimum distance from a reference point among a set of points.

point
The reference point.
positions
The points to compare.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns The point closest to point.

reflectstatic

static reflect(point: Point | VectorLike, pivot: Point | VectorLike, result?: Point | null): Point

Reflects a point through a pivot point.

point
The point to reflect.
pivot
The point to reflect through.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns The reflection of point through pivot.

reflectOverLinestatic

static reflectOverLine(point: Point | VectorLike, line: Segment | ShapeLike, result?: Point | null): Point

Reflects a point across a line.

point
The point to reflect.
line
The line to reflect across.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns The mirror image of point across line.

relativePositionOnSegmentstatic

static relativePositionOnSegment(point: Point | VectorLike, segment: Segment | ShapeLike, result?: Real | null): Real

Computes the relative position of a point along a line segment as a real number.

point
The point to measure.
segment
The segment along which to measure.
result optional
Optional Real to write the result into; it is returned. Without it, a new Real is returned.

Returns The relative position of point along segment.

rotateAroundstatic

static rotateAround(point: Point | VectorLike, pivot: Point | VectorLike, angle: Real | NumberLike, result?: Point | null): Point

Rotates a point around a pivot by the specified angle.

point
The point to rotate.
pivot
The center of rotation.
angle
The angle of rotation.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns point rotated around pivot by angle.

sequentialDistancesstatic

static sequentialDistances(positions: Sequence<Vector> | VectorsLike, result?: Sequence<Real> | null): Sequence<Real>

Computes the distance along the points from the first point to each point: the running total of the distances between consecutive points, starting with 0.

One entry per point; [0, 0], [3, 4], [3, 10] gives 0, 5, 11. No points give an empty sequence.

positions
The sequence of points.
result optional
Optional Sequence<Real> to write the result into; it is returned. Without it, a new Sequence<Real> is returned.

Returns The distance along the points to each point, starting with 0.

snapToGridstatic

static snapToGrid(point: Point | VectorLike, gridSize: Real | NumberLike, result?: Point | null): Point

Snaps a point to the nearest position on a uniform grid.

point
The point to snap.
gridSize
The spacing between grid lines along each axis.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns The grid-aligned point nearest to point (halves are rounded up, like Values.round). For a grid size of 0 or less the point is returned unchanged.

translatestatic

static translate(point: Point | VectorLike, direction: Vector | VectorLike, result?: Point | null): Point

Translates a point by a direction vector.

point
The point to translate.
direction
The direction vector representing the translation offset.
result optional
Optional Point to write the result into; it is returned. Without it, a new Point is returned.

Returns point shifted by direction.

verticalDistancestatic

static verticalDistance(p1: Point | VectorLike, p2: Point | VectorLike, result?: Real | null): Real

Computes the vertical (Y-axis) distance between two points.

p1
The first point.
p2
The second point.
result optional
Optional Real to write the result into; it is returned. Without it, a new Real is returned.

Returns The vertical distance between p1 and p2.