@snaptrude/plugin-core 0.3.0 → 0.6.0

package/src/api/core/geom/query/curve.ts

@@ -0,0 +1,1078 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import { Vec3Handle, CurveHandle, LineHandle, Vec3Components } from "../../../../handles"
+
+/**
+ * Curve queries — read-only geometric questions about curves (lines and arcs)
+ * and the relationships between two curves (all-handle model, §11).
+ *
+ * Every method takes opaque curve handles ({@linkcode CurveHandle}/{@linkcode LineHandle})
+ * and point handles ({@linkcode Vec3Handle}) and returns plain values — points as
+ * {@linkcode Vec3Components}, lengths/distances/parameters as `number`, predicates as
+ * `boolean`. Relationship methods that produce a new curve return a
+ * {@linkcode CurveHandle} (or `null` when there is no result). No query mutates its
+ * inputs.
+ *
+ * Accessed via `snaptrude.core.geom.query.curve`.
+ */
+export abstract class PluginGeomQueryCurveApi {
+  constructor() {}
+
+  /**
+   * Get the start point of a curve.
+   * @param curve The curve to query
+   * @returns The start point as {@linkcode Vec3Components}
+   *
+   * @examplePrompt Where does this wall edge start?
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const centerline = await snaptrude.design.query.geometry.getCenterline(wall)
+   * if (centerline) {
+   *   const start = await snaptrude.core.geom.query.curve.getStartPoint(centerline)
+   *   console.log(start.x, start.y, start.z)
+   * }
+   * ```
+   */
+  public abstract getStartPoint(curve: CurveHandle): PluginApiReturn<Vec3Components>
+
+  /**
+   * Get the end point of a curve.
+   * @param curve The curve to query
+   * @returns The end point as {@linkcode Vec3Components}
+   *
+   * @examplePrompt Get the coordinates of the far end of this edge
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const line = await snaptrude.core.geom.create.line(a, b)
+   * const end = await snaptrude.core.geom.query.curve.getEndPoint(line) // { x: 5, y: 0, z: 0 }
+   * ```
+   */
+  public abstract getEndPoint(curve: CurveHandle): PluginApiReturn<Vec3Components>
+
+  /**
+   * Get the mid point of a curve.
+   * @param curve The curve to query
+   * @returns The mid point as {@linkcode Vec3Components}
+   *
+   * @examplePrompt Find the midpoint of this wall edge
+   * @examplePrompt Where is the centre of this boundary line?
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const centerline = await snaptrude.design.query.geometry.getCenterline(wall)
+   * if (centerline) {
+   *   const mid = await snaptrude.core.geom.query.curve.getMidPoint(centerline)
+   *   console.log(mid.x, mid.y, mid.z)
+   * }
+   * ```
+   */
+  public abstract getMidPoint(curve: CurveHandle): PluginApiReturn<Vec3Components>
+
+  /**
+   * Get the arc-length of a curve.
+   * @param curve The curve to query
+   * @returns The curve length as a `number`
+   *
+   * @examplePrompt How long is this wall edge?
+   * @examplePrompt Measure the length of this curved boundary
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const centerline = await snaptrude.design.query.geometry.getCenterline(wall)
+   * if (centerline) {
+   *   const length = await snaptrude.core.geom.query.curve.getLength(centerline)
+   * }
+   * ```
+   */
+  public abstract getLength(curve: CurveHandle): PluginApiReturn<number>
+
+  /**
+   * Get the straight-line chord length between a curve's endpoints.
+   * @param curve The curve to query
+   * @returns The chord length as a `number`
+   *
+   * @examplePrompt What is the straight-line distance between the two ends of this arc?
+   *
+   * # Example
+   * ```ts
+   * const start = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const end = await snaptrude.core.math.vec3.new(-5, 0, 0)
+   * const centre = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const axis = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const arc = await snaptrude.core.geom.create.arc(start, end, centre, axis)
+   * const chord = await snaptrude.core.geom.query.curve.getChordLength(arc) // 10 (getLength gives the arc length)
+   * ```
+   */
+  public abstract getChordLength(curve: CurveHandle): PluginApiReturn<number>
+
+  /**
+   * Get the unit tangent vector of a curve at a point on it.
+   * @param curve The curve to query
+   * @param point Point on the curve
+   * @returns The tangent vector as {@linkcode Vec3Components}
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(3, 0, 4)
+   * const line = await snaptrude.core.geom.create.line(a, b)
+   * const tangent = await snaptrude.core.geom.query.curve.getTangent(line, a) // { x: 0.6, y: 0, z: 0.8 }
+   * ```
+   */
+  public abstract getTangent(
+    curve: CurveHandle,
+    point: Vec3Handle,
+  ): PluginApiReturn<Vec3Components>
+
+  /**
+   * Get the unit normal vector of a curve at a point on it.
+   * @param curve The curve to query
+   * @param point Point on the curve
+   * @returns The normal vector as {@linkcode Vec3Components}
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(10, 0, 0)
+   * const line = await snaptrude.core.geom.create.line(a, b)
+   * const normal = await snaptrude.core.geom.query.curve.getNormal(line, a)
+   * ```
+   */
+  public abstract getNormal(
+    curve: CurveHandle,
+    point: Vec3Handle,
+  ): PluginApiReturn<Vec3Components>
+
+  /**
+   * Get the point on a curve nearest to an arbitrary point.
+   * @param curve The curve to query
+   * @param point The reference point
+   * @returns The nearest point on the curve as {@linkcode Vec3Components}
+   *
+   * @examplePrompt Find the point on this edge closest to the column
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const centerline = await snaptrude.design.query.geometry.getCenterline(wall)
+   * const reference = await snaptrude.core.math.vec3.new(2, 0, 3)
+   * if (centerline) {
+   *   const nearest = await snaptrude.core.geom.query.curve.getNearestPoint(centerline, reference)
+   * }
+   * ```
+   */
+  public abstract getNearestPoint(
+    curve: CurveHandle,
+    point: Vec3Handle,
+  ): PluginApiReturn<Vec3Components>
+
+  /**
+   * Project a point onto a curve.
+   * @param curve The curve to project onto
+   * @param point The point to project
+   * @returns The projected point as {@linkcode Vec3Components}
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(10, 0, 0)
+   * const line = await snaptrude.core.geom.create.line(a, b)
+   * const point = await snaptrude.core.math.vec3.new(3, 0, 4)
+   * const projected = await snaptrude.core.geom.query.curve.getProjection(line, point) // { x: 3, y: 0, z: 0 }
+   * ```
+   */
+  public abstract getProjection(
+    curve: CurveHandle,
+    point: Vec3Handle,
+  ): PluginApiReturn<Vec3Components>
+
+  /**
+   * Get the point at a given distance along a curve from a reference point.
+   * @param curve The curve to query
+   * @param referencePoint Point on the curve to measure from
+   * @param distance Distance along the curve from the reference point
+   * @param forward Optional direction along the curve (defaults to `true`)
+   * @returns The resulting point as {@linkcode Vec3Components}
+   *
+   * @examplePrompt Find the point 2 metres along this edge from the corner
+   * @examplePrompt Mark a spot 900mm from the start of the wall edge
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(10, 0, 0)
+   * const line = await snaptrude.core.geom.create.line(a, b)
+   * const p = await snaptrude.core.geom.query.curve.getPointAtDistance(line, a, 2) // { x: 2, y: 0, z: 0 }
+   * const q = await snaptrude.core.geom.query.curve.getPointAtDistance(line, b, 2, false) // measured backwards from the end
+   * ```
+   */
+  public abstract getPointAtDistance(
+    curve: CurveHandle,
+    referencePoint: Vec3Handle,
+    distance: number,
+    forward?: boolean,
+  ): PluginApiReturn<Vec3Components>
+
+  /**
+   * Get the curve parameter corresponding to a point on the curve.
+   * @param curve The curve to query
+   * @param point Point on the curve
+   * @returns The parameter as a `number`
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(8, 0, 0)
+   * const line = await snaptrude.core.geom.create.line(a, b)
+   * const t = await snaptrude.core.geom.query.curve.getParameterAtPoint(line, b)
+   * ```
+   */
+  public abstract getParameterAtPoint(
+    curve: CurveHandle,
+    point: Vec3Handle,
+  ): PluginApiReturn<number>
+
+  /**
+   * Get the curvature of a curve at a point on it.
+   * @param curve The curve to query
+   * @param point Point on the curve
+   * @returns The curvature as a `number`
+   *
+   * # Example
+   * ```ts
+   * const start = await snaptrude.core.math.vec3.new(2, 0, 0)
+   * const end = await snaptrude.core.math.vec3.new(-2, 0, 0)
+   * const centre = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const axis = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const arc = await snaptrude.core.geom.create.arc(start, end, centre, axis)
+   * const k = await snaptrude.core.geom.query.curve.getCurvature(arc, start) // 0.5 (1 / radius)
+   * ```
+   */
+  public abstract getCurvature(
+    curve: CurveHandle,
+    point: Vec3Handle,
+  ): PluginApiReturn<number>
+
+  /**
+   * Get the shortest distance from an arbitrary point to a curve.
+   * @param curve The curve to query
+   * @param point The point to measure from
+   * @returns The distance as a `number`
+   *
+   * @examplePrompt How far is this column from the wall edge?
+   * @examplePrompt What is the shortest distance from this point to the boundary line?
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const centerline = await snaptrude.design.query.geometry.getCenterline(wall)
+   * const point = await snaptrude.core.math.vec3.new(2, 0, 3)
+   * if (centerline) {
+   *   const distance = await snaptrude.core.geom.query.curve.getDistanceToPoint(centerline, point)
+   * }
+   * ```
+   */
+  public abstract getDistanceToPoint(
+    curve: CurveHandle,
+    point: Vec3Handle,
+  ): PluginApiReturn<number>
+
+  /**
+   * Get the arc-length distance along a curve between two points on it.
+   * @param curve The curve to query
+   * @param pointA First point on the curve
+   * @param pointB Second point on the curve
+   * @returns The distance along the curve as a `number`
+   *
+   * @examplePrompt How far apart are these two points measured along the curved wall?
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(10, 0, 0)
+   * const line = await snaptrude.core.geom.create.line(a, b)
+   * const mid = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const d = await snaptrude.core.geom.query.curve.getDistanceAlong(line, a, mid) // 5
+   * ```
+   */
+  public abstract getDistanceAlong(
+    curve: CurveHandle,
+    pointA: Vec3Handle,
+    pointB: Vec3Handle,
+  ): PluginApiReturn<number>
+
+  /**
+   * List sampled points along a curve.
+   * @param curve The curve to sample
+   * @param resolution Optional number of samples for arcs (defaults to `20`; ignored for lines)
+   * @returns The sampled points as {@linkcode Vec3Components}`[]`
+   *
+   * # Example
+   * ```ts
+   * const start = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const end = await snaptrude.core.math.vec3.new(0, 0, 5)
+   * const centre = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const axis = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const arc = await snaptrude.core.geom.create.arc(start, end, centre, axis)
+   * const points = await snaptrude.core.geom.query.curve.listPoints(arc, 40)
+   * for (const p of points) console.log(p.x, p.y, p.z)
+   * ```
+   */
+  public abstract listPoints(
+    curve: CurveHandle,
+    resolution?: number,
+  ): PluginApiReturn<Vec3Components[]>
+
+  /**
+   * List the points produced by subdividing a curve into equal segments.
+   * @param curve The curve to subdivide
+   * @param segments Number of equal segments to divide the curve into
+   * @returns The subdivision points as {@linkcode Vec3Components}`[]`
+   *
+   * @examplePrompt Divide this edge into 5 equal segments
+   * @examplePrompt Split the wall line into equal parts for placing columns
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const centerline = await snaptrude.design.query.geometry.getCenterline(wall)
+   * if (centerline) {
+   *   const points = await snaptrude.core.geom.query.curve.listSubdivisions(centerline, 5)
+   * }
+   * ```
+   */
+  public abstract listSubdivisions(
+    curve: CurveHandle,
+    segments: number,
+  ): PluginApiReturn<Vec3Components[]>
+
+  /**
+   * Test whether a curve is a straight line.
+   * @param curve The curve to query
+   * @returns `true` if the curve is linear, otherwise `false`
+   *
+   * @examplePrompt Is this edge straight or curved?
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const centerline = await snaptrude.design.query.geometry.getCenterline(wall)
+   * if (centerline) {
+   *   const straight = await snaptrude.core.geom.query.curve.isLinear(centerline)
+   * }
+   * ```
+   */
+  public abstract isLinear(curve: CurveHandle): PluginApiReturn<boolean>
+
+  /**
+   * Test whether a point lies on a curve within an optional threshold.
+   * @param curve The curve to query
+   * @param point The point to test
+   * @param threshold Optional distance tolerance (defaults to the engine default)
+   * @returns `true` if the point is on the curve, otherwise `false`
+   *
+   * @examplePrompt Check whether this point lies on the wall edge
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(10, 0, 0)
+   * const line = await snaptrude.core.geom.create.line(a, b)
+   * const point = await snaptrude.core.math.vec3.new(5, 0, 0.005)
+   * const on = await snaptrude.core.geom.query.curve.isOnCurve(line, point, 0.01) // true within tolerance
+   * ```
+   */
+  public abstract isOnCurve(
+    curve: CurveHandle,
+    point: Vec3Handle,
+    threshold?: number,
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Test whether a curve contains a point, optionally including its endpoints.
+   * @param curve The curve to query
+   * @param point The point to test
+   * @param includeEndPoints Optional flag to count endpoints as contained (defaults to `true`)
+   * @returns `true` if the curve contains the point, otherwise `false`
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(10, 0, 0)
+   * const line = await snaptrude.core.geom.create.line(a, b)
+   * const atEnd = await snaptrude.core.geom.query.curve.hasPoint(line, b) // true (endpoints count by default)
+   * const interiorOnly = await snaptrude.core.geom.query.curve.hasPoint(line, b, false) // false
+   * ```
+   */
+  public abstract hasPoint(
+    curve: CurveHandle,
+    point: Vec3Handle,
+    includeEndPoints?: boolean,
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Test whether two curves are geometrically equal.
+   * @param curveA First curve
+   * @param curveB Second curve
+   * @returns `true` if the curves are equal, otherwise `false`
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(10, 0, 0)
+   * const lineA = await snaptrude.core.geom.create.line(a, b)
+   * const lineB = await snaptrude.core.geom.create.line(a, b)
+   * const same = await snaptrude.core.geom.query.curve.isEqual(lineA, lineB) // true
+   * ```
+   */
+  public abstract isEqual(
+    curveA: CurveHandle,
+    curveB: CurveHandle,
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Test whether two curves overlap (share a collinear/concentric span), optionally including their endpoints.
+   * @param curveA First curve
+   * @param curveB Second curve
+   * @param includeEndPoints Optional flag to count endpoint contact as overlap (defaults to `false`)
+   * @returns `true` if the curves overlap, otherwise `false`
+   *
+   * @examplePrompt Do these two wall edges overlap?
+   *
+   * # Example
+   * ```ts
+   * const p0 = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const p5 = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const p10 = await snaptrude.core.math.vec3.new(10, 0, 0)
+   * const p15 = await snaptrude.core.math.vec3.new(15, 0, 0)
+   * const lineA = await snaptrude.core.geom.create.line(p0, p10)
+   * const lineB = await snaptrude.core.geom.create.line(p5, p15)
+   * const overlaps = await snaptrude.core.geom.query.curve.isOverlapping(lineA, lineB) // true (share the 5..10 span)
+   * ```
+   */
+  public abstract isOverlapping(
+    curveA: CurveHandle,
+    curveB: CurveHandle,
+    includeEndPoints?: boolean,
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Get the common (overlapping) part of two curves.
+   * @param curveA First curve
+   * @param curveB Second curve
+   * @returns The common part as a {@linkcode CurveHandle}, or `null` if there is none
+   *
+   * @examplePrompt Get the shared segment where these two edges overlap
+   *
+   * # Example
+   * ```ts
+   * const p0 = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const p5 = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const p10 = await snaptrude.core.math.vec3.new(10, 0, 0)
+   * const p15 = await snaptrude.core.math.vec3.new(15, 0, 0)
+   * const lineA = await snaptrude.core.geom.create.line(p0, p10)
+   * const lineB = await snaptrude.core.geom.create.line(p5, p15)
+   * const common = await snaptrude.core.geom.query.curve.getCommonPart(lineA, lineB)
+   * if (common) {
+   *   const length = await snaptrude.core.geom.query.curve.getLength(common) // 5
+   * }
+   * ```
+   */
+  public abstract getCommonPart(
+    curveA: CurveHandle,
+    curveB: CurveHandle,
+  ): PluginApiReturn<CurveHandle | null>
+
+  /**
+   * List the intersection points between two curves.
+   * @param curveA First curve
+   * @param curveB Second curve
+   * @param boundedA Optional flag to bound intersections to `curveA`'s extent (defaults to `true`)
+   * @param boundedB Optional flag to bound intersections to `curveB`'s extent (defaults to `true`)
+   * @returns The intersection points as {@linkcode Vec3Components}`[]`
+   *
+   * @examplePrompt Where do these two lines cross?
+   * @examplePrompt Find the intersection points of these two gridlines
+   *
+   * # Example
+   * ```ts
+   * const a1 = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const a2 = await snaptrude.core.math.vec3.new(10, 0, 0)
+   * const b1 = await snaptrude.core.math.vec3.new(5, 0, -5)
+   * const b2 = await snaptrude.core.math.vec3.new(5, 0, 5)
+   * const lineA = await snaptrude.core.geom.create.line(a1, a2)
+   * const lineB = await snaptrude.core.geom.create.line(b1, b2)
+   * const points = await snaptrude.core.geom.query.curve.listIntersections(lineA, lineB) // [{ x: 5, y: 0, z: 0 }]
+   * const unbounded = await snaptrude.core.geom.query.curve.listIntersections(lineA, lineB, false, false) // treat both as infinite
+   * ```
+   */
+  public abstract listIntersections(
+    curveA: CurveHandle,
+    curveB: CurveHandle,
+    boundedA?: boolean,
+    boundedB?: boolean,
+  ): PluginApiReturn<Vec3Components[]>
+
+  /**
+   * Merge two curves into a single curve when they are mergeable.
+   * @param curveA First curve
+   * @param curveB Second curve
+   * @returns The merged curve as a {@linkcode CurveHandle}, or `null` if they cannot be merged
+   *
+   * @examplePrompt Merge these two line segments into a single line
+   *
+   * # Example
+   * ```ts
+   * const p0 = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const p5 = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const p10 = await snaptrude.core.math.vec3.new(10, 0, 0)
+   * const lineA = await snaptrude.core.geom.create.line(p0, p5)
+   * const lineB = await snaptrude.core.geom.create.line(p5, p10)
+   * const merged = await snaptrude.core.geom.query.curve.getMergedCurve(lineA, lineB)
+   * if (merged) {
+   *   const length = await snaptrude.core.geom.query.curve.getLength(merged) // 10
+   * }
+   * ```
+   */
+  public abstract getMergedCurve(
+    curveA: CurveHandle,
+    curveB: CurveHandle,
+  ): PluginApiReturn<CurveHandle | null>
+
+  /**
+   * Test whether two curves are continuous (share an endpoint without a gap).
+   * @param curveA First curve
+   * @param curveB Second curve
+   * @returns `true` if the curves are continuous, otherwise `false`
+   *
+   * @examplePrompt Do these two edges connect end to end without a gap?
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const c = await snaptrude.core.math.vec3.new(5, 0, 5)
+   * const lineA = await snaptrude.core.geom.create.line(a, b)
+   * const lineB = await snaptrude.core.geom.create.line(b, c)
+   * const connected = await snaptrude.core.geom.query.curve.isContinuous(lineA, lineB) // true
+   * ```
+   */
+  public abstract isContinuous(
+    curveA: CurveHandle,
+    curveB: CurveHandle,
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Test whether two lines are parallel within an optional tolerance.
+   * @param lineA First line
+   * @param lineB Second line
+   * @param tolerance Optional angular tolerance (defaults to the engine default)
+   * @returns `true` if the lines are parallel, otherwise `false`
+   *
+   * @examplePrompt Are these two walls parallel?
+   * @examplePrompt Check if these gridlines run parallel to each other
+   *
+   * # Example
+   * ```ts
+   * const a1 = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const a2 = await snaptrude.core.math.vec3.new(10, 0, 0)
+   * const b1 = await snaptrude.core.math.vec3.new(0, 0, 3)
+   * const b2 = await snaptrude.core.math.vec3.new(10, 0, 3)
+   * const lineA = await snaptrude.core.geom.create.line(a1, a2)
+   * const lineB = await snaptrude.core.geom.create.line(b1, b2)
+   * const parallel = await snaptrude.core.geom.query.curve.isParallel(lineA, lineB) // true
+   * ```
+   */
+  public abstract isParallel(
+    lineA: LineHandle,
+    lineB: LineHandle,
+    tolerance?: number,
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Get the shortest gap between two curves, optionally including their endpoints.
+   * @param curveA First curve
+   * @param curveB Second curve
+   * @param includeEndPoints Optional flag to include endpoints when measuring (defaults to `false`)
+   * @returns The shortest gap as a `number`
+   *
+   * @examplePrompt What is the gap between these two wall edges?
+   * @examplePrompt How close do these two curves get to each other?
+   *
+   * # Example
+   * ```ts
+   * const a1 = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const a2 = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const b1 = await snaptrude.core.math.vec3.new(0, 0, 2)
+   * const b2 = await snaptrude.core.math.vec3.new(5, 0, 2)
+   * const curveA = await snaptrude.core.geom.create.line(a1, a2)
+   * const curveB = await snaptrude.core.geom.create.line(b1, b2)
+   * const gap = await snaptrude.core.geom.query.curve.getShortestGap(curveA, curveB) // 2
+   * ```
+   */
+  public abstract getShortestGap(
+    curveA: CurveHandle,
+    curveB: CurveHandle,
+    includeEndPoints?: boolean,
+  ): PluginApiReturn<number>
+
+  /**
+   * Get the perpendicular distance between two parallel lines.
+   * @param lineA First line
+   * @param lineB Second line
+   * @returns The distance between the lines as a `number`
+   *
+   * @examplePrompt How far apart are these two parallel walls?
+   * @examplePrompt Measure the spacing between these two gridlines
+   *
+   * # Example
+   * ```ts
+   * const a1 = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const a2 = await snaptrude.core.math.vec3.new(10, 0, 0)
+   * const b1 = await snaptrude.core.math.vec3.new(0, 0, 4)
+   * const b2 = await snaptrude.core.math.vec3.new(10, 0, 4)
+   * const lineA = await snaptrude.core.geom.create.line(a1, a2)
+   * const lineB = await snaptrude.core.geom.create.line(b1, b2)
+   * const spacing = await snaptrude.core.geom.query.curve.getDistanceBetween(lineA, lineB) // 4
+   * ```
+   */
+  public abstract getDistanceBetween(
+    lineA: LineHandle,
+    lineB: LineHandle,
+  ): PluginApiReturn<number>
+}
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.getStartPoint}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to query |
+ */
+export const PluginGeomQueryCurveGetStartPointArgs = z.object({
+  curve: CurveHandle,
+})
+
+export type PluginGeomQueryCurveGetStartPointArgs = z.infer<typeof PluginGeomQueryCurveGetStartPointArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.getEndPoint}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to query |
+ */
+export const PluginGeomQueryCurveGetEndPointArgs = z.object({
+  curve: CurveHandle,
+})
+
+export type PluginGeomQueryCurveGetEndPointArgs = z.infer<typeof PluginGeomQueryCurveGetEndPointArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.getMidPoint}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to query |
+ */
+export const PluginGeomQueryCurveGetMidPointArgs = z.object({
+  curve: CurveHandle,
+})
+
+export type PluginGeomQueryCurveGetMidPointArgs = z.infer<typeof PluginGeomQueryCurveGetMidPointArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.getLength}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to query |
+ */
+export const PluginGeomQueryCurveGetLengthArgs = z.object({
+  curve: CurveHandle,
+})
+
+export type PluginGeomQueryCurveGetLengthArgs = z.infer<typeof PluginGeomQueryCurveGetLengthArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.getChordLength}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to query |
+ */
+export const PluginGeomQueryCurveGetChordLengthArgs = z.object({
+  curve: CurveHandle,
+})
+
+export type PluginGeomQueryCurveGetChordLengthArgs = z.infer<typeof PluginGeomQueryCurveGetChordLengthArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.getTangent}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to query |
+ * | `point` | {@linkcode Vec3Handle} | Point on the curve |
+ */
+export const PluginGeomQueryCurveGetTangentArgs = z.object({
+  curve: CurveHandle,
+  point: Vec3Handle,
+})
+
+export type PluginGeomQueryCurveGetTangentArgs = z.infer<typeof PluginGeomQueryCurveGetTangentArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.getNormal}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to query |
+ * | `point` | {@linkcode Vec3Handle} | Point on the curve |
+ */
+export const PluginGeomQueryCurveGetNormalArgs = z.object({
+  curve: CurveHandle,
+  point: Vec3Handle,
+})
+
+export type PluginGeomQueryCurveGetNormalArgs = z.infer<typeof PluginGeomQueryCurveGetNormalArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.getNearestPoint}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to query |
+ * | `point` | {@linkcode Vec3Handle} | The reference point |
+ */
+export const PluginGeomQueryCurveGetNearestPointArgs = z.object({
+  curve: CurveHandle,
+  point: Vec3Handle,
+})
+
+export type PluginGeomQueryCurveGetNearestPointArgs = z.infer<typeof PluginGeomQueryCurveGetNearestPointArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.getProjection}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to project onto |
+ * | `point` | {@linkcode Vec3Handle} | The point to project |
+ */
+export const PluginGeomQueryCurveGetProjectionArgs = z.object({
+  curve: CurveHandle,
+  point: Vec3Handle,
+})
+
+export type PluginGeomQueryCurveGetProjectionArgs = z.infer<typeof PluginGeomQueryCurveGetProjectionArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.getPointAtDistance}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to query |
+ * | `referencePoint` | {@linkcode Vec3Handle} | Point on the curve to measure from |
+ * | `distance` | `number` | Distance along the curve from the reference point |
+ * | `forward` | `boolean` | Optional direction along the curve (defaults to `true`) |
+ */
+export const PluginGeomQueryCurveGetPointAtDistanceArgs = z.object({
+  curve: CurveHandle,
+  referencePoint: Vec3Handle,
+  distance: z.number(),
+  forward: z.boolean().optional(),
+})
+
+export type PluginGeomQueryCurveGetPointAtDistanceArgs = z.infer<typeof PluginGeomQueryCurveGetPointAtDistanceArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.getParameterAtPoint}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to query |
+ * | `point` | {@linkcode Vec3Handle} | Point on the curve |
+ */
+export const PluginGeomQueryCurveGetParameterAtPointArgs = z.object({
+  curve: CurveHandle,
+  point: Vec3Handle,
+})
+
+export type PluginGeomQueryCurveGetParameterAtPointArgs = z.infer<typeof PluginGeomQueryCurveGetParameterAtPointArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.getCurvature}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to query |
+ * | `point` | {@linkcode Vec3Handle} | Point on the curve |
+ */
+export const PluginGeomQueryCurveGetCurvatureArgs = z.object({
+  curve: CurveHandle,
+  point: Vec3Handle,
+})
+
+export type PluginGeomQueryCurveGetCurvatureArgs = z.infer<typeof PluginGeomQueryCurveGetCurvatureArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.getDistanceToPoint}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to query |
+ * | `point` | {@linkcode Vec3Handle} | The point to measure from |
+ */
+export const PluginGeomQueryCurveGetDistanceToPointArgs = z.object({
+  curve: CurveHandle,
+  point: Vec3Handle,
+})
+
+export type PluginGeomQueryCurveGetDistanceToPointArgs = z.infer<typeof PluginGeomQueryCurveGetDistanceToPointArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.getDistanceAlong}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to query |
+ * | `pointA` | {@linkcode Vec3Handle} | First point on the curve |
+ * | `pointB` | {@linkcode Vec3Handle} | Second point on the curve |
+ */
+export const PluginGeomQueryCurveGetDistanceAlongArgs = z.object({
+  curve: CurveHandle,
+  pointA: Vec3Handle,
+  pointB: Vec3Handle,
+})
+
+export type PluginGeomQueryCurveGetDistanceAlongArgs = z.infer<typeof PluginGeomQueryCurveGetDistanceAlongArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.listPoints}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to sample |
+ * | `resolution` | `number` | Optional number of samples for arcs (defaults to `20`; ignored for lines) |
+ */
+export const PluginGeomQueryCurveListPointsArgs = z.object({
+  curve: CurveHandle,
+  resolution: z.number().optional(),
+})
+
+export type PluginGeomQueryCurveListPointsArgs = z.infer<typeof PluginGeomQueryCurveListPointsArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.listSubdivisions}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to subdivide |
+ * | `segments` | `number` | Number of equal segments to divide the curve into |
+ */
+export const PluginGeomQueryCurveListSubdivisionsArgs = z.object({
+  curve: CurveHandle,
+  segments: z.number(),
+})
+
+export type PluginGeomQueryCurveListSubdivisionsArgs = z.infer<typeof PluginGeomQueryCurveListSubdivisionsArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.isLinear}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to query |
+ */
+export const PluginGeomQueryCurveIsLinearArgs = z.object({
+  curve: CurveHandle,
+})
+
+export type PluginGeomQueryCurveIsLinearArgs = z.infer<typeof PluginGeomQueryCurveIsLinearArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.isOnCurve}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to query |
+ * | `point` | {@linkcode Vec3Handle} | The point to test |
+ * | `threshold` | `number` | Optional distance tolerance (defaults to the engine default) |
+ */
+export const PluginGeomQueryCurveIsOnCurveArgs = z.object({
+  curve: CurveHandle,
+  point: Vec3Handle,
+  threshold: z.number().optional(),
+})
+
+export type PluginGeomQueryCurveIsOnCurveArgs = z.infer<typeof PluginGeomQueryCurveIsOnCurveArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.hasPoint}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to query |
+ * | `point` | {@linkcode Vec3Handle} | The point to test |
+ * | `includeEndPoints` | `boolean` | Optional flag to count endpoints as contained (defaults to `true`) |
+ */
+export const PluginGeomQueryCurveHasPointArgs = z.object({
+  curve: CurveHandle,
+  point: Vec3Handle,
+  includeEndPoints: z.boolean().optional(),
+})
+
+export type PluginGeomQueryCurveHasPointArgs = z.infer<typeof PluginGeomQueryCurveHasPointArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.isEqual}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curveA` | {@linkcode CurveHandle} | First curve |
+ * | `curveB` | {@linkcode CurveHandle} | Second curve |
+ */
+export const PluginGeomQueryCurveIsEqualArgs = z.object({
+  curveA: CurveHandle,
+  curveB: CurveHandle,
+})
+
+export type PluginGeomQueryCurveIsEqualArgs = z.infer<typeof PluginGeomQueryCurveIsEqualArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.isOverlapping}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curveA` | {@linkcode CurveHandle} | First curve |
+ * | `curveB` | {@linkcode CurveHandle} | Second curve |
+ * | `includeEndPoints` | `boolean` | Optional flag to count endpoint contact as overlap (defaults to `false`) |
+ */
+export const PluginGeomQueryCurveIsOverlappingArgs = z.object({
+  curveA: CurveHandle,
+  curveB: CurveHandle,
+  includeEndPoints: z.boolean().optional(),
+})
+
+export type PluginGeomQueryCurveIsOverlappingArgs = z.infer<typeof PluginGeomQueryCurveIsOverlappingArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.getCommonPart}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curveA` | {@linkcode CurveHandle} | First curve |
+ * | `curveB` | {@linkcode CurveHandle} | Second curve |
+ */
+export const PluginGeomQueryCurveGetCommonPartArgs = z.object({
+  curveA: CurveHandle,
+  curveB: CurveHandle,
+})
+
+export type PluginGeomQueryCurveGetCommonPartArgs = z.infer<typeof PluginGeomQueryCurveGetCommonPartArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.listIntersections}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curveA` | {@linkcode CurveHandle} | First curve |
+ * | `curveB` | {@linkcode CurveHandle} | Second curve |
+ * | `boundedA` | `boolean` | Optional flag to bound intersections to `curveA`'s extent (defaults to `true`) |
+ * | `boundedB` | `boolean` | Optional flag to bound intersections to `curveB`'s extent (defaults to `true`) |
+ */
+export const PluginGeomQueryCurveListIntersectionsArgs = z.object({
+  curveA: CurveHandle,
+  curveB: CurveHandle,
+  boundedA: z.boolean().optional(),
+  boundedB: z.boolean().optional(),
+})
+
+export type PluginGeomQueryCurveListIntersectionsArgs = z.infer<typeof PluginGeomQueryCurveListIntersectionsArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.getMergedCurve}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curveA` | {@linkcode CurveHandle} | First curve |
+ * | `curveB` | {@linkcode CurveHandle} | Second curve |
+ */
+export const PluginGeomQueryCurveGetMergedCurveArgs = z.object({
+  curveA: CurveHandle,
+  curveB: CurveHandle,
+})
+
+export type PluginGeomQueryCurveGetMergedCurveArgs = z.infer<typeof PluginGeomQueryCurveGetMergedCurveArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.isContinuous}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curveA` | {@linkcode CurveHandle} | First curve |
+ * | `curveB` | {@linkcode CurveHandle} | Second curve |
+ */
+export const PluginGeomQueryCurveIsContinuousArgs = z.object({
+  curveA: CurveHandle,
+  curveB: CurveHandle,
+})
+
+export type PluginGeomQueryCurveIsContinuousArgs = z.infer<typeof PluginGeomQueryCurveIsContinuousArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.isParallel}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `lineA` | {@linkcode LineHandle} | First line |
+ * | `lineB` | {@linkcode LineHandle} | Second line |
+ * | `tolerance` | `number` | Optional angular tolerance (defaults to the engine default) |
+ */
+export const PluginGeomQueryCurveIsParallelArgs = z.object({
+  lineA: LineHandle,
+  lineB: LineHandle,
+  tolerance: z.number().optional(),
+})
+
+export type PluginGeomQueryCurveIsParallelArgs = z.infer<typeof PluginGeomQueryCurveIsParallelArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.getShortestGap}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curveA` | {@linkcode CurveHandle} | First curve |
+ * | `curveB` | {@linkcode CurveHandle} | Second curve |
+ * | `includeEndPoints` | `boolean` | Optional flag to include endpoints when measuring (defaults to `false`) |
+ */
+export const PluginGeomQueryCurveGetShortestGapArgs = z.object({
+  curveA: CurveHandle,
+  curveB: CurveHandle,
+  includeEndPoints: z.boolean().optional(),
+})
+
+export type PluginGeomQueryCurveGetShortestGapArgs = z.infer<typeof PluginGeomQueryCurveGetShortestGapArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCurveApi.getDistanceBetween}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `lineA` | {@linkcode LineHandle} | First line |
+ * | `lineB` | {@linkcode LineHandle} | Second line |
+ */
+export const PluginGeomQueryCurveGetDistanceBetweenArgs = z.object({
+  lineA: LineHandle,
+  lineB: LineHandle,
+})
+
+export type PluginGeomQueryCurveGetDistanceBetweenArgs = z.infer<typeof PluginGeomQueryCurveGetDistanceBetweenArgs>