# disko:geometry

> Plain-data shapes, intersections, projections, bounds and containment.

Import with `import { … } from "disko:geometry"`. Generated from the module's
shipped declarations. See [Map geometry](/games/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).

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

### Line

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

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

### Ray

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

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

### Circle

A circle; `radius >= 0`.

```ts
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.

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

### Plane

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

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

### Bounds

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

```ts
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.

```ts
export type Polygon = readonly Vector[];
```

### RayHit

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

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

## Functions

### segment

Creates a segment.

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

### line

Creates a line.

```ts
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`.

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

Throws: RangeError when `a` equals `b`.

### ray

Creates a ray.

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

Throws: RangeError when `direction` is zero.

### circle

Creates a circle.

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

Throws: RangeError when `radius` is negative.

### bounds

Creates bounds.

```ts
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) }`.

```ts
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.

```ts
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.

```ts
export function arcCenter(arc: Arc): Vector;
```

### arcRadius

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

```ts
export function arcRadius(arc: Arc): number;
```

### arcSweep

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

```ts
export function arcSweep(arc: Arc): number;
```

### arcAngles

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

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

### arcLength

Arc length `radius · sweep`.

```ts
export function arcLength(arc: Arc): number;
```

### segmentLength

Segment length.

```ts
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.

```ts
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.

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

### sampleArc

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

```ts
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.

```ts
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).

```ts
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`](#segmentoverlap)). Shared endpoints are returned exactly.

```ts
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.

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

### raySegmentIntersection

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

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

### lineCircleIntersections

Line–circle crossings ordered along the line direction.

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

### segmentCircleIntersections

Segment–circle crossings ordered from `seg.start`.

```ts
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.

```ts
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 `[]`.

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

### lineArcIntersections

Line–arc crossings ordered along the line direction.

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

### segmentArcIntersections

Segment–arc crossings ordered from `seg.start`.

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

### rayArcIntersection

The nearest ray–arc hit, or `null`.

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

### projectOnLine

The orthogonal projection of `point` onto the line.

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

### closestPointOnSegment

The point of the segment nearest to `point`.

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

### closestPointOnCircle

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

```ts
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).

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

### closestPointOnBounds

`point` clamped into the bounds (itself when inside).

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

### distanceToLine

Distance from `point` to the line.

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

### distanceToSegment

Distance from `point` to the segment.

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

### distanceToArc

Distance from `point` to the arc.

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

### signedDistanceToCircle

Distance from `point` to the circle; negative inside.

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

### signedDistanceToPlane

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

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

Throws: RangeError when `plane.normal` is zero.

### boundsOfPoints

The bounds of a list of points.

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

Throws: RangeError on an empty list.

### boundsOfSegment

The bounds of a segment.

```ts
export function boundsOfSegment(seg: Segment): Bounds;
```

### boundsOfCircle

The bounds of a circle.

```ts
export function boundsOfCircle(c: Circle): Bounds;
```

### boundsOfPolygon

The bounds of a polygon.

```ts
export function boundsOfPolygon(p: Polygon): Bounds;
```

### boundsOfArc

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

```ts
export function boundsOfArc(arc: Arc): Bounds;
```

### unionBounds

The smallest bounds containing both.

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

### expandBounds

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

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

Throws: RangeError when shrinking would go below zero size.

### boundsCenter

The center of the bounds.

```ts
export function boundsCenter(b: Bounds): Vector;
```

### boundsSize

`{ width, height }` of the bounds.

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

### boundsOverlap

Whether two bounds overlap; touching edges count.

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

### circleContainsPoint

Whether the circle contains `point`, boundary included.

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

### boundsContainsPoint

Whether the bounds contain `point`, boundary included.

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

### polygonContainsPoint

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

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

### circlesOverlap

Whether two circles overlap; touching counts.

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

### pointOnSegment

Whether `point` lies on the segment.

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

### pointOnArc

Whether `point` lies on the arc.

```ts
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).

```ts
export function polygonArea(polygon: Polygon): number;
```

### polygonCentroid

The area centroid.

```ts
export function polygonCentroid(polygon: Polygon): Vector;
```

Throws: RangeError for a polygon with zero area.