@liquidcars/atlas-geometry-processes 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# @liquidcars/atlas-geometry-processes
+
+Independent 3D geometry pack for standard process and flowchart symbols in
+@liquidcars/atlas.
+
+~~~js
+import "@liquidcars/atlas";
+import "@liquidcars/atlas-geometry-processes";
+~~~
+
+The import registers the process.* geometry namespace. The pack is declarative
+from the host's point of view: it contributes canonical sizes, typed
+parameters, local palette colors, named anchors and compound parts, but does
+not depend on Three.js.
+
+## Included symbols
+
+| Geometry | Use |
+| --- | --- |
+| process.terminator | Start/end |
+| process.activity | Task, subprocess or call activity |
+| process.decision | Decision/gateway |
+| process.data | Data input/output |
+| process.manual-operation | Manual operation |
+| process.document | Document or record |
+| process.predefined-process | Reusable named routine |
+| process.stored-data | Persistent data store |
+| process.internal-storage | Internal storage |
+| process.direct-data | Disk/drum-like direct data |
+| process.manual-input | Manual data entry |
+| process.preparation | Preparation/setup |
+| process.parallel-mode | Parallel execution |
+| process.loop-limit | Bounded loop |
+| process.display | User-facing display |
+| process.connector | In-page sequence/junction |
+| process.off-page-reference | Continuation on another page |
+| process.annotation | Note attached to a symbol |
+| process.control-transfer | Control-flow transfer |
+| process.condition | Condition/rule gate |
+
+The symbols are intentionally process-oriented rather than generic primitives:
+they preserve the visual vocabulary of flowcharts while remaining volumetric,
+selectable and compatible with Atlas relations.
+
+## Example
+
+~~~yaml
+- id: receive-order
+  name: Receive order
+  geometry: process.terminator
+  geometryOptions:
+    kind: start
+
+- id: validate-order
+  name: Validate order
+  geometry: process.activity
+  geometryOptions:
+    variant: task
+    icon: "✓"
+
+- id: order-valid
+  name: Order valid?
+  geometry: process.decision
+  geometryOptions:
+    outcome: neutral
+
+- id: rejected
+  name: Rejected
+  geometry: process.document
+  geometryOptions:
+    icon: "!"
+
+relations:
+  - from: receive-order
+    to: validate-order
+    label: begins
+  - from: validate-order
+    to: order-valid
+    label: checks
+  - from: order-valid
+    to: rejected
+    label: "no"
+~~~
+
+A local palette can override the default colors without changing the model
+semantics:
+
+~~~json
+{
+  "geometry": "process.display",
+  "geometryOptions": {
+    "screen": "active",
+    "icon": "UI"
+  },
+  "geometryPalette": {
+    "body": "#263746",
+    "accent": "#f4d35e"
+  }
+}
+~~~
+
+Icons and images are optional. A symbol stays clean when no marker is supplied.
+Images accept browser-loadable URLs or data URIs; external hosts must permit
+cross-origin loading when required by the browser.
+
+## Design notes
+
+The first release follows common flowchart semantics visible in standard
+process-symbol libraries. Some symbols, such as a document's curved lower edge
+or a manual-input parallelogram, are represented as stylized 3D compounds so
+they remain legible from the interactive camera instead of pretending to be
+flat 2D SVG glyphs.
+
+The pack uses namespace process and registers itself on import:
+
+~~~js
+import processGeometryPack from "@liquidcars/atlas-geometry-processes";
+
+console.log(processGeometryPack.geometries.map(geometry => geometry.id));
+~~~

package/index.js

