@snaptrude/plugin-core 0.3.0 → 0.5.0

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

@@ -0,0 +1,404 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import { CircleHandle, Vec3Handle, Vec3Components } from "../../../../handles"
+
+/**
+ * Circle-specific geometry queries — read closed-circle properties as plain values
+ * (all-handle model, §11). A circle is a closed curve with its own namespace
+ * (mirroring {@linkcode PluginGeomQueryArcApi}); it is NOT part of the shared
+ * {@linkcode CurveHandle} line/arc surface.
+ *
+ * Every method takes an opaque {@linkcode CircleHandle} (plus a point handle where
+ * relevant) and returns plain values — numbers, {@linkcode Vec3Components},
+ * predicates as `boolean`. No query mutates its inputs.
+ *
+ * Accessed via `snaptrude.core.geom.query.circle`.
+ */
+export abstract class PluginGeomQueryCircleApi {
+  constructor() {}
+
+  /**
+   * Read the radius of a circle.
+   * @param circle The circle to query
+   * @returns The radius as a `number`
+   *
+   * @examplePrompt What is the radius of this circle?
+   * @examplePrompt Measure the radius of the circular column grid
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const radius = await snaptrude.core.geom.query.circle.getRadius(circle)
+   * ```
+   */
+  public abstract getRadius(circle: CircleHandle): PluginApiReturn<number>
+
+  /**
+   * Read the centre point of a circle.
+   * @param circle The circle to query
+   * @returns The centre as {@linkcode Vec3Components}
+   *
+   * @examplePrompt Where is the centre of this circle?
+   * @examplePrompt Find the center point of the circular courtyard outline
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const centre = await snaptrude.core.geom.query.circle.getCentre(circle)
+   * console.log(centre.x, centre.y, centre.z)
+   * ```
+   */
+  public abstract getCentre(circle: CircleHandle): PluginApiReturn<Vec3Components>
+
+  /**
+   * Read the axis (plane normal) of a circle.
+   * @param circle The circle to query
+   * @returns The axis as {@linkcode Vec3Components}
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const axis = await snaptrude.core.geom.query.circle.getAxis(circle)
+   * console.log(axis.x, axis.y, axis.z)
+   * ```
+   */
+  public abstract getAxis(circle: CircleHandle): PluginApiReturn<Vec3Components>
+
+  /**
+   * Read the length (circumference, `2πr`) of a circle.
+   * @param circle The circle to query
+   * @returns The circumference as a `number`
+   *
+   * @examplePrompt What is the circumference of this circle?
+   * @examplePrompt How long is the circular path around the courtyard?
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const circumference = await snaptrude.core.geom.query.circle.getLength(circle)
+   * ```
+   */
+  public abstract getLength(circle: CircleHandle): PluginApiReturn<number>
+
+  /**
+   * Check whether a circle is geometrically valid (non-degenerate axis + positive radius).
+   * @param circle The circle to query
+   * @returns `true` if the circle is valid, otherwise `false`
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const ok = await snaptrude.core.geom.query.circle.isValid(circle)
+   * ```
+   */
+  public abstract isValid(circle: CircleHandle): PluginApiReturn<boolean>
+
+  /**
+   * Get the point on a circle nearest to an arbitrary point.
+   * @param circle The circle to query
+   * @param point The reference point
+   * @returns The nearest point as {@linkcode Vec3Components}
+   *
+   * @examplePrompt Find the point on the circle closest to this column
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const target = await snaptrude.core.math.vec3.new(8, 0, 2)
+   * const nearest = await snaptrude.core.geom.query.circle.getNearestPoint(circle, target)
+   * console.log(nearest.x, nearest.y, nearest.z)
+   * ```
+   */
+  public abstract getNearestPoint(
+    circle: CircleHandle,
+    point: Vec3Handle
+  ): PluginApiReturn<Vec3Components>
+
+  /**
+   * Test whether a point lies on a circle.
+   * @param circle The circle to query
+   * @param point The point to test
+   * @returns `true` if the point is on the circle, otherwise `false`
+   *
+   * @examplePrompt Check whether this point sits on the circle
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const pt = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const onCircle = await snaptrude.core.geom.query.circle.hasPoint(circle, pt)
+   * ```
+   */
+  public abstract hasPoint(circle: CircleHandle, point: Vec3Handle): PluginApiReturn<boolean>
+
+  /**
+   * Get the tangent direction of a circle at a point on it.
+   * @param circle The circle to query
+   * @param point A point on the circle
+   * @returns The tangent as {@linkcode Vec3Components}
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const pt = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const tangent = await snaptrude.core.geom.query.circle.getTangent(circle, pt)
+   * console.log(tangent.x, tangent.y, tangent.z)
+   * ```
+   */
+  public abstract getTangent(circle: CircleHandle, point: Vec3Handle): PluginApiReturn<Vec3Components>
+
+  /**
+   * Get the (in-plane, radial) normal direction of a circle at a point on it.
+   * @param circle The circle to query
+   * @param point A point on the circle
+   * @returns The radial normal as {@linkcode Vec3Components}
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const pt = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const normal = await snaptrude.core.geom.query.circle.getNormal(circle, pt)
+   * console.log(normal.x, normal.y, normal.z)
+   * ```
+   */
+  public abstract getNormal(circle: CircleHandle, point: Vec3Handle): PluginApiReturn<Vec3Components>
+
+  /**
+   * Get the point reached by travelling a signed arc-distance along the circle from
+   * a reference point that lies on it.
+   * @param circle The circle to query
+   * @param referencePoint A point on the circle to travel from
+   * @param distance Arc distance to travel
+   * @param forward Travel direction (optional; default forward)
+   * @returns The resulting point as {@linkcode Vec3Components}
+   *
+   * @examplePrompt Mark a point 2 metres along the circle from this point
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const ref = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const ahead = await snaptrude.core.geom.query.circle.getPointAtDistance(circle, ref, 2)
+   * const behind = await snaptrude.core.geom.query.circle.getPointAtDistance(circle, ref, 2, false)
+   * ```
+   */
+  public abstract getPointAtDistance(
+    circle: CircleHandle,
+    referencePoint: Vec3Handle,
+    distance: number,
+    forward?: boolean
+  ): PluginApiReturn<Vec3Components>
+
+  /**
+   * Test whether two circles are geometrically equal.
+   * @param circleA First circle
+   * @param circleB Second circle
+   * @returns `true` if the circles are equal, otherwise `false`
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const a = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const b = await snaptrude.core.geom.create.circle(origin, up, 3)
+   * const same = await snaptrude.core.geom.query.circle.isEqual(a, b)
+   * ```
+   */
+  public abstract isEqual(circleA: CircleHandle, circleB: CircleHandle): PluginApiReturn<boolean>
+
+  /**
+   * Sample a circle into an ordered list of points.
+   * @param circle The circle to query
+   * @param resolution Number of segments to sample (optional)
+   * @returns The sampled points as {@linkcode Vec3Components}`[]`
+   *
+   * @examplePrompt Divide this circle into 12 equal points
+   * @examplePrompt Get evenly spaced points around the circle to place columns
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const points = await snaptrude.core.geom.query.circle.listPoints(circle, 12)
+   * for (const p of points) console.log(p.x, p.y, p.z)
+   * ```
+   */
+  public abstract listPoints(circle: CircleHandle, resolution?: number): PluginApiReturn<Vec3Components[]>
+}
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.getRadius}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ */
+export const PluginGeomQueryCircleGetRadiusArgs = z.object({ circle: CircleHandle })
+export type PluginGeomQueryCircleGetRadiusArgs = z.infer<typeof PluginGeomQueryCircleGetRadiusArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.getCentre}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ */
+export const PluginGeomQueryCircleGetCentreArgs = z.object({ circle: CircleHandle })
+export type PluginGeomQueryCircleGetCentreArgs = z.infer<typeof PluginGeomQueryCircleGetCentreArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.getAxis}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ */
+export const PluginGeomQueryCircleGetAxisArgs = z.object({ circle: CircleHandle })
+export type PluginGeomQueryCircleGetAxisArgs = z.infer<typeof PluginGeomQueryCircleGetAxisArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.getLength}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ */
+export const PluginGeomQueryCircleGetLengthArgs = z.object({ circle: CircleHandle })
+export type PluginGeomQueryCircleGetLengthArgs = z.infer<typeof PluginGeomQueryCircleGetLengthArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.isValid}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ */
+export const PluginGeomQueryCircleIsValidArgs = z.object({ circle: CircleHandle })
+export type PluginGeomQueryCircleIsValidArgs = z.infer<typeof PluginGeomQueryCircleIsValidArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.getNearestPoint}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ * | `point` | {@linkcode Vec3Handle} | The reference point |
+ */
+export const PluginGeomQueryCircleGetNearestPointArgs = z.object({
+  circle: CircleHandle,
+  point: Vec3Handle,
+})
+export type PluginGeomQueryCircleGetNearestPointArgs = z.infer<
+  typeof PluginGeomQueryCircleGetNearestPointArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.hasPoint}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ * | `point` | {@linkcode Vec3Handle} | The point to test |
+ */
+export const PluginGeomQueryCircleHasPointArgs = z.object({
+  circle: CircleHandle,
+  point: Vec3Handle,
+})
+export type PluginGeomQueryCircleHasPointArgs = z.infer<typeof PluginGeomQueryCircleHasPointArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.getTangent}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ * | `point` | {@linkcode Vec3Handle} | A point on the circle |
+ */
+export const PluginGeomQueryCircleGetTangentArgs = z.object({
+  circle: CircleHandle,
+  point: Vec3Handle,
+})
+export type PluginGeomQueryCircleGetTangentArgs = z.infer<typeof PluginGeomQueryCircleGetTangentArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.getNormal}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ * | `point` | {@linkcode Vec3Handle} | A point on the circle |
+ */
+export const PluginGeomQueryCircleGetNormalArgs = z.object({
+  circle: CircleHandle,
+  point: Vec3Handle,
+})
+export type PluginGeomQueryCircleGetNormalArgs = z.infer<typeof PluginGeomQueryCircleGetNormalArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.getPointAtDistance}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ * | `referencePoint` | {@linkcode Vec3Handle} | A point on the circle to travel from |
+ * | `distance` | `number` | Arc distance to travel |
+ * | `forward` | `boolean` | Travel direction (optional; default forward) |
+ */
+export const PluginGeomQueryCircleGetPointAtDistanceArgs = z.object({
+  circle: CircleHandle,
+  referencePoint: Vec3Handle,
+  distance: z.number(),
+  forward: z.boolean().optional(),
+})
+export type PluginGeomQueryCircleGetPointAtDistanceArgs = z.infer<
+  typeof PluginGeomQueryCircleGetPointAtDistanceArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.isEqual}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circleA` | {@linkcode CircleHandle} | First circle |
+ * | `circleB` | {@linkcode CircleHandle} | Second circle |
+ */
+export const PluginGeomQueryCircleIsEqualArgs = z.object({
+  circleA: CircleHandle,
+  circleB: CircleHandle,
+})
+export type PluginGeomQueryCircleIsEqualArgs = z.infer<typeof PluginGeomQueryCircleIsEqualArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.listPoints}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ * | `resolution` | `number` | Number of segments to sample (optional) |
+ */
+export const PluginGeomQueryCircleListPointsArgs = z.object({
+  circle: CircleHandle,
+  resolution: z.number().optional(),
+})
+export type PluginGeomQueryCircleListPointsArgs = z.infer<typeof PluginGeomQueryCircleListPointsArgs>