@genart-dev/plugin-construction 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,211 @@
+import { LayerTypeDefinition, McpToolDefinition, DesignPlugin } from '@genart-dev/core';
+
+declare const formLayerType: LayerTypeDefinition;
+
+declare const crossContourLayerType: LayerTypeDefinition;
+
+declare const valueShapesLayerType: LayerTypeDefinition;
+
+declare const envelopeLayerType: LayerTypeDefinition;
+
+declare const intersectionLayerType: LayerTypeDefinition;
+
+declare const constructionMcpTools: McpToolDefinition[];
+
+/** 3D vector. */
+interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/** 2D vector. */
+interface Vec2 {
+    x: number;
+    y: number;
+}
+/** 3x3 matrix stored as row-major flat array. */
+type Mat3 = [
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number
+];
+/** Clamp a value to [min, max]. */
+declare function clamp(v: number, min: number, max: number): number;
+/**
+ * Build a ZYX Euler rotation matrix from angles in degrees.
+ * rotationX is clamped to [-90, 90] to avoid gimbal lock.
+ *
+ * R = Rz * Ry * Rx
+ */
+declare function rotationMatrix(rxDeg: number, ryDeg: number, rzDeg: number): Mat3;
+/** Multiply a Mat3 by a Vec3, returning a new Vec3. */
+declare function rotate3D(point: Vec3, m: Mat3): Vec3;
+/**
+ * Project a 3D point to 2D.
+ *
+ * - "orthographic": drops Z (screen.x = point.x, screen.y = point.y)
+ * - "weak-perspective": mild foreshortening based on Z depth
+ *   scale = focalLength / (focalLength + point.z)
+ */
+declare function project(point: Vec3, projection?: "orthographic" | "weak-perspective", focalLength?: number): Vec2;
+/**
+ * Convenience: rotate a 3D point then project to 2D.
+ * rotationX is clamped to [-90, 90].
+ */
+declare function transformPoint(point: Vec3, rxDeg: number, ryDeg: number, rzDeg: number, projection?: "orthographic" | "weak-perspective", focalLength?: number): Vec2;
+/** Transform a 3D normal vector and return the Z component (for face visibility). */
+declare function transformedNormalZ(normal: Vec3, m: Mat3): number;
+/** Compute the identity matrix. */
+declare function identityMatrix(): Mat3;
+/** Multiply two Mat3 matrices: result = a * b. */
+declare function multiplyMat3(a: Mat3, b: Mat3): Mat3;
+/** Normalize a Vec3 to unit length. Returns zero vector if length is ~0. */
+declare function normalize3(v: Vec3): Vec3;
+/** Dot product of two Vec3. */
+declare function dot3(a: Vec3, b: Vec3): number;
+/** Cross product of two Vec3. */
+declare function cross3(a: Vec3, b: Vec3): Vec3;
+
+interface EllipseParams {
+    cx: number;
+    cy: number;
+    rx: number;
+    ry: number;
+    rotation: number;
+}
+/**
+ * Compute ellipse parameters from a circle viewed at an angle.
+ *
+ * A circle of `radius` whose normal is tilted by `normalTilt` degrees from
+ * the viewer becomes an ellipse with:
+ *   - major axis = radius (unchanged)
+ *   - minor axis = radius * |cos(normalTilt)|
+ *
+ * `axisRotation` is the rotation of the ellipse's major axis on the 2D plane (degrees).
+ */
+declare function projectedEllipse(center: Vec2, radius: number, normalTilt: number, axisRotation: number): EllipseParams;
+/**
+ * Draw an ellipse (or partial arc) on a Canvas2D context.
+ * Strokes the path — caller should set strokeStyle/lineWidth beforehand.
+ *
+ * @param startAngle - Arc start in radians (default 0)
+ * @param endAngle - Arc end in radians (default 2π)
+ * @param counterclockwise - Direction of arc (default false)
+ */
+declare function drawEllipse(ctx: CanvasRenderingContext2D, cx: number, cy: number, rx: number, ry: number, rotation: number, startAngle?: number, endAngle?: number, counterclockwise?: boolean): void;
+/**
+ * Draw an ellipse with separate visible and hidden arcs.
+ * The "front" half (facing viewer) is drawn solid;
+ * the "back" half is drawn with the provided hidden style.
+ *
+ * @param frontHalf - Angle range in radians for the visible portion [start, end]
+ * @param hiddenAlpha - Alpha for hidden portion
+ * @param hiddenDash - Dash pattern for hidden portion
+ */
+declare function drawEllipseWithHidden(ctx: CanvasRenderingContext2D, params: EllipseParams, frontHalf: [number, number], hiddenAlpha: number, hiddenDash: number[]): void;
+/**
+ * Compute points along an ellipse for use in path construction.
+ */
+declare function ellipsePoints(params: EllipseParams, segments: number, startAngle?: number, endAngle?: number): Vec2[];
+
+interface LightSource {
+    azimuth: number;
+    elevation: number;
+    intensity: number;
+}
+/**
+ * Compute a 3D light direction vector from azimuth and elevation.
+ * Returns a unit vector pointing FROM the light TOWARD the scene.
+ */
+declare function lightDirection(light: LightSource): Vec3;
+/**
+ * Compute the light direction as a 2D vector for rendering indicators.
+ * Points from center toward where light is coming from.
+ */
+declare function lightDirection2D(light: LightSource): Vec2;
+/**
+ * Compute the terminator ellipse on a sphere.
+ * The terminator is a great circle perpendicular to the light direction.
+ */
+declare function sphereTerminator(center: Vec2, radius: number, light: LightSource, matrix: Mat3): {
+    terminatorEllipse: EllipseParams;
+    lightSide: Vec2;
+};
+/**
+ * Compute a simple cast shadow polygon on the ground plane.
+ * Projects the form's bottom silhouette along the light direction.
+ */
+declare function castShadow(center: Vec2, radius: number, light: LightSource, groundY: number): Vec2[];
+type ValueGrouping = "two-value" | "three-value" | "five-value";
+interface ValueZone {
+    type: "highlight" | "light" | "halftone" | "core-shadow" | "reflected-light" | "cast-shadow" | "occlusion-shadow";
+    path: Vec2[];
+    value: number;
+    label: string;
+}
+/**
+ * Compute value zones for a sphere at a given position.
+ * Returns an array of zones with polygon paths and values.
+ */
+declare function sphereValueZones(center: Vec2, radius: number, light: LightSource, matrix: Mat3, grouping: ValueGrouping): ValueZone[];
+
+/**
+ * Compute envelope from points based on style.
+ * - "tight": convex hull
+ * - "loose": convex hull expanded outward
+ * - "fitted": the original polygon (straight lines connecting input points in order)
+ */
+declare function computeEnvelope(points: Vec2[], style: "tight" | "loose" | "fitted"): Vec2[];
+/**
+ * Compute angles at each vertex of an envelope polygon.
+ * Returns the interior angle in degrees at each vertex.
+ */
+declare function envelopeAngles(vertices: Vec2[]): Array<{
+    vertex: Vec2;
+    angle: number;
+}>;
+/** Vertical plumb line through a reference point, clipped to bounds. */
+declare function plumbLine(referencePoint: Vec2, bounds: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): [Vec2, Vec2];
+/** Horizontal level line through a reference point, clipped to bounds. */
+declare function levelLine(referencePoint: Vec2, bounds: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): [Vec2, Vec2];
+/** Comparative measurement between two segments. Returns ratio and label. */
+declare function comparativeMeasure(segment1: [Vec2, Vec2], segment2: [Vec2, Vec2]): {
+    ratio: number;
+    label: string;
+};
+
+type FormType = "box" | "cylinder" | "sphere" | "cone" | "wedge" | "egg";
+interface FormDefinition {
+    type: FormType;
+    position: Vec3;
+    size: Vec3;
+    rotation: Vec3;
+}
+
+/**
+ * Approximate form intersection by sampling both surfaces and finding
+ * points where they are equidistant from the camera (same Z depth).
+ *
+ * Returns a projected 2D polyline approximating the intersection curve.
+ */
+declare function approximateIntersection(form1: FormDefinition, form2: FormDefinition, samples?: number): Vec2[];
+
+declare const constructionPlugin: DesignPlugin;
+
+export { approximateIntersection, castShadow, clamp, comparativeMeasure, computeEnvelope, constructionMcpTools, cross3, crossContourLayerType, constructionPlugin as default, dot3, drawEllipse, drawEllipseWithHidden, ellipsePoints, envelopeAngles, envelopeLayerType, formLayerType, identityMatrix, intersectionLayerType, levelLine, lightDirection, lightDirection2D, multiplyMat3, normalize3, plumbLine, project, projectedEllipse, rotate3D, rotationMatrix, sphereTerminator, sphereValueZones, transformPoint, transformedNormalZ, valueShapesLayerType };

