@operato/scene-manufacturing 10.0.0-beta.2 → 10.0.0-beta.24

package/README.md

@@ -1,13 +1,33 @@
-## build
+# @operato/scene-manufacturing
 
-`$ yarn build`
+> Things scene components for manufacturing industry
 
-| type | filename                                   | for            | tested |
-| ---- | ------------------------------------------ | -------------- | ------ |
-| UMD  | things-scene-scene-manufacturing.js    | modern browser | O      |
-| UMD  | things-scene-scene-manufacturing-ie.js | ie 11          | O      |
-| ESM  | things-scene-scene-manufacturing.mjs   | modern browser | O      |
+<!-- AUTOGEN_BEGIN: do not edit between markers (run scripts/regenerate-readmes.mjs to update) -->
 
-## publish
+## Components
 
-`$ yarn publish`
+- `TactTimer`
+
+## Install
+
+```bash
+yarn add @operato/scene-manufacturing
+```
+
+## Usage
+
+```ts
+import { TactTimer } from '@operato/scene-manufacturing'
+```
+
+## Build
+
+```bash
+yarn build
+```
+
+Output: ESM module at `dist/index.js` (single bundle, no UMD/IE legacy).
+
+_Version: 10.0.0-beta.2_
+
+<!-- AUTOGEN_END -->

package/dist/index.d.ts

@@ -1 +1,7 @@
 export { default as TactTimer } from './tact-timer.js';
+export { default as RobotArm } from './robot-arm.js';
+export { RobotArm3D } from './robot-arm-3d.js';
+export type { ChainElement, JointAxis, SolveOptions } from './robot-arm-ik.js';
+export { forwardKinematics, solveCCDIK, maxReach } from './robot-arm-ik.js';
+export type { LinkShape, JointHousing, StyleName, GripperType, ChainPresetName, GripperConfig, RobotArmStyle } from './robot-arm-styles.js';
+export { STYLES, CHAIN_PRESETS, DEFAULT_GRIPPER } from './robot-arm-styles.js';

package/dist/index.js

@@ -1,2 +1,6 @@
 export { default as TactTimer } from './tact-timer.js';
+export { default as RobotArm } from './robot-arm.js';
+export { RobotArm3D } from './robot-arm-3d.js';
+export { forwardKinematics, solveCCDIK, maxReach } from './robot-arm-ik.js';
+export { STYLES, CHAIN_PRESETS, DEFAULT_GRIPPER } from './robot-arm-styles.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,iBAAiB,CAAA","sourcesContent":["export { default as TactTimer } from './tact-timer.js'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAE9C,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAU3E,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA","sourcesContent":["export { default as TactTimer } from './tact-timer.js'\nexport { default as RobotArm } from './robot-arm.js'\nexport { RobotArm3D } from './robot-arm-3d.js'\nexport type { ChainElement, JointAxis, SolveOptions } from './robot-arm-ik.js'\nexport { forwardKinematics, solveCCDIK, maxReach } from './robot-arm-ik.js'\nexport type {\n  LinkShape,\n  JointHousing,\n  StyleName,\n  GripperType,\n  ChainPresetName,\n  GripperConfig,\n  RobotArmStyle\n} from './robot-arm-styles.js'\nexport { STYLES, CHAIN_PRESETS, DEFAULT_GRIPPER } from './robot-arm-styles.js'\n"]}

package/dist/robot-arm-3d.d.ts

