@snaptrude/plugin-core 0.3.0 → 0.5.0

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

@@ -0,0 +1,540 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import {
+  ContourHandle,
+  ProfileHandle,
+  Vec3Handle,
+  Vec3Components,
+  BBoxComponents,
+} from "../../../../handles"
+
+/**
+ * Contour queries — read-only geometric questions about a contour (an outer
+ * {@linkcode ProfileHandle} plus zero or more inner profiles that act as holes)
+ * and the relationships between two contours (all-handle model, §11).
+ *
+ * Every method takes an opaque {@linkcode ContourHandle} (plus point handles
+ * {@linkcode Vec3Handle} where relevant) and returns plain values — points as
+ * {@linkcode Vec3Components}, areas/perimeters/counts as `number`, predicates as
+ * `boolean`, the bounding box as {@linkcode BBoxComponents}. Methods that
+ * enumerate the contour's child profiles return fresh {@linkcode ProfileHandle}s.
+ * No query mutates its inputs.
+ *
+ * Accessed via `snaptrude.core.geom.query.contour`.
+ */
+export abstract class PluginGeomQueryContourApi {
+  constructor() {}
+
+  /**
+   * Get the outer (boundary) profile of a contour. Host API call — mints a fresh handle.
+   * @param contour The contour to query
+   * @returns The outer profile as a {@linkcode ProfileHandle}, or `null` if the contour has no outer profile
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const outer = await snaptrude.core.geom.query.contour.getOuterProfile(contour)
+   * if (outer) console.log(await snaptrude.core.geom.query.profile.getPerimeter(outer))
+   * ```
+   */
+  public abstract getOuterProfile(
+    contour: ContourHandle
+  ): PluginApiReturn<ProfileHandle | null>
+
+  /**
+   * List the inner profiles (holes) of a contour. Host API call — mints fresh handles.
+   * @param contour The contour to query
+   * @returns The contour's holes as {@linkcode ProfileHandle}`[]`
+   *
+   * # Example
+   * ```ts
+   * const outer = await snaptrude.core.geom.create.profileRect(6, 4)
+   * const hole = await snaptrude.core.geom.create.profileRect(2, 1)
+   * const contour = await snaptrude.core.geom.create.contourFromProfiles(outer, [hole])
+   * const holes = await snaptrude.core.geom.query.contour.listHoles(contour)
+   * for (const h of holes) console.log(await snaptrude.core.geom.query.profile.getArea(h))
+   * ```
+   */
+  public abstract listHoles(
+    contour: ContourHandle
+  ): PluginApiReturn<ProfileHandle[]>
+
+  /**
+   * Get the number of inner profiles (holes) in a contour.
+   * @param contour The contour to query
+   * @returns The hole count as a `number`
+   *
+   * @examplePrompt How many holes does this shape have?
+   * @examplePrompt Count the openings in this slab outline
+   *
+   * # Example
+   * ```ts
+   * const outer = await snaptrude.core.geom.create.profileRect(6, 4)
+   * const hole = await snaptrude.core.geom.create.profileRect(2, 1)
+   * const contour = await snaptrude.core.geom.create.contourFromProfiles(outer, [hole])
+   * const count = await snaptrude.core.geom.query.contour.getHoleCount(contour) // 1
+   * ```
+   */
+  public abstract getHoleCount(
+    contour: ContourHandle
+  ): PluginApiReturn<number>
+
+  /**
+   * Get the (approximate) net enclosed area of a contour — the outer profile area
+   * minus the area of every hole.
+   * @param contour The contour to query
+   * @returns The area as a `number`
+   *
+   * @examplePrompt What is the area of this shape?
+   * @examplePrompt Calculate the usable area of this outline after subtracting its holes
+   *
+   * # Example
+   * ```ts
+   * const outer = await snaptrude.core.geom.create.profileRect(6, 4)
+   * const hole = await snaptrude.core.geom.create.profileRect(2, 1)
+   * const contour = await snaptrude.core.geom.create.contourFromProfiles(outer, [hole])
+   * const area = await snaptrude.core.geom.query.contour.getArea(contour) // 24 - 2 = 22
+   * ```
+   */
+  public abstract getArea(
+    contour: ContourHandle
+  ): PluginApiReturn<number>
+
+  /**
+   * Get the perimeter (total length of every curve) of a contour, including holes.
+   * @param contour The contour to query
+   * @returns The perimeter as a `number`
+   *
+   * @examplePrompt What is the perimeter of this shape?
+   * @examplePrompt How long is the boundary of this outline, including its holes?
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const perimeter = await snaptrude.core.geom.query.contour.getPerimeter(contour) // 14
+   * ```
+   */
+  public abstract getPerimeter(
+    contour: ContourHandle
+  ): PluginApiReturn<number>
+
+  /**
+   * Get the axis-aligned bounding box of a contour.
+   * @param contour The contour to query
+   * @returns The bounding box as {@linkcode BBoxComponents}
+   *
+   * @examplePrompt What are the overall extents of this shape?
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const { min, max } = await snaptrude.core.geom.query.contour.getBoundingBox(contour)
+   * console.log(max.x - min.x, max.z - min.z) // 4 3
+   * ```
+   */
+  public abstract getBoundingBox(
+    contour: ContourHandle
+  ): PluginApiReturn<BBoxComponents>
+
+  /**
+   * Get the unit normal vector of a contour's plane.
+   * @param contour The contour to query
+   * @returns The normal as {@linkcode Vec3Components}, or `null` if the contour has no well-defined normal
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const normal = await snaptrude.core.geom.query.contour.getNormal(contour)
+   * if (normal) console.log(normal.x, normal.y, normal.z)
+   * ```
+   */
+  public abstract getNormal(
+    contour: ContourHandle
+  ): PluginApiReturn<Vec3Components | null>
+
+  /**
+   * Get the point on a contour nearest to an arbitrary point.
+   * @param contour The contour to query
+   * @param point The reference point
+   * @returns The nearest point on the contour as {@linkcode Vec3Components}
+   *
+   * @examplePrompt Find the point on this boundary closest to a given location
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const point = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const nearest = await snaptrude.core.geom.query.contour.getNearestPoint(contour, point)
+   * console.log(nearest.x, nearest.y, nearest.z) // 2 0 0
+   * ```
+   */
+  public abstract getNearestPoint(
+    contour: ContourHandle,
+    point: Vec3Handle
+  ): PluginApiReturn<Vec3Components>
+
+  /**
+   * Test whether a point lies inside a contour (inside the outer profile and
+   * outside every hole).
+   * @param contour The contour to query
+   * @param point The point to test
+   * @returns `true` if the point is inside the contour, otherwise `false`
+   *
+   * @examplePrompt Is this point inside the shape?
+   * @examplePrompt Check whether a location falls within this boundary but not in a hole
+   *
+   * # Example
+   * ```ts
+   * const outer = await snaptrude.core.geom.create.profileRect(6, 4)
+   * const hole = await snaptrude.core.geom.create.profileRect(2, 1)
+   * const contour = await snaptrude.core.geom.create.contourFromProfiles(outer, [hole])
+   * const point = await snaptrude.core.math.vec3.new(2.5, 0, 1.5)
+   * const inside = await snaptrude.core.geom.query.contour.hasPoint(contour, point) // true — outside the hole
+   * ```
+   */
+  public abstract hasPoint(
+    contour: ContourHandle,
+    point: Vec3Handle
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Test whether a point lies on a contour's boundary (any of its curves).
+   * @param contour The contour to query
+   * @param point The point to test
+   * @returns `true` if the point is on the boundary, otherwise `false`
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const point = await snaptrude.core.math.vec3.new(2, 0, 0)
+   * const onEdge = await snaptrude.core.geom.query.contour.isOnBoundary(contour, point) // true
+   * ```
+   */
+  public abstract isOnBoundary(
+    contour: ContourHandle,
+    point: Vec3Handle
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Test whether a contour's outer profile is wound clockwise on the XZ plane.
+   * @param contour The contour to query
+   * @returns `true` if the contour is clockwise, otherwise `false`
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const clockwise = await snaptrude.core.geom.query.contour.isClockwise(contour)
+   * ```
+   */
+  public abstract isClockwise(
+    contour: ContourHandle
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Test whether a contour is planar.
+   * @param contour The contour to query
+   * @returns `true` if the contour is planar, otherwise `false`
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const planar = await snaptrude.core.geom.query.contour.isPlanar(contour) // true
+   * ```
+   */
+  public abstract isPlanar(
+    contour: ContourHandle
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Test whether a contour is empty (its outer profile contains no curves).
+   * @param contour The contour to query
+   * @returns `true` if the contour is empty, otherwise `false`
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const empty = await snaptrude.core.geom.query.contour.isEmpty(contour) // false
+   * ```
+   */
+  public abstract isEmpty(
+    contour: ContourHandle
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Test whether a contour intersects itself.
+   * @param contour The contour to query
+   * @returns `true` if the contour is self-intersecting, otherwise `false`
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const crossed = await snaptrude.core.geom.query.contour.isSelfIntersecting(contour) // false
+   * ```
+   */
+  public abstract isSelfIntersecting(
+    contour: ContourHandle
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Test whether a contour's orientation is valid (outer profile and holes are
+   * wound consistently).
+   * @param contour The contour to query
+   * @returns `true` if the orientation is valid, otherwise `false`
+   *
+   * # Example
+   * ```ts
+   * const outer = await snaptrude.core.geom.create.profileRect(6, 4)
+   * const hole = await snaptrude.core.geom.create.profileRect(2, 1)
+   * const contour = await snaptrude.core.geom.create.contourFromProfiles(outer, [hole])
+   * const valid = await snaptrude.core.geom.query.contour.isOrientationValid(contour)
+   * ```
+   */
+  public abstract isOrientationValid(
+    contour: ContourHandle
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Test whether two contours are geometrically equal.
+   * @param contourA First contour
+   * @param contourB Second contour
+   * @returns `true` if the contours are equal, otherwise `false`
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const a = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const b = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const same = await snaptrude.core.geom.query.contour.isEqual(a, b) // true
+   * ```
+   */
+  public abstract isEqual(
+    contourA: ContourHandle,
+    contourB: ContourHandle
+  ): PluginApiReturn<boolean>
+}
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryContourApi.getOuterProfile}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to query |
+ */
+export const PluginGeomQueryContourGetOuterProfileArgs = z.object({
+  contour: ContourHandle,
+})
+
+export type PluginGeomQueryContourGetOuterProfileArgs = z.infer<typeof PluginGeomQueryContourGetOuterProfileArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryContourApi.listHoles}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to query |
+ */
+export const PluginGeomQueryContourListHolesArgs = z.object({
+  contour: ContourHandle,
+})
+
+export type PluginGeomQueryContourListHolesArgs = z.infer<typeof PluginGeomQueryContourListHolesArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryContourApi.getHoleCount}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to query |
+ */
+export const PluginGeomQueryContourGetHoleCountArgs = z.object({
+  contour: ContourHandle,
+})
+
+export type PluginGeomQueryContourGetHoleCountArgs = z.infer<typeof PluginGeomQueryContourGetHoleCountArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryContourApi.getArea}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to query |
+ */
+export const PluginGeomQueryContourGetAreaArgs = z.object({
+  contour: ContourHandle,
+})
+
+export type PluginGeomQueryContourGetAreaArgs = z.infer<typeof PluginGeomQueryContourGetAreaArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryContourApi.getPerimeter}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to query |
+ */
+export const PluginGeomQueryContourGetPerimeterArgs = z.object({
+  contour: ContourHandle,
+})
+
+export type PluginGeomQueryContourGetPerimeterArgs = z.infer<typeof PluginGeomQueryContourGetPerimeterArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryContourApi.getBoundingBox}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to query |
+ */
+export const PluginGeomQueryContourGetBoundingBoxArgs = z.object({
+  contour: ContourHandle,
+})
+
+export type PluginGeomQueryContourGetBoundingBoxArgs = z.infer<typeof PluginGeomQueryContourGetBoundingBoxArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryContourApi.getNormal}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to query |
+ */
+export const PluginGeomQueryContourGetNormalArgs = z.object({
+  contour: ContourHandle,
+})
+
+export type PluginGeomQueryContourGetNormalArgs = z.infer<typeof PluginGeomQueryContourGetNormalArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryContourApi.getNearestPoint}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to query |
+ * | `point` | {@linkcode Vec3Handle} | The reference point |
+ */
+export const PluginGeomQueryContourGetNearestPointArgs = z.object({
+  contour: ContourHandle,
+  point: Vec3Handle,
+})
+
+export type PluginGeomQueryContourGetNearestPointArgs = z.infer<typeof PluginGeomQueryContourGetNearestPointArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryContourApi.hasPoint}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to query |
+ * | `point` | {@linkcode Vec3Handle} | The point to test |
+ */
+export const PluginGeomQueryContourHasPointArgs = z.object({
+  contour: ContourHandle,
+  point: Vec3Handle,
+})
+
+export type PluginGeomQueryContourHasPointArgs = z.infer<typeof PluginGeomQueryContourHasPointArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryContourApi.isOnBoundary}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to query |
+ * | `point` | {@linkcode Vec3Handle} | The point to test |
+ */
+export const PluginGeomQueryContourIsOnBoundaryArgs = z.object({
+  contour: ContourHandle,
+  point: Vec3Handle,
+})
+
+export type PluginGeomQueryContourIsOnBoundaryArgs = z.infer<typeof PluginGeomQueryContourIsOnBoundaryArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryContourApi.isClockwise}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to query |
+ */
+export const PluginGeomQueryContourIsClockwiseArgs = z.object({
+  contour: ContourHandle,
+})
+
+export type PluginGeomQueryContourIsClockwiseArgs = z.infer<typeof PluginGeomQueryContourIsClockwiseArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryContourApi.isPlanar}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to query |
+ */
+export const PluginGeomQueryContourIsPlanarArgs = z.object({
+  contour: ContourHandle,
+})
+
+export type PluginGeomQueryContourIsPlanarArgs = z.infer<typeof PluginGeomQueryContourIsPlanarArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryContourApi.isEmpty}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to query |
+ */
+export const PluginGeomQueryContourIsEmptyArgs = z.object({
+  contour: ContourHandle,
+})
+
+export type PluginGeomQueryContourIsEmptyArgs = z.infer<typeof PluginGeomQueryContourIsEmptyArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryContourApi.isSelfIntersecting}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to query |
+ */
+export const PluginGeomQueryContourIsSelfIntersectingArgs = z.object({
+  contour: ContourHandle,
+})
+
+export type PluginGeomQueryContourIsSelfIntersectingArgs = z.infer<typeof PluginGeomQueryContourIsSelfIntersectingArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryContourApi.isOrientationValid}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to query |
+ */
+export const PluginGeomQueryContourIsOrientationValidArgs = z.object({
+  contour: ContourHandle,
+})
+
+export type PluginGeomQueryContourIsOrientationValidArgs = z.infer<typeof PluginGeomQueryContourIsOrientationValidArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryContourApi.isEqual}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contourA` | {@linkcode ContourHandle} | First contour |
+ * | `contourB` | {@linkcode ContourHandle} | Second contour |
+ */
+export const PluginGeomQueryContourIsEqualArgs = z.object({
+  contourA: ContourHandle,
+  contourB: ContourHandle,
+})
+
+export type PluginGeomQueryContourIsEqualArgs = z.infer<typeof PluginGeomQueryContourIsEqualArgs>