disko:geometry

Import with import { … } from "disko:geometry". Generated from the module's shipped declarations. See Map geometry for a guide.

disko:geometry — plain-data shapes, intersections, projections, bounds and containment.

Every function is pure and deterministic. Comparisons are exact unless an opts argument supplies { epsilon }, which widens every boundary comparison by that absolute amount. Boundaries count as inside. Functions with zero to two answers return arrays ordered along the first argument; a tangency gives one point.

Types

Segment

A segment between two points, which may be equal (world.crossing form).

export interface Segment {
    readonly start: Vector;
    readonly end: Vector;
}

Line

An infinite line through point; direction is non-zero.

export interface Line {
    readonly point: Vector;
    readonly direction: Vector;
}

Ray

A half-line from origin; direction is non-zero.

export interface Ray {
    readonly origin: Vector;
    readonly direction: Vector;
}

Circle

A circle; radius >= 0.

export interface Circle {
    readonly center: Vector;
    readonly radius: number;
}

Arc

A world-native arc, the data world.createSegment and segment.setCurve take. start and end differ. The center is midpoint(start, end) + perpendicular((end − start) / 2) · curve, and the arc runs from start to end in the positive-angle direction, sweeping θ ∈ (0, 2π) with curve = cot(θ / 2): 0 is a semicircle, positive curves are minor arcs and negative curves are major arcs.

export interface Arc {
    readonly start: Vector;
    readonly end: Vector;
    readonly curve: number;
}

Plane

The world plane form: points p with dot(normal, p) === distance.

export interface Plane {
    readonly normal: Vector;
    readonly distance: number;
}

Bounds

An axis-aligned box with min <= max on both axes.

export interface Bounds {
    readonly minX: number;
    readonly minY: number;
    readonly maxX: number;
    readonly maxY: number;
}

Polygon

Three or more points, implicitly closed. Concave and self-intersecting polygons are allowed; containment uses the even-odd rule.

export type Polygon = readonly Vector[];

RayHit

A hit along a ray: the point and its distance from the origin.

export interface RayHit {
    point: Vector;
    distance: number;
}

Functions

segment

Creates a segment.

export function segment(start: Vector, end: Vector): Segment;

line

Creates a line.

export function line(point: Vector, direction: Vector): Line;

Throws: RangeError when direction is zero.

lineThrough

The line through a and b, directed from a to b.

export function lineThrough(a: Vector, b: Vector): Line;

Throws: RangeError when a equals b.

ray

Creates a ray.

export function ray(origin: Vector, direction: Vector): Ray;

Throws: RangeError when direction is zero.

circle

Creates a circle.

export function circle(center: Vector, radius: number): Circle;

Throws: RangeError when radius is negative.

bounds

Creates bounds.

export function bounds(minX: number, minY: number, maxX: number, maxY: number): Bounds;

Throws: RangeError when a minimum exceeds its maximum.

plane

The plane through point with the given normal: { normal: unit, distance: dot(point, unit) }.

export function plane(point: Vector, normal: Vector): Plane;

Throws: RangeError when normal is zero.

arcFromCenter

The arc on the circle around center from startAngle, sweeping sweep radians in the positive-angle direction.

export function arcFromCenter(options: {
    readonly center: Vector;
    readonly radius: number;
    readonly startAngle: number;
    readonly sweep: number;
}): Arc;

Throws: RangeError unless radius > 0 and sweep ∈ (0, 2π).

arcCenter

The arc's circle center, computed exactly as the physics solver does.

export function arcCenter(arc: Arc): Vector;

arcRadius

The arc's circle radius, computed exactly as the physics solver does.

export function arcRadius(arc: Arc): number;

arcSweep

The swept angle 2 · atan2(1, curve) in (0, 2π).

export function arcSweep(arc: Arc): number;

arcAngles

Angles of start and end around the center, each in (−π, π].

export function arcAngles(arc: Arc): {
    startAngle: number;
    endAngle: number;
};

arcLength

Arc length radius · sweep.

export function arcLength(arc: Arc): number;

segmentLength

Segment length.

export function segmentLength(seg: Segment): number;

arcPointAt

The point at fraction t ∈ [0, 1] of the arc length; 0 and 1 return the exact endpoints.

export function arcPointAt(arc: Arc, t: number): Vector;

segmentPointAt

The point at fraction t ∈ [0, 1] of the segment; 0 and 1 return the exact endpoints.

export function segmentPointAt(seg: Segment, t: number): Vector;

sampleArc

count >= 2 points evenly spaced along the arc, including both ends. An explicit approximation.

export function sampleArc(arc: Arc, count: number): Vector[];

regularPolygon

The vertices of a regular polygon; the first lies at angle rotation and the rest follow in the positive-angle direction.

export function regularPolygon(options: {
    readonly center: Vector;
    readonly radius: number;
    readonly sides: number;
    readonly rotation?: number;
}): Vector[];

Throws: RangeError unless sides is an integer >= 3 and radius > 0.

lineIntersection

The crossing of two lines, or null when they are parallel or coincident (unit directions whose cross product is within epsilon).

export function lineIntersection(a: Line, b: Line, opts?: Tolerance): Vector | null;

segmentIntersection

The crossing of two segments, or null when they are disjoint or parallel, including collinear overlap (see segmentOverlap). Shared endpoints are returned exactly.

export function segmentIntersection(a: Segment, b: Segment, opts?: Tolerance): Vector | null;

segmentOverlap

The shared piece of two collinear segments, running from the point nearest a.start, or null when they are not collinear or do not overlap. A single shared point gives a zero-length segment.