@@ -0,0 +1,169 @@
+import * as THREE from 'three';
+import { RealObjectGroup } from '@hatiolab/things-scene';
+export declare class RobotArm3D extends RealObjectGroup {
+    private _smoothing?;
+    private _animFrame?;
+    private _isAnimating;
+    private _chain;
+    private _jointFrames;
+    build(): void;
+    private _remountCarriers;
+    /**
+     * IK with a "point gripper downward" bias.
+     *
+     * CCDIK is position-only — it solves for joint values that put the
+     * end-effector at the target, without constraining the gripper's
+     * orientation. With no orientation constraint, valid solutions
+     * include twisted poses (gripper sideways / upside-down) — typical
+     * pick-and-place tasks then look broken: the box gets gripped at a
+     * wrong angle, or after release the carrier "launches" off because
+     * the gripper was facing some weird direction at the moment of
+     * release. The arm can also visibly "lock" near joint limits trying
+     * to satisfy a position-only target through a contorted path.
+     *
+     * Trick — augment the chain with a virtual rigid extension along the
+     * last frame's +Z, length L. When CCDIK puts this extended end at
+     * `target + L * (-Ẑ_chainLocal)` (i.e. the original target shifted
+     * downward by L in chain-local), the only way the chain can satisfy
+     * both placements simultaneously is by orienting the last frame's +Z
+     * to point in the chain-local -Z direction = world -Y direction =
+     * gripper pointing straight DOWN. Best-effort even when CCDIK can't
+     * fully converge — the solver pushes the chain in the right
+     * orientation, which matches what a real pick-and-place arm does.
+     */
+    private _gripperTcpZ;
+    private _solveIkDescent;
+    private _resolveChain;
+    /**
+     * Base pedestal height — small reservation at the bottom of `depth` so
+     * the chain doesn't start at z=0 (which would clip into the floor).
+     * About 12% of depth, clamped to a sane range.
+     */
+    private _baseHeight;
+    /**
+     * Color resolution priority (high → low):
+     *   1. `state.fillStyle`  → main link color (overrides style preset)
+     *   2. `state.color`      → legacy / explicit hex int
+     *   3. style preset color
+     * Same for accent: state.strokeStyle → state.accentColor → preset accent.
+     * This way the user can keep a SCARA's box-link shape but recolor it via
+     * the standard fillStyle property without dropping into custom presets.
+     */
+    private _resolveStyle;
+    /**
+     * Resolution priority for each joint i:
+     *   1. state.jointN (e.g. state.joint0, state.joint1, ...)  — written
+     *      by the property panel's per-joint number inputs (one row per
+     *      joint, range-clamped slider).
+     *   2. state.joints[i]  — array form, useful for programmatic batch set.
+     *   3. state.joints[i]  — object form ({0: v, 1: v, ...}).
+     *   4. 0  — fallback.
+     * Final value is range-clamped against the joint's own limits.
+     */
+    private _resolveJoints;
+    private _jointSpeed;
+    /** Convert revolute joint values from degrees → radians. Prismatic
+     *  values pass through untouched. */
+    private _toRadians;
+    /** Inverse of `_toRadians` — radians → degrees for revolute. */
+    private _fromRadians;
+    /**
+     * Build the chain as a tree of nested Object3Ds. Each link extends
+     * along its parent's +Z by `length` — applying the joint rotation BEFORE
+     * the translation. This way `rotateAround joint axis = rotate the
+     * downstream subtree`, which matches real arm kinematics.
+     */
+    private _buildArm;
+    /**
+     * Frame at the gripper TCP (Tool Center Point) — the working point of
+     * the gripper, NOT the wrist. For jaw grippers this is the mid-point
+     * between finger tips; for suction/magnetic it's the contact face.
+     * Carriers held by the arm parent here so they sit at the gripping
+     * interface, not buried inside the gripper meshes.
+     *
+     * Falls back to `_endFrame` (wrist) until `_buildGripper` has run.
+     */
+    getGripperFrame(): THREE.Object3D | undefined;
+    /**
+     * Convert a world-space point to the IK module's chain-local frame.
+     *
+     * Why this matters: CCDIK + forwardKinematics operate in `armRoot`'s
+     * local space (base joint at origin, +Z up — the IK math convention).
+     * `state.target` is interpreted in *that* frame. If a caller hands in
+     * a world position from another component (a parcel sitting somewhere
+     * in the scene), it must be projected through `armRoot`'s inverse
+     * world matrix first, otherwise the arm reaches toward "as if the
+     * world coords were base-relative" — a totally wrong direction once
+     * the robot itself isn't at the world origin.
+     *
+     * Returns the same `{x, y, z}` shape `state.target` accepts, which is
+     * already in chain-local space (no further conversion needed by
+     * pickAndPlace).
+     */
+    worldToChainLocal(worldX: number, worldY: number, worldZ: number): {
+        x: number;
+        y: number;
+        z: number;
+    };
+    private _armRoot?;
+    /**
+     * Apply a joint value to its scene-graph frame. `value` is in *user
+     * units* (degrees for revolute, scene units for prismatic) — convert
+     * to radians at the math boundary.
+     */
+    private _applyJointValue;
+    /** Cheap path: just refresh joint orientations without rebuilding the
+     *  geometry tree. Used when only joint values changed. */
+    private _refreshJointPoses;
+    private _buildJointHousing;
+    private _buildLinkMesh;
+    /**
+     * Build the gripper meshes onto `_endFrame` and place a TCP frame at
+     * the gripper's working point (between the finger tips for jaw types,
+     * at the cup/disk distal face for surface types). Carriers held by the
+     * arm mount onto this TCP frame, NOT onto `_endFrame` — `_endFrame` is
+     * the wrist (chain end-of-link) and the gripper extends from it in +Z,
+     * so a carrier at `_endFrame` origin would visually overlap the gripper
+     * meshes (the fingers/cup would pierce through the box).
+     */
+    private _buildGripper;
+    private _tcpFrame?;
+    /**
+     * Each gripper sub-builder returns its TCP z-offset (in `_endFrame`'s
+     * local coordinates) — the point in space where a held carrier's grip
+     * face should land. The caller positions `_tcpFrame` at that z so
+     * carriers attach there directly.
+     */
+    private _buildParallelGripper;
+    private _buildThreeFingerGripper;
+    private _buildSuctionGripper;
+    private _buildMagneticGripper;
+    private _buildReachSphere;
+    /**
+     * Pedestal — sized from `state.width × state.height` (the 2D footprint).
+     * Cylindrical base whose radius fills ~90% of the smaller footprint
+     * dimension; a flared bottom (1.2× radius) gives the visual weight of
+     * a real industrial robot anchor.
+     */
+    private _buildBase;
+    private _startAnimation;
+    private _stopAnimation;
+    /**
+     * Re-run IK toward a new target without rebuilding the scene graph.
+     *
+     * Mirrors the IK block of `build()` but operates on the *existing*
+     * joint frames and meshes. Critically does NOT call `update()` /
+     * `clear()` — those tear down `this.object3d`'s children, which would
+     * also detach the gripper frame and any Carriable currently mounted
+     * onto it. A pickAndPlace operation would lose its held carrier the
+     * instant the place target is committed.
+     *
+     * Falls back to a full `update()` only when the cached chain hasn't
+     * been built yet (build pre-condition).
+     */
+    private _retargetIk;
+    updateDimension(): void;
+    onchange(after: Record<string, unknown>, before: Record<string, unknown>): void;
+    dispose(): void;
+    updateAlpha(): void;
+}