@snaptrude/plugin-core 0.3.0 → 0.5.0

package/dist/api/core/geom/update/profile.d.ts

@@ -0,0 +1,329 @@
+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 declare 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)
+     * ```
+     */
+    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)
+     * ```
+     */
+    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)
+     * ```
+     */
+    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 })
+     * ```
+     */
+    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 })
+     * ```
+     */
+    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")
+     * ```
+     */
+    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
+     * ```
+     */
+    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)
+     * ```
+     */
+    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
+     * ```
+     */
+    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 declare const PluginGeomUpdateProfileOffsetArgs: z.ZodObject<{
+    profile: z.ZodPipe<z.ZodString, z.ZodTransform<import("../../../..").Handle<"profile">, string>>;
+    distance: z.ZodNumber;
+}, z.core.$strip>;
+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 declare const PluginGeomUpdateProfileMoveArgs: z.ZodObject<{
+    profile: z.ZodPipe<z.ZodString, z.ZodTransform<import("../../../..").Handle<"profile">, string>>;
+    translation: z.ZodPipe<z.ZodString, z.ZodTransform<import("../../../..").Handle<"vec3">, string>>;
+}, z.core.$strip>;
+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 declare const PluginGeomUpdateProfileRotateArgs: z.ZodObject<{
+    profile: z.ZodPipe<z.ZodString, z.ZodTransform<import("../../../..").Handle<"profile">, string>>;
+    axis: z.ZodPipe<z.ZodString, z.ZodTransform<import("../../../..").Handle<"vec3">, string>>;
+    angle: z.ZodNumber;
+    pivot: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("../../../..").Handle<"vec3">, string>>>;
+}, z.core.$strip>;
+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 declare const PluginGeomUpdateProfileScaleArgs: z.ZodObject<{
+    profile: z.ZodPipe<z.ZodString, z.ZodTransform<import("../../../..").Handle<"profile">, string>>;
+    factor: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strip>]>;
+    pivot: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("../../../..").Handle<"vec3">, string>>>;
+}, z.core.$strip>;
+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 declare const PluginGeomUpdateProfileMirrorArgs: z.ZodObject<{
+    profile: z.ZodPipe<z.ZodString, z.ZodTransform<import("../../../..").Handle<"profile">, string>>;
+    plane: z.ZodObject<{
+        point: z.ZodPipe<z.ZodString, z.ZodTransform<import("../../../..").Handle<"vec3">, string>>;
+        normal: z.ZodPipe<z.ZodString, z.ZodTransform<import("../../../..").Handle<"vec3">, string>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+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 declare const PluginGeomUpdateProfileAddArgs: z.ZodObject<{
+    profile: z.ZodPipe<z.ZodString, z.ZodTransform<import("../../../..").Handle<"profile">, string>>;
+    curve: z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<import("../../../..").Handle<"line">, string>>, z.ZodPipe<z.ZodString, z.ZodTransform<import("../../../..").Handle<"arc">, string>>]>;
+    position: z.ZodOptional<z.ZodEnum<{
+        start: "start";
+        end: "end";
+    }>>;
+}, z.core.$strip>;
+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 declare const PluginGeomUpdateProfileRemoveArgs: z.ZodObject<{
+    profile: z.ZodPipe<z.ZodString, z.ZodTransform<import("../../../..").Handle<"profile">, string>>;
+    position: z.ZodOptional<z.ZodEnum<{
+        start: "start";
+        end: "end";
+    }>>;
+}, z.core.$strip>;
+export type PluginGeomUpdateProfileRemoveArgs = z.infer<typeof PluginGeomUpdateProfileRemoveArgs>;
+/**
+ * Arguments for {@linkcode PluginGeomUpdateProfileApi.reverse}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ProfileHandle} | The profile to reverse |
+ */
+export declare const PluginGeomUpdateProfileReverseArgs: z.ZodObject<{
+    profile: z.ZodPipe<z.ZodString, z.ZodTransform<import("../../../..").Handle<"profile">, string>>;
+}, z.core.$strip>;
+export type PluginGeomUpdateProfileReverseArgs = z.infer<typeof PluginGeomUpdateProfileReverseArgs>;
+/**
+ * Arguments for {@linkcode PluginGeomUpdateProfileApi.simplify}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ProfileHandle} | The profile to simplify |
+ */
+export declare const PluginGeomUpdateProfileSimplifyArgs: z.ZodObject<{
+    profile: z.ZodPipe<z.ZodString, z.ZodTransform<import("../../../..").Handle<"profile">, string>>;
+}, z.core.$strip>;
+export type PluginGeomUpdateProfileSimplifyArgs = z.infer<typeof PluginGeomUpdateProfileSimplifyArgs>;
+//# sourceMappingURL=profile.d.ts.map

package/dist/api/core/geom/update/profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../../../../src/api/core/geom/update/profile.ts"],"names":[],"mappings":"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"}