@snaptrude/plugin-core 0.3.0 → 0.5.0

package/src/api/core/geom/update/profile.ts

@@ -0,0 +1,377 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import {
+  ProfileHandle,
+  Vec3Handle,
+  CurveHandle,
+  Vec3Components,
+} from "../../../../handles"
+
+/**
+ * Profile editing — produce NEW profiles from an existing one (all-handle model, §11).
+ *
+ * Every method is an immutable derive-new operation: it takes an opaque
+ * {@linkcode ProfileHandle} (plus any extra inputs) and returns a fresh
+ * {@linkcode ProfileHandle} for the resulting profile. The input profile is never
+ * mutated — the original handle keeps referring to the unchanged profile. Read the
+ * resulting geometry back as plain values with the query namespace.
+ *
+ * Accessed via `snaptrude.core.geom.update.profile`.
+ */
+export abstract class PluginGeomUpdateProfileApi {
+  constructor() {}
+
+  /**
+   * Offset a closed profile inward/outward by a signed distance. Immutable —
+   * returns a NEW profile and leaves the input unchanged.
+   *
+   * @param profile The closed profile to offset
+   * @param distance Signed offset distance (outward when positive, inward when negative)
+   * @returns The offset profile as a NEW {@linkcode ProfileHandle}
+   *
+   * @examplePrompt Offset this outline 300mm inward
+   * @examplePrompt Inset this boundary by a foot all around
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(10, 8)
+   * const inset = await snaptrude.core.geom.update.profile.offset(rect, -0.3)
+   * const area = await snaptrude.core.geom.query.profile.getArea(inset)
+   * ```
+   */
+  public abstract offset(
+    profile: ProfileHandle,
+    distance: number,
+  ): PluginApiReturn<ProfileHandle>
+
+  /**
+   * Translate a profile by a vector. Immutable — returns a NEW profile and leaves
+   * the input unchanged.
+   *
+   * @param profile The profile to move
+   * @param translation Translation vector to move the profile by
+   * @returns The moved profile as a NEW {@linkcode ProfileHandle}
+   *
+   * @examplePrompt Move this outline 3 metres along the x axis
+   * @examplePrompt Shift this boundary to a new position
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(6, 4)
+   * const shift = await snaptrude.core.math.vec3.new(3, 0, 0)
+   * const moved = await snaptrude.core.geom.update.profile.move(rect, shift)
+   * ```
+   */
+  public abstract move(
+    profile: ProfileHandle,
+    translation: Vec3Handle,
+  ): PluginApiReturn<ProfileHandle>
+
+  /**
+   * Rotate a profile about an axis through an optional pivot. Immutable — returns a
+   * NEW profile and leaves the input unchanged.
+   *
+   * @param profile The profile to rotate
+   * @param axis Rotation axis direction
+   * @param angle Rotation angle in radians
+   * @param pivot Optional pivot point to rotate about (defaults to the origin)
+   * @returns The rotated profile as a NEW {@linkcode ProfileHandle}
+   *
+   * @examplePrompt Rotate this outline 30 degrees
+   * @examplePrompt Turn this boundary about its centre point
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(6, 4)
+   * const axis = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const rotated = await snaptrude.core.geom.update.profile.rotate(rect, axis, Math.PI / 6)
+   * ```
+   */
+  public abstract rotate(
+    profile: ProfileHandle,
+    axis: Vec3Handle,
+    angle: number,
+    pivot?: Vec3Handle,
+  ): PluginApiReturn<ProfileHandle>
+
+  /**
+   * Scale a profile uniformly or per-axis about an optional pivot. Immutable —
+   * returns a NEW profile and leaves the input unchanged.
+   *
+   * @param profile The profile to scale
+   * @param factor Uniform scale factor, or per-axis factors
+   * @param pivot Optional pivot point to scale about (defaults to the origin)
+   * @returns The scaled profile as a NEW {@linkcode ProfileHandle}
+   *
+   * @examplePrompt Scale this outline down to half size
+   * @examplePrompt Enlarge this boundary by 50 percent
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(6, 4)
+   * const half = await snaptrude.core.geom.update.profile.scale(rect, 0.5)
+   * const stretched = await snaptrude.core.geom.update.profile.scale(rect, { x: 2, y: 1, z: 1 })
+   * ```
+   */
+  public abstract scale(
+    profile: ProfileHandle,
+    factor: number | Vec3Components,
+    pivot?: Vec3Handle,
+  ): PluginApiReturn<ProfileHandle>
+
+  /**
+   * Mirror a profile across a plane. Immutable — returns a NEW profile and leaves
+   * the input unchanged.
+   *
+   * @param profile The profile to mirror
+   * @param plane Mirror plane defined by a point on it and its normal
+   * @returns The mirrored profile as a NEW {@linkcode ProfileHandle}
+   *
+   * @examplePrompt Mirror this outline across the vertical plane
+   * @examplePrompt Flip this boundary to its mirror image
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(6, 4)
+   * const point = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const normal = await snaptrude.core.math.vec3.new(1, 0, 0)
+   * const mirrored = await snaptrude.core.geom.update.profile.mirror(rect, { point, normal })
+   * ```
+   */
+  public abstract mirror(
+    profile: ProfileHandle,
+    plane: { point: Vec3Handle; normal: Vec3Handle },
+  ): PluginApiReturn<ProfileHandle>
+
+  /**
+   * Append a curve to the start or end of a profile. The curve must connect to the
+   * chosen end. Immutable — returns a NEW profile and leaves the input unchanged.
+   *
+   * @param profile The profile to append to
+   * @param curve The curve to append; it must connect to the chosen end
+   * @param position Optional end to append at (defaults to `"end"`)
+   * @returns The extended profile as a NEW {@linkcode ProfileHandle}
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const open = await snaptrude.core.geom.update.profile.remove(rect, "end")
+   * const pts = await snaptrude.core.geom.query.profile.listPoints(open)
+   * const last = pts[pts.length - 1]
+   * const from = await snaptrude.core.math.vec3.new(last.x, last.y, last.z)
+   * const to = await snaptrude.core.math.vec3.new(pts[0].x, pts[0].y, pts[0].z)
+   * const closer = await snaptrude.core.geom.create.line(from, to)
+   * const closed = await snaptrude.core.geom.update.profile.add(open, closer, "end")
+   * ```
+   */
+  public abstract add(
+    profile: ProfileHandle,
+    curve: CurveHandle,
+    position?: "start" | "end",
+  ): PluginApiReturn<ProfileHandle>
+
+  /**
+   * Remove the curve at the start or end of a profile. Immutable — returns a NEW
+   * profile and leaves the input unchanged.
+   *
+   * @param profile The profile to remove a curve from
+   * @param position Optional end to remove from (defaults to `"end"`)
+   * @returns The trimmed profile as a NEW {@linkcode ProfileHandle}
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const open = await snaptrude.core.geom.update.profile.remove(rect, "end")
+   * const isClosed = await snaptrude.core.geom.query.profile.isClosed(open) // false
+   * ```
+   */
+  public abstract remove(
+    profile: ProfileHandle,
+    position?: "start" | "end",
+  ): PluginApiReturn<ProfileHandle>
+
+  /**
+   * Reverse the orientation of a profile. Immutable — returns a NEW profile and
+   * leaves the input unchanged.
+   *
+   * @param profile The profile to reverse
+   * @returns The reversed profile as a NEW {@linkcode ProfileHandle}
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const reversed = await snaptrude.core.geom.update.profile.reverse(rect)
+   * const clockwise = await snaptrude.core.geom.query.profile.isClockwise(reversed)
+   * ```
+   */
+  public abstract reverse(
+    profile: ProfileHandle,
+  ): PluginApiReturn<ProfileHandle>
+
+  /**
+   * Simplify a profile by merging collinear/redundant segments. Immutable —
+   * returns a NEW profile and leaves the input unchanged.
+   *
+   * @param profile The profile to simplify
+   * @returns The simplified profile as a NEW {@linkcode ProfileHandle}
+   *
+   * @examplePrompt Clean up this outline by merging collinear segments
+   * @examplePrompt Simplify this polyline and remove redundant points
+   *
+   * # Example
+   * ```ts
+   * const p0 = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const p1 = await snaptrude.core.math.vec3.new(2, 0, 0) // collinear with p0 and p2
+   * const p2 = await snaptrude.core.math.vec3.new(4, 0, 0)
+   * const p3 = await snaptrude.core.math.vec3.new(4, 0, 3)
+   * const jagged = await snaptrude.core.geom.create.profileFromLinePoints([p0, p1, p2, p3])
+   * const clean = await snaptrude.core.geom.update.profile.simplify(jagged)
+   * const curves = await snaptrude.core.geom.query.profile.listCurves(clean) // p0→p2 merged
+   * ```
+   */
+  public abstract simplify(
+    profile: ProfileHandle,
+  ): PluginApiReturn<ProfileHandle>
+}
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateProfileApi.offset}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ProfileHandle} | The closed profile to offset |
+ * | `distance` | `number` | Signed offset distance (outward when positive, inward when negative) |
+ */
+export const PluginGeomUpdateProfileOffsetArgs = z.object({
+  profile: ProfileHandle,
+  distance: z.number(),
+})
+
+export type PluginGeomUpdateProfileOffsetArgs = z.infer<typeof PluginGeomUpdateProfileOffsetArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateProfileApi.move}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ProfileHandle} | The profile to move |
+ * | `translation` | {@linkcode Vec3Handle} | Translation vector to move the profile by |
+ */
+export const PluginGeomUpdateProfileMoveArgs = z.object({
+  profile: ProfileHandle,
+  translation: Vec3Handle,
+})
+
+export type PluginGeomUpdateProfileMoveArgs = z.infer<typeof PluginGeomUpdateProfileMoveArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateProfileApi.rotate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ProfileHandle} | The profile to rotate |
+ * | `axis` | {@linkcode Vec3Handle} | Rotation axis direction |
+ * | `angle` | `number` | Rotation angle in radians |
+ * | `pivot` | {@linkcode Vec3Handle} | Optional pivot point to rotate about (defaults to the origin) |
+ */
+export const PluginGeomUpdateProfileRotateArgs = z.object({
+  profile: ProfileHandle,
+  axis: Vec3Handle,
+  angle: z.number(),
+  pivot: Vec3Handle.optional(),
+})
+
+export type PluginGeomUpdateProfileRotateArgs = z.infer<typeof PluginGeomUpdateProfileRotateArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateProfileApi.scale}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ProfileHandle} | The profile to scale |
+ * | `factor` | `number` \| {@linkcode Vec3Components} | Uniform scale factor, or per-axis factors |
+ * | `pivot` | {@linkcode Vec3Handle} | Optional pivot point to scale about (defaults to the origin) |
+ */
+export const PluginGeomUpdateProfileScaleArgs = z.object({
+  profile: ProfileHandle,
+  factor: z.union([z.number(), Vec3Components]),
+  pivot: Vec3Handle.optional(),
+})
+
+export type PluginGeomUpdateProfileScaleArgs = z.infer<typeof PluginGeomUpdateProfileScaleArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateProfileApi.mirror}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ProfileHandle} | The profile to mirror |
+ * | `plane` | `{ point: `{@linkcode Vec3Handle}`, normal: `{@linkcode Vec3Handle}` }` | Mirror plane defined by a point on it and its normal |
+ */
+export const PluginGeomUpdateProfileMirrorArgs = z.object({
+  profile: ProfileHandle,
+  plane: z.object({
+    point: Vec3Handle,
+    normal: Vec3Handle,
+  }),
+})
+
+export type PluginGeomUpdateProfileMirrorArgs = z.infer<typeof PluginGeomUpdateProfileMirrorArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateProfileApi.add}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ProfileHandle} | The profile to append to |
+ * | `curve` | {@linkcode CurveHandle} | The curve to append; it must connect to the chosen end |
+ * | `position` | `"start"` \| `"end"` | Optional end to append at (defaults to `"end"`) |
+ */
+export const PluginGeomUpdateProfileAddArgs = z.object({
+  profile: ProfileHandle,
+  curve: CurveHandle,
+  position: z.enum(["start", "end"]).optional(),
+})
+
+export type PluginGeomUpdateProfileAddArgs = z.infer<typeof PluginGeomUpdateProfileAddArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateProfileApi.remove}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ProfileHandle} | The profile to remove a curve from |
+ * | `position` | `"start"` \| `"end"` | Optional end to remove from (defaults to `"end"`) |
+ */
+export const PluginGeomUpdateProfileRemoveArgs = z.object({
+  profile: ProfileHandle,
+  position: z.enum(["start", "end"]).optional(),
+})
+
+export type PluginGeomUpdateProfileRemoveArgs = z.infer<typeof PluginGeomUpdateProfileRemoveArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateProfileApi.reverse}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ProfileHandle} | The profile to reverse |
+ */
+export const PluginGeomUpdateProfileReverseArgs = z.object({
+  profile: ProfileHandle,
+})
+
+export type PluginGeomUpdateProfileReverseArgs = z.infer<typeof PluginGeomUpdateProfileReverseArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateProfileApi.simplify}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ProfileHandle} | The profile to simplify |
+ */
+export const PluginGeomUpdateProfileSimplifyArgs = z.object({
+  profile: ProfileHandle,
+})
+
+export type PluginGeomUpdateProfileSimplifyArgs = z.infer<typeof PluginGeomUpdateProfileSimplifyArgs>