package/dist/index.d.ts

@@ -0,0 +1,211 @@
+import { LayerTypeDefinition, McpToolDefinition, DesignPlugin } from '@genart-dev/core';
+
+declare const formLayerType: LayerTypeDefinition;
+
+declare const crossContourLayerType: LayerTypeDefinition;
+
+declare const valueShapesLayerType: LayerTypeDefinition;
+
+declare const envelopeLayerType: LayerTypeDefinition;
+
+declare const intersectionLayerType: LayerTypeDefinition;
+
+declare const constructionMcpTools: McpToolDefinition[];
+
+/** 3D vector. */
+interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/** 2D vector. */
+interface Vec2 {
+    x: number;
+    y: number;
+}
+/** 3x3 matrix stored as row-major flat array. */
+type Mat3 = [
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number
+];
+/** Clamp a value to [min, max]. */
+declare function clamp(v: number, min: number, max: number): number;
+/**
+ * Build a ZYX Euler rotation matrix from angles in degrees.
+ * rotationX is clamped to [-90, 90] to avoid gimbal lock.
+ *
+ * R = Rz * Ry * Rx
+ */
+declare function rotationMatrix(rxDeg: number, ryDeg: number, rzDeg: number): Mat3;
+/** Multiply a Mat3 by a Vec3, returning a new Vec3. */
+declare function rotate3D(point: Vec3, m: Mat3): Vec3;
+/**
+ * Project a 3D point to 2D.
+ *
+ * - "orthographic": drops Z (screen.x = point.x, screen.y = point.y)
+ * - "weak-perspective": mild foreshortening based on Z depth
+ *   scale = focalLength / (focalLength + point.z)
+ */
+declare function project(point: Vec3, projection?: "orthographic" | "weak-perspective", focalLength?: number): Vec2;
+/**
+ * Convenience: rotate a 3D point then project to 2D.
+ * rotationX is clamped to [-90, 90].
+ */
+declare function transformPoint(point: Vec3, rxDeg: number, ryDeg: number, rzDeg: number, projection?: "orthographic" | "weak-perspective", focalLength?: number): Vec2;
+/** Transform a 3D normal vector and return the Z component (for face visibility). */
+declare function transformedNormalZ(normal: Vec3, m: Mat3): number;
+/** Compute the identity matrix. */
+declare function identityMatrix(): Mat3;
+/** Multiply two Mat3 matrices: result = a * b. */
+declare function multiplyMat3(a: Mat3, b: Mat3): Mat3;
+/** Normalize a Vec3 to unit length. Returns zero vector if length is ~0. */
+declare function normalize3(v: Vec3): Vec3;
+/** Dot product of two Vec3. */
+declare function dot3(a: Vec3, b: Vec3): number;
+/** Cross product of two Vec3. */
+declare function cross3(a: Vec3, b: Vec3): Vec3;
+
+interface EllipseParams {
+    cx: number;
+    cy: number;
+    rx: number;
+    ry: number;
+    rotation: number;
+}
+/**
+ * Compute ellipse parameters from a circle viewed at an angle.
+ *
+ * A circle of `radius` whose normal is tilted by `normalTilt` degrees from
+ * the viewer becomes an ellipse with:
+ *   - major axis = radius (unchanged)
+ *   - minor axis = radius * |cos(normalTilt)|
+ *
+ * `axisRotation` is the rotation of the ellipse's major axis on the 2D plane (degrees).
+ */
+declare function projectedEllipse(center: Vec2, radius: number, normalTilt: number, axisRotation: number): EllipseParams;
+/**
+ * Draw an ellipse (or partial arc) on a Canvas2D context.
+ * Strokes the path — caller should set strokeStyle/lineWidth beforehand.
+ *
+ * @param startAngle - Arc start in radians (default 0)
+ * @param endAngle - Arc end in radians (default 2π)
+ * @param counterclockwise - Direction of arc (default false)
+ */
+declare function drawEllipse(ctx: CanvasRenderingContext2D, cx: number, cy: number, rx: number, ry: number, rotation: number, startAngle?: number, endAngle?: number, counterclockwise?: boolean): void;
+/**
+ * Draw an ellipse with separate visible and hidden arcs.
+ * The "front" half (facing viewer) is drawn solid;
+ * the "back" half is drawn with the provided hidden style.
+ *
+ * @param frontHalf - Angle range in radians for the visible portion [start, end]
+ * @param hiddenAlpha - Alpha for hidden portion
+ * @param hiddenDash - Dash pattern for hidden portion
+ */
+declare function drawEllipseWithHidden(ctx: CanvasRenderingContext2D, params: EllipseParams, frontHalf: [number, number], hiddenAlpha: number, hiddenDash: number[]): void;
+/**
+ * Compute points along an ellipse for use in path construction.
+ */
+declare function ellipsePoints(params: EllipseParams, segments: number, startAngle?: number, endAngle?: number): Vec2[];
+
+interface LightSource {
+    azimuth: number;
+    elevation: number;
+    intensity: number;
+}
+/**
+ * Compute a 3D light direction vector from azimuth and elevation.
+ * Returns a unit vector pointing FROM the light TOWARD the scene.
+ */
+declare function lightDirection(light: LightSource): Vec3;
+/**
+ * Compute the light direction as a 2D vector for rendering indicators.
+ * Points from center toward where light is coming from.
+ */
+declare function lightDirection2D(light: LightSource): Vec2;
+/**
+ * Compute the terminator ellipse on a sphere.
+ * The terminator is a great circle perpendicular to the light direction.
+ */
+declare function sphereTerminator(center: Vec2, radius: number, light: LightSource, matrix: Mat3): {
+    terminatorEllipse: EllipseParams;
+    lightSide: Vec2;
+};
+/**
+ * Compute a simple cast shadow polygon on the ground plane.
+ * Projects the form's bottom silhouette along the light direction.
+ */
+declare function castShadow(center: Vec2, radius: number, light: LightSource, groundY: number): Vec2[];
+type ValueGrouping = "two-value" | "three-value" | "five-value";
+interface ValueZone {
+    type: "highlight" | "light" | "halftone" | "core-shadow" | "reflected-light" | "cast-shadow" | "occlusion-shadow";
+    path: Vec2[];
+    value: number;
+    label: string;
+}
+/**
+ * Compute value zones for a sphere at a given position.
+ * Returns an array of zones with polygon paths and values.
+ */
+declare function sphereValueZones(center: Vec2, radius: number, light: LightSource, matrix: Mat3, grouping: ValueGrouping): ValueZone[];
+
+/**
+ * Compute envelope from points based on style.
+ * - "tight": convex hull
+ * - "loose": convex hull expanded outward
+ * - "fitted": the original polygon (straight lines connecting input points in order)
+ */
+declare function computeEnvelope(points: Vec2[], style: "tight" | "loose" | "fitted"): Vec2[];
+/**
+ * Compute angles at each vertex of an envelope polygon.
+ * Returns the interior angle in degrees at each vertex.
+ */
+declare function envelopeAngles(vertices: Vec2[]): Array<{
+    vertex: Vec2;
+    angle: number;
+}>;
+/** Vertical plumb line through a reference point, clipped to bounds. */
+declare function plumbLine(referencePoint: Vec2, bounds: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): [Vec2, Vec2];
+/** Horizontal level line through a reference point, clipped to bounds. */
+declare function levelLine(referencePoint: Vec2, bounds: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): [Vec2, Vec2];
+/** Comparative measurement between two segments. Returns ratio and label. */
+declare function comparativeMeasure(segment1: [Vec2, Vec2], segment2: [Vec2, Vec2]): {
+    ratio: number;
+    label: string;
+};
+
+type FormType = "box" | "cylinder" | "sphere" | "cone" | "wedge" | "egg";
+interface FormDefinition {
+    type: FormType;
+    position: Vec3;
+    size: Vec3;
+    rotation: Vec3;
+}
+
+/**
+ * Approximate form intersection by sampling both surfaces and finding
+ * points where they are equidistant from the camera (same Z depth).
+ *
+ * Returns a projected 2D polyline approximating the intersection curve.
+ */
+declare function approximateIntersection(form1: FormDefinition, form2: FormDefinition, samples?: number): Vec2[];
+
+declare const constructionPlugin: DesignPlugin;
+
+export { approximateIntersection, castShadow, clamp, comparativeMeasure, computeEnvelope, constructionMcpTools, cross3, crossContourLayerType, constructionPlugin as default, dot3, drawEllipse, drawEllipseWithHidden, ellipsePoints, envelopeAngles, envelopeLayerType, formLayerType, identityMatrix, intersectionLayerType, levelLine, lightDirection, lightDirection2D, multiplyMat3, normalize3, plumbLine, project, projectedEllipse, rotate3D, rotationMatrix, sphereTerminator, sphereValueZones, transformPoint, transformedNormalZ, valueShapesLayerType };