export function segmentOverlap(a: Segment, b: Segment, opts?: Tolerance): Segment | null;

raySegmentIntersection

The nearest hit of a ray on a segment, or null.

export function raySegmentIntersection(ray: Ray, seg: Segment, opts?: Tolerance): RayHit | null;

lineCircleIntersections

Line–circle crossings ordered along the line direction.

export function lineCircleIntersections(line: Line, circle: Circle, opts?: Tolerance): Vector[];

segmentCircleIntersections

Segment–circle crossings ordered from seg.start.

export function segmentCircleIntersections(seg: Segment, circle: Circle, opts?: Tolerance): Vector[];

rayCircleIntersection

The nearest ray–circle hit, or null. An origin inside the circle gives the exit point.

export function rayCircleIntersection(ray: Ray, circle: Circle, opts?: Tolerance): RayHit | null;

circleIntersections

Circle–circle crossings. Walking around a in the positive-angle direction from the direction toward b.center, the first point comes first. Concentric circles give [].

export function circleIntersections(a: Circle, b: Circle, opts?: Tolerance): Vector[];

lineArcIntersections

Line–arc crossings ordered along the line direction.

export function lineArcIntersections(line: Line, arc: Arc, opts?: Tolerance): Vector[];

segmentArcIntersections

Segment–arc crossings ordered from seg.start.

export function segmentArcIntersections(seg: Segment, arc: Arc, opts?: Tolerance): Vector[];

rayArcIntersection

The nearest ray–arc hit, or null.

export function rayArcIntersection(ray: Ray, arc: Arc, opts?: Tolerance): RayHit | null;

projectOnLine

The orthogonal projection of point onto the line.

export function projectOnLine(point: Vector, line: Line): Vector;

closestPointOnSegment

The point of the segment nearest to point.

export function closestPointOnSegment(point: Vector, seg: Segment): Vector;

closestPointOnCircle

The point of the circle nearest to point, or null at the center.

export function closestPointOnCircle(point: Vector, circle: Circle): Vector | null;

closestPointOnArc

The point of the arc nearest to point: the radial projection inside the sweep, otherwise the nearer endpoint (start on a tie or at the center).

export function closestPointOnArc(point: Vector, arc: Arc): Vector;

closestPointOnBounds

point clamped into the bounds (itself when inside).

export function closestPointOnBounds(point: Vector, b: Bounds): Vector;

distanceToLine

Distance from point to the line.

export function distanceToLine(point: Vector, line: Line): number;

distanceToSegment

Distance from point to the segment.

export function distanceToSegment(point: Vector, seg: Segment): number;

distanceToArc

Distance from point to the arc.

export function distanceToArc(point: Vector, arc: Arc): number;

signedDistanceToCircle

Distance from point to the circle; negative inside.

export function signedDistanceToCircle(point: Vector, circle: Circle): number;

signedDistanceToPlane

dot(normal, point) − distance with the normal normalized.

export function signedDistanceToPlane(point: Vector, plane: Plane): number;

Throws: RangeError when plane.normal is zero.

boundsOfPoints

The bounds of a list of points.

export function boundsOfPoints(points: readonly Vector[]): Bounds;

Throws: RangeError on an empty list.

boundsOfSegment

The bounds of a segment.

export function boundsOfSegment(seg: Segment): Bounds;

boundsOfCircle

The bounds of a circle.

export function boundsOfCircle(c: Circle): Bounds;

boundsOfPolygon

The bounds of a polygon.

export function boundsOfPolygon(p: Polygon): Bounds;

boundsOfArc

Exact arc bounds, including the axis extremes inside the sweep.

export function boundsOfArc(arc: Arc): Bounds;

unionBounds

The smallest bounds containing both.

export function unionBounds(a: Bounds, b: Bounds): Bounds;

expandBounds

Bounds grown by margin on every side; a negative margin shrinks them.

export function expandBounds(b: Bounds, margin: number): Bounds;

Throws: RangeError when shrinking would go below zero size.

boundsCenter

The center of the bounds.

export function boundsCenter(b: Bounds): Vector;

boundsSize

{ width, height } of the bounds.

export function boundsSize(b: Bounds): {
    width: number;
    height: number;
};

boundsOverlap

Whether two bounds overlap; touching edges count.

export function boundsOverlap(a: Bounds, b: Bounds, opts?: Tolerance): boolean;

circleContainsPoint

Whether the circle contains point, boundary included.

export function circleContainsPoint(circle: Circle, point: Vector, opts?: Tolerance): boolean;

boundsContainsPoint

Whether the bounds contain point, boundary included.

export function boundsContainsPoint(b: Bounds, point: Vector, opts?: Tolerance): boolean;

polygonContainsPoint

Even-odd containment; a point on an edge counts as inside.

export function polygonContainsPoint(polygon: Polygon, point: Vector, opts?: Tolerance): boolean;

circlesOverlap

Whether two circles overlap; touching counts.

export function circlesOverlap(a: Circle, b: Circle, opts?: Tolerance): boolean;

pointOnSegment

Whether point lies on the segment.

export function pointOnSegment(point: Vector, seg: Segment, opts?: Tolerance): boolean;

pointOnArc

Whether point lies on the arc.

export function pointOnArc(point: Vector, arc: Arc, opts?: Tolerance): boolean;

polygonArea

Signed polygon area; positive when the vertices run in the positive-angle direction (clockwise on screen).

export function polygonArea(polygon: Polygon): number;

polygonCentroid

The area centroid.

export function polygonCentroid(polygon: Polygon): Vector;

Throws: RangeError for a polygon with zero area.