@@ -0,0 +1,489 @@
+import { registerGeometryPack } from "@liquidcars/atlas";
+
+const clamp = (value, minimum, maximum) => Math.min(maximum, Math.max(minimum, Number(value) || minimum));
+
+const frontMarker = (parameters, color = "accent", position = [0, 0, .54], size = [.3, .24, 1]) => {
+  if (!parameters?.icon && !parameters?.image) return [];
+  return [{
+    shape: "plane",
+    size,
+    position,
+    color: parameters.image ? "#ffffff" : color,
+    icon: parameters.icon,
+    image: parameters.image,
+    iconColor: "#ffffff",
+    edges: false,
+    doubleSided: true
+  }];
+};
+
+const frontLine = (position, size, color = "accent") => ({
+  shape: "box",
+  size,
+  position,
+  color,
+  edges: false,
+  metalness: .12
+});
+
+const processPalette = {
+  body: "#496879",
+  edge: "#8fd3ee",
+  process: "#4d7d91",
+  decision: "#d19a54",
+  data: "#5e9f9a",
+  input: "#6c8fb7",
+  paper: "#8ca9b7",
+  storage: "#597887",
+  accent: "#72dbc9",
+  positive: "#8bd8a8",
+  negative: "#ed8f98",
+  ink: "#dceaf0"
+};
+
+export const processGeometryPack = {
+  namespace: "process",
+  name: "Process Symbols",
+  version: "0.1.0",
+  category: "Processes",
+  palette: processPalette,
+  geometries: [
+    {
+      id: "terminator",
+      name: "Terminator",
+      description: "Start or end of a process.",
+      canonicalSize: [3, 1.35, 1.5],
+      parameters: {
+        kind: { type: "select", label: "Kind", options: ["start", "end"], default: "start" },
+        icon: { type: "icon", label: "Front icon", default: "" },
+        image: { type: "image", label: "Front image URL", default: "" }
+      },
+      anchors: { input: [-1, 0, 0], output: [1, 0, 0] },
+      create({ parameters }) {
+        const color = parameters.kind === "end" ? "negative" : "positive";
+        return {
+          parts: [
+            { shape: "box", size: [.72, .8, .82], color, radius: .16, edgeColor: "edge" },
+            { shape: "sphere", size: [.62, .8, .82], position: [-.35, 0, 0], color, edges: false },
+            { shape: "sphere", size: [.62, .8, .82], position: [.35, 0, 0], color, edges: false },
+            ...frontMarker(parameters, "ink", [0, 0, .45], [.34, .26, 1])
+          ]
+        };
+      }
+    },
+    {
+      id: "activity",
+      name: "Process",
+      description: "A normal process activity or task.",
+      canonicalSize: [2.8, 1.8, 1.8],
+      parameters: {
+        variant: { type: "select", label: "Variant", options: ["task", "subprocess", "call"], default: "task" },
+        radius: { type: "number", label: "Corner radius", min: 0, max: .2, step: .01, default: .05 },
+        icon: { type: "icon", label: "Front icon", default: "" },
+        image: { type: "image", label: "Front image URL", default: "" }
+      },
+      anchors: { input: [-1, 0, 0], output: [1, 0, 0], detail: [0, 0, 1] },
+      create({ parameters }) {
+        const parts = [
+          { shape: "box", size: [1, .76, .8], color: "process", edgeColor: "edge", radius: clamp(parameters.radius, 0, .2) }
+        ];
+        if (parameters.variant !== "task") {
+          parts.push(
+            frontLine([-.42, 0, .42], [.035, .66, .035], parameters.variant === "call" ? "accent" : "edge"),
+            frontLine([.42, 0, .42], [.035, .66, .035], parameters.variant === "call" ? "accent" : "edge")
+          );
+        }
+        if (parameters.variant === "call") parts.push(frontLine([0, .39, .42], [.72, .035, .035], "accent"));
+        return { parts: [...parts, ...frontMarker(parameters)] };
+      }
+    },
+    {
+      id: "decision",
+      name: "Decision",
+      description: "A branching decision or gateway.",
+      canonicalSize: [2.25, 1.8, 2.25],
+      parameters: {
+        outcome: { type: "select", label: "Expected outcome", options: ["neutral", "positive", "negative"], default: "neutral" },
+        icon: { type: "icon", label: "Front icon", default: "" }
+      },
+      anchors: { input: [-1, 0, 0], yes: [1, 0, 0], no: [0, -1, 0], detail: [0, 0, 1] },
+      create({ parameters }) {
+        const color = parameters.outcome === "positive" ? "positive" : parameters.outcome === "negative" ? "negative" : "decision";
+        return {
+          parts: [
+            { shape: "box", size: [.88, .22, .88], rotation: [0, 0, Math.PI / 4], color, edgeColor: "edge", radius: .04 },
+            ...frontMarker(parameters, "ink", [0, 0, .15], [.25, .2, 1])
+          ]
+        };
+      }
+    },
+    {
+      id: "data",
+      name: "Data",
+      description: "Data entering or leaving a process.",
+      canonicalSize: [2.7, 1.55, 1.7],
+      parameters: {
+        direction: { type: "select", label: "Direction", options: ["input", "output", "both"], default: "input" },
+        icon: { type: "icon", label: "Front icon", default: "" },
+        image: { type: "image", label: "Front image URL", default: "" }
+      },
+      anchors: { input: [-1, 0, 0], output: [1, 0, 0], detail: [0, 0, 1] },
+      create({ parameters }) {
+        const color = parameters.direction === "output" ? "data" : parameters.direction === "both" ? "accent" : "input";
+        return {
+          parts: [
+            { shape: "box", size: [1, .58, .78], rotation: [0, 0, -.16], color, edgeColor: "edge", radius: .03 },
+            ...frontMarker(parameters, "ink", [0, 0, .43], [.3, .23, 1])
+          ]
+        };
+      }
+    },
+    {
+      id: "manual-operation",
+      name: "Manual Operation",
+      description: "A manually performed operation.",
+      canonicalSize: [2.75, 1.6, 1.7],
+      parameters: {
+        icon: { type: "icon", label: "Front icon", default: "" }
+      },
+      anchors: { input: [-1, 0, 0], output: [1, 0, 0] },
+      create({ parameters }) {
+        return {
+          parts: [
+            { shape: "frustum-pyramid", size: [1, .64, .84], color: "input", edgeColor: "edge" },
+            ...frontMarker(parameters, "ink", [0, 0, .44], [.28, .22, 1])
+          ]
+        };
+      }
+    },
+    {
+      id: "document",
+      name: "Document",
+      description: "A document or generated record.",
+      canonicalSize: [2.65, 2, 1.65],
+      parameters: {
+        copies: { type: "number", label: "Copies", min: 1, max: 3, step: 1, default: 1 },
+        icon: { type: "icon", label: "Front icon", default: "" },
+        image: { type: "image", label: "Front image URL", default: "" }
+      },
+      anchors: { input: [-1, 0, 0], output: [1, 0, 0], archive: [0, -1, 0] },
+      create({ parameters }) {
+        const copies = Math.round(clamp(parameters.copies, 1, 3));
+        const parts = [];
+        for (let index = copies - 1; index >= 0; index--) {
+          parts.push({
+            shape: "box",
+            size: [1, .72, .78],
+            position: [index * .06, index * .04, index * -.05],
+            color: index === 0 ? "paper" : "body",
+            edgeColor: "edge",
+            radius: .04
+          });
+        }
+        parts.push(
+          frontLine([-.28, -.22, .43], [.42, .035, .035], "ink"),
+          frontLine([.22, -.22, .43], [.22, .035, .035], "ink"),
+          ...frontMarker(parameters, "ink", [0, .12, .44], [.25, .2, 1])
+        );
+        return { parts };
+      }
+    },
+    {
+      id: "predefined-process",
+      name: "Predefined Process",
+      description: "A reusable subprocess or named routine.",
+      canonicalSize: [2.9, 1.8, 1.8],
+      parameters: {
+        icon: { type: "icon", label: "Front icon", default: "" },
+        image: { type: "image", label: "Front image URL", default: "" }
+      },
+      anchors: { input: [-1, 0, 0], output: [1, 0, 0], call: [0, 0, 1] },
+      create({ parameters }) {
+        return {
+          parts: [
+            { shape: "box", size: [1, .76, .8], color: "process", edgeColor: "edge", radius: .07 },
+            frontLine([-.42, 0, .43], [.035, .68, .035], "accent"),
+            frontLine([.42, 0, .43], [.035, .68, .035], "accent"),
+            ...frontMarker(parameters)
+          ]
+        };
+      }
+    },
+    {
+      id: "stored-data",
+      name: "Stored Data",
+      description: "Persisted data or a data store.",
+      canonicalSize: [2.45, 1.9, 2.1],
+      parameters: {
+        tiers: { type: "number", label: "Tiers", min: 1, max: 4, step: 1, default: 2 },
+        icon: { type: "icon", label: "Front icon", default: "" }
+      },
+      anchors: { input: [-1, 0, 0], output: [1, 0, 0], query: [0, 0, 1] },
+      create({ parameters }) {
+        const tiers = Math.round(clamp(parameters.tiers, 1, 4));
+        const parts = [];
+        for (let index = 0; index < tiers; index++) {
+          parts.push({
+            shape: "cylinder",
+            size: [.82, .28, .82],
+            position: [0, -.32 + index * (.64 / Math.max(1, tiers - 1)), 0],
+            color: index % 2 ? "storage" : "body",
+            edgeColor: "accent"
+          });
+        }
+        return { parts: [...parts, ...frontMarker(parameters, "accent", [0, 0, .46], [.27, .22, 1])] };
+      }
+    },
+    {
+      id: "internal-storage",
+      name: "Internal Storage",
+      description: "A store managed inside the process boundary.",
+      canonicalSize: [2.55, 2, 1.8],
+      parameters: {
+        partitions: { type: "number", label: "Partitions", min: 1, max: 4, step: 1, default: 2 },
+        icon: { type: "icon", label: "Front icon", default: "" }
+      },
+      anchors: { input: [-1, 0, 0], output: [1, 0, 0], access: [0, 0, 1] },
+      create({ parameters }) {
+        const partitions = Math.round(clamp(parameters.partitions, 1, 4));
+        const parts = [
+          { shape: "box", size: [1, .78, .8], color: "storage", edgeColor: "edge", radius: .03 },
+          frontLine([0, 0, .43], [.035, .7, .035], "accent")
+        ];
+        for (let index = 1; index < partitions; index++) {
+          const x = -.36 + index * (.72 / partitions);
+          parts.push(frontLine([x, 0, .44], [.022, .66, .035], "accent"));
+        }
+        return { parts: [...parts, ...frontMarker(parameters)] };
+      }
+    },
+    {
+      id: "direct-data",
+      name: "Direct Data",
+      description: "Direct-access data, typically represented by a drum or disk.",
+      canonicalSize: [2.6, 1.9, 2.15],
+      parameters: {
+        medium: { type: "select", label: "Medium", options: ["disk", "drum"], default: "disk" },
+        icon: { type: "icon", label: "Front icon", default: "" }
+      },
+      anchors: { input: [-1, 0, 0], output: [1, 0, 0], read: [0, 0, 1] },
+      create({ parameters }) {
+        const color = parameters.medium === "drum" ? "storage" : "data";
+        return {
+          parts: [
+            { shape: "cylinder", size: [.86, 1.02, .86], rotation: [0, 0, Math.PI / 2], color, edgeColor: "edge" },
+            { shape: "cylinder", size: [.48, 1.04, .48], rotation: [0, 0, Math.PI / 2], color: "accent", edges: false },
+            ...frontMarker(parameters, "ink", [0, 0, .5], [.27, .2, 1])
+          ]
+        };
+      }
+    },
+    {
+      id: "manual-input",
+      name: "Manual Input",
+      description: "Data entered manually by an operator.",
+      canonicalSize: [2.75, 1.65, 1.75],
+      parameters: {
+        icon: { type: "icon", label: "Front icon", default: "" },
+        image: { type: "image", label: "Front image URL", default: "" }
+      },
+      anchors: { input: [-1, .15, 0], output: [1, 0, 0], operator: [0, 1, 0] },
+      create({ parameters }) {
+        return {
+          parts: [
+            { shape: "box", size: [1, .62, .8], rotation: [0, 0, .16], color: "input", edgeColor: "edge", radius: .03 },
+            ...frontMarker(parameters, "ink", [0, 0, .43], [.3, .22, 1])
+          ]
+        };
+      }
+    },
+    {
+      id: "preparation",
+      name: "Preparation",
+      description: "Preparation, setup or initialization step.",
+      canonicalSize: [2.7, 1.8, 1.8],
+      parameters: {
+        icon: { type: "icon", label: "Front icon", default: "" }
+      },
+      anchors: { input: [-1, 0, 0], output: [1, 0, 0], setup: [0, 1, 0] },
+      create({ parameters }) {
+        return {
+          parts: [
+            { shape: "prism", size: [1, .74, .82], color: "process", edgeColor: "edge" },
+            ...frontMarker(parameters)
+          ]
+        };
+      }
+    },
+    {
+      id: "parallel-mode",
+      name: "Parallel Mode",
+      description: "A process that can execute in parallel.",
+      canonicalSize: [2.8, 1.9, 1.8],
+      parameters: {
+        lanes: { type: "number", label: "Lanes", min: 2, max: 4, step: 1, default: 2 },
+        icon: { type: "icon", label: "Front icon", default: "" }
+      },
+      anchors: { input: [-1, 0, 0], output: [1, 0, 0], lane: [0, 0, 1] },
+      create({ parameters }) {
+        const lanes = Math.round(clamp(parameters.lanes, 2, 4));
+        const parts = [
+          { shape: "box", size: [1, .76, .8], color: "process", edgeColor: "edge", radius: .04 }
+        ];
+        for (let index = 0; index < lanes; index++) {
+          const y = -.27 + index * (.54 / Math.max(1, lanes - 1));
+          parts.push(frontLine([0, y, .43], [.66, .025, .035], index % 2 ? "accent" : "edge"));
+        }
+        return { parts: [...parts, ...frontMarker(parameters)] };
+      }
+    },
+    {
+      id: "loop-limit",
+      name: "Loop Limit",
+      description: "A bounded loop or iteration limit.",
+      canonicalSize: [2.7, 1.9, 1.8],
+      parameters: {
+        limit: { type: "number", label: "Limit", min: 1, max: 99, step: 1, default: 3 },
+        icon: { type: "icon", label: "Front icon", default: "" }
+      },
+      anchors: { input: [-1, 0, 0], output: [1, 0, 0], loop: [0, 0, 1] },
+      create({ parameters }) {
+        const limit = Math.round(clamp(parameters.limit, 1, 99));
+        return {
+          parts: [
+            { shape: "pyramid-square", size: [1, .72, .82], color: "decision", edgeColor: "edge" },
+            frontLine([0, -.17, .45], [.34, .035, .035], "ink"),
+            ...frontMarker({ ...parameters, icon: parameters.icon || String(limit) }, "ink", [0, .12, .45], [.28, .2, 1])
+          ]
+        };
+      }
+    },
+    {
+      id: "display",
+      name: "Display",
+      description: "A user-facing display or presentation step.",
+      canonicalSize: [2.9, 1.8, 1.8],
+      parameters: {
+        screen: { type: "select", label: "Screen state", options: ["idle", "active", "warning"], default: "active" },
+        image: { type: "image", label: "Screen image URL", default: "" },
+        icon: { type: "icon", label: "Screen icon", default: "" }
+      },
+      anchors: { input: [-1, 0, 0], output: [1, 0, 0], user: [0, 0, 1] },
+      create({ parameters }) {
+        const color = parameters.screen === "warning" ? "negative" : parameters.screen === "active" ? "accent" : "body";
+        return {
+          parts: [
+            { shape: "box", size: [.9, .68, .76], color: "body", edgeColor: "edge", radius: .12 },
+            { shape: "box", size: [.72, .5, .05], position: [0, .02, .41], color: "screen", edgeColor: color, radius: .03 },
+            ...frontMarker(parameters, color, [0, .02, .45], [.25, .18, 1])
+          ]
+        };
+      }
+    },
+    {
+      id: "connector",
+      name: "Connector",
+      description: "An in-page connector or continuation point.",
+      canonicalSize: [1.55, 1.55, 1.55],
+      parameters: {
+        kind: { type: "select", label: "Kind", options: ["sequence", "junction"], default: "sequence" },
+        icon: { type: "icon", label: "Connector icon", default: "" }
+      },
+      anchors: { input: [-1, 0, 0], output: [1, 0, 0], continuation: [0, 0, 1] },
+      create({ parameters }) {
+        const color = parameters.kind === "junction" ? "decision" : "accent";
+        return {
+          parts: [
+            { shape: "cylinder", size: [.72, .22, .72], rotation: [0, 0, Math.PI / 2], color, edgeColor: "edge" },
+            { shape: "sphere", size: [.32, .32, .32], position: [0, 0, .39], color: "ink", edges: false },
+            ...frontMarker(parameters, "ink", [0, 0, .51], [.2, .16, 1])
+          ]
+        };
+      }
+    },
+    {
+      id: "off-page-reference",
+      name: "Off-page Reference",
+      description: "A continuation to another page or diagram.",
+      canonicalSize: [2.2, 2.1, 1.7],
+      parameters: {
+        target: { type: "string", label: "Target", default: "" },
+        icon: { type: "icon", label: "Reference icon", default: "" }
+      },
+      anchors: { input: [-1, 0, 0], output: [1, 0, 0], continuation: [0, -1, 0] },
+      create({ parameters }) {
+        return {
+          parts: [
+            { shape: "pyramid-square", size: [1, .72, .82], rotation: [0, 0, Math.PI / 4], color: "paper", edgeColor: "edge" },
+            ...frontMarker({ ...parameters, icon: parameters.icon || parameters.target }, "ink", [0, 0, .2], [.25, .18, 1])
+          ]
+        };
+      }
+    },
+    {
+      id: "annotation",
+      name: "Annotation",
+      description: "A note linked to a process symbol.",
+      canonicalSize: [2.7, 1.9, 1.6],
+      parameters: {
+        icon: { type: "icon", label: "Annotation icon", default: "i" },
+        image: { type: "image", label: "Annotation image URL", default: "" }
+      },
+      anchors: { target: [-1, 0, 0], note: [1, 0, 0] },
+      create({ parameters }) {
+        return {
+          parts: [
+            { shape: "box", size: [.72, .58, .58], color: "paper", edgeColor: "edge", radius: .04 },
+            frontLine([.58, 0, 0], [.62, .035, .035], "accent"),
+            ...frontMarker(parameters, "ink", [0, 0, .32], [.22, .16, 1])
+          ]
+        };
+      }
+    },
+    {
+      id: "control-transfer",
+      name: "Control Transfer",
+      description: "A control or flow transfer marker.",
+      canonicalSize: [2.5, 1.55, 1.55],
+      parameters: {
+        direction: { type: "select", label: "Direction", options: ["forward", "back"], default: "forward" },
+        icon: { type: "icon", label: "Transfer icon", default: "" }
+      },
+      anchors: { input: [-1, 0, 0], output: [1, 0, 0] },
+      create({ parameters }) {
+        const rotation = parameters.direction === "back" ? -Math.PI / 2 : Math.PI / 2;
+        return {
+          parts: [
+            { shape: "box", size: [.62, .16, .16], position: [-.17, 0, 0], color: "accent", edges: false },
+            { shape: "cone", size: [.42, .42, .42], position: [.28, 0, 0], rotation: [0, 0, rotation], color: "accent", edgeColor: "edge" },
+            ...frontMarker(parameters, "ink", [0, 0, .24], [.2, .16, 1])
+          ]
+        };
+      }
+    },
+    {
+      id: "condition",
+      name: "Condition",
+      description: "A condition or rule gate.",
+      canonicalSize: [2.25, 1.8, 2.1],
+      parameters: {
+        state: { type: "select", label: "State", options: ["true", "false", "unknown"], default: "unknown" },
+        icon: { type: "icon", label: "Condition icon", default: "" }
+      },
+      anchors: { input: [-1, 0, 0], true: [1, .35, 0], false: [1, -.35, 0] },
+      create({ parameters }) {
+        const color = parameters.state === "true" ? "positive" : parameters.state === "false" ? "negative" : "decision";
+        return {
+          parts: [
+            { shape: "pyramid-triangle", size: [1, .68, .84], color, edgeColor: "edge" },
+            ...frontMarker(parameters, "ink", [0, 0, .45], [.22, .18, 1])
+          ]
+        };
+      }
+    }
+  ]
+};
+
+registerGeometryPack(processGeometryPack);
+
+export default processGeometryPack;

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@liquidcars/atlas-geometry-processes",
+  "version": "0.1.0",
+  "description": "Standard process and flowchart geometry pack for LiquidCars Atlas",
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "sideEffects": true,
+  "peerDependencies": {
+    "@liquidcars/atlas": ">=0.1.25"
+  },
+  "keywords": [
+    "liquidcars",
+    "atlas",
+    "3d",
+    "geometry-pack",
+    "process",
+    "flowchart",
+    "bpmn"
+  ],
+  "license": "MIT"
+}