@wandelbots/wandelbots-js-react-components 5.5.1-pr.fix-standardize-output.591.60112ee → 5.5.1

package/src/components/robots/GenericRobot.tsx

@@ -0,0 +1,137 @@
+import { useGLTF } from "@react-three/drei"
+import type { ThreeElements } from "@react-three/fiber"
+import type React from "react"
+import { useCallback, useEffect, useState } from "react"
+import type { Group, Mesh, Object3D } from "three"
+import { isFlange, parseRobotModel } from "./robotModelLogic"
+
+export type RobotModelProps = {
+  modelURL: string | Promise<string>
+  /**
+   * Called after a robot model has been loaded and
+   * rendered into the threejs scene
+   */
+  postModelRender?: () => void
+  flangeRef?: React.Ref<Group>
+} & ThreeElements["group"]
+
+function isMesh(node: Object3D): node is Mesh {
+  return node.type === "Mesh"
+}
+
+// Separate component that only renders when we have a valid URL
+function LoadedRobotModel({
+  url,
+  flangeRef,
+  postModelRender,
+  ...props
+}: {
+  url: string
+  flangeRef?: React.Ref<Group>
+  postModelRender?: () => void
+} & ThreeElements["group"]) {
+  const gltfResult = useGLTF(url)
+  const parsed = parseRobotModel(gltfResult, "robot.glb")
+  const gltf = parsed.gltf
+
+  const groupRef: React.RefCallback<Group> = useCallback(
+    (group) => {
+      if (group && postModelRender) {
+        postModelRender()
+      }
+    },
+    [postModelRender],
+  )
+
+  function renderNode(node: Object3D): React.ReactNode {
+    try {
+      if (isMesh(node)) {
+        // Defensive: only render mesh if geometry exists
+        if ((node as Mesh).geometry) {
+          return (
+            <mesh
+              name={node.name}
+              key={node.uuid}
+              geometry={(node as Mesh).geometry}
+              material={(node as Mesh).material}
+              position={node.position}
+              rotation={node.rotation}
+            />
+          )
+        }
+        // Fallback to empty group if geometry is missing
+        return (
+          <group
+            name={node.name}
+            key={node.uuid}
+            position={node.position}
+            rotation={node.rotation}
+          />
+        )
+      } else {
+        return (
+          <group
+            name={node.name}
+            key={node.uuid}
+            position={node.position}
+            rotation={node.rotation}
+            ref={isFlange(node) ? flangeRef : undefined}
+          >
+            {node.children.map(renderNode)}
+          </group>
+        )
+      }
+    } catch (e) {
+      console.warn("Error rendering node", node.name, e)
+      return null
+    }
+  }
+
+  return (
+    <group {...props} dispose={null} ref={groupRef}>
+      {renderNode(gltf.scene)}
+    </group>
+  )
+}
+
+export function GenericRobot({
+  modelURL,
+  flangeRef,
+  postModelRender,
+  ...props
+}: RobotModelProps) {
+  const [resolvedURL, setResolvedURL] = useState<string | null>(null)
+
+  useEffect(() => {
+    const resolveURL = async () => {
+      try {
+        if (typeof modelURL === "string") {
+          setResolvedURL(modelURL)
+        } else {
+          const url = await modelURL
+          setResolvedURL(url)
+        }
+      } catch (error) {
+        console.error("Failed to resolve model URL:", error)
+      }
+    }
+
+    resolveURL()
+  }, [modelURL])
+
+  // Don't render until we have a resolved URL
+  if (!resolvedURL) {
+    return null // Loading state
+  }
+
+  return (
+    <LoadedRobotModel
+      url={resolvedURL}
+      flangeRef={flangeRef}
+      postModelRender={postModelRender}
+      {...props}
+    />
+  )
+}
+
+export default GenericRobot

package/src/components/robots/LinearAxis.tsx

@@ -0,0 +1,74 @@
+import type { ThreeElements } from "@react-three/fiber"
+
+import type { Group } from "three"
+import type { ConnectedMotionGroup } from "../../lib/ConnectedMotionGroup"
+import { DHLinearAxis } from "./DHLinearAxis"
+import { defaultGetModel } from "./robotModelLogic"
+import { SupportedLinearAxis } from "./SupportedLinearAxis"
+
+export type LinearAxisProps = {
+  connectedMotionGroup: ConnectedMotionGroup
+  getModel?: (modelFromController: string) => Promise<string>
+  flangeRef?: React.Ref<Group>
+  transparentColor?: string
+  postModelRender?: () => void
+} & ThreeElements["group"]
+
+/**
+ * The LinearAxis component is a wrapper that renders SupportedLinearAxis if a model is available,
+ * otherwise falls back to DHLinearAxis for usage with @wandelbots/nova-js ConnectedMotionGroup object.
+ *
+ * @param {LinearAxisProps} props - The properties for the LinearAxis component.
+ * @param {ConnectedMotionGroup} props.connectedMotionGroup - The connected motion group containing motion state and parameters.
+ * @param {Function} [props.getModel=defaultGetModel] - Optional function to get the model URL. Defaults to defaultGetModel.
+ * @param {Object} props - Additional properties passed to the underlying component.
+ *
+ * @returns {JSX.Element} The rendered SupportedLinearAxis or DHLinearAxis component.
+ */
+export function LinearAxis({
+  connectedMotionGroup,
+  getModel = defaultGetModel,
+  flangeRef,
+  transparentColor,
+  postModelRender,
+  ...props
+}: LinearAxisProps) {
+  if (!connectedMotionGroup.dhParameters) {
+    return null
+  }
+
+  const modelFromController = connectedMotionGroup.modelFromController || ""
+  const hasModel = modelFromController && getModel(modelFromController)
+
+  // Use SupportedLinearAxis if model is available, otherwise fall back to DHLinearAxis
+  if (hasModel) {
+    return (
+      <SupportedLinearAxis
+        rapidlyChangingMotionState={
+          connectedMotionGroup.rapidlyChangingMotionState
+        }
+        modelFromController={modelFromController}
+        dhParameters={connectedMotionGroup.dhParameters}
+        getModel={getModel}
+        flangeRef={flangeRef}
+        transparentColor={transparentColor}
+        postModelRender={postModelRender}
+        {...props}
+      />
+    )
+  }
+
+  return (
+    <DHLinearAxis
+      rapidlyChangingMotionState={
+        connectedMotionGroup.rapidlyChangingMotionState
+      }
+      dhParameters={connectedMotionGroup.dhParameters}
+      {...props}
+    />
+  )
+}
+
+export { defaultGetModel }
+
+export default LinearAxis

package/src/components/robots/LinearAxisAnimator.tsx

@@ -0,0 +1,118 @@
+import { useFrame, useThree } from "@react-three/fiber"
+import type { DHParameter, MotionGroupState } from "@wandelbots/nova-js/v2"
+import type React from "react"
+import { useCallback, useEffect, useRef } from "react"
+import type { Group, Object3D } from "three"
+import { useAutorun } from "../utils/hooks"
+import { ValueInterpolator } from "../utils/interpolation"
+import { collectJoints } from "./robotModelLogic"
+
+type LinearAxisAnimatorProps = {
+  rapidlyChangingMotionState: MotionGroupState
+  dhParameters: DHParameter[]
+  onTranslationChanged?: (joints: Object3D[], jointValues: number[]) => void
+  children: React.ReactNode
+}
+
+export default function LinearAxisAnimator({
+  rapidlyChangingMotionState,
+  dhParameters,
+  onTranslationChanged,
+  children,
+}: LinearAxisAnimatorProps) {
+  const jointValues = useRef<number[]>([])
+  const jointObjects = useRef<Object3D[]>([])
+  const interpolatorRef = useRef<ValueInterpolator | null>(null)
+  const { invalidate } = useThree()
+
+  // Initialize interpolator
+  // biome-ignore lint/correctness/useExhaustiveDependencies: pre-biome code
+  useEffect(() => {
+    const initialJointValues = rapidlyChangingMotionState.joint_position.filter(
+      (item) => item !== undefined,
+    )
+
+    interpolatorRef.current = new ValueInterpolator(initialJointValues, {
+      tension: 120, // Controls spring stiffness - higher values create faster, more responsive motion
+      friction: 20, // Controls damping - higher values reduce oscillation and create smoother settling
+      threshold: 0.001,
+    })
+
+    return () => {
+      interpolatorRef.current?.destroy()
+    }
+  }, [])
+
+  // Animation loop that runs at the display's refresh rate
+  useFrame((state, delta) => {
+    if (interpolatorRef.current) {
+      const isComplete = interpolatorRef.current.update(delta)
+      setTranslation()
+
+      // Trigger a re-render only if the animation is still running
+      if (!isComplete) {
+        invalidate()
+      }
+    }
+  })
+
+  function setGroupRef(group: Group | null) {
+    if (!group) return
+
+    jointObjects.current = collectJoints(group)
+
+    // Set initial position
+    setTranslation()
+    invalidate()
+  }
+
+  function setTranslation() {
+    const updatedJointValues = interpolatorRef.current?.getCurrentValues() || []
+
+    if (onTranslationChanged) {
+      onTranslationChanged(jointObjects.current, updatedJointValues)
+    } else {
+      // For linear axes, we apply translation instead of rotation
+      for (const [index, object] of jointObjects.current.entries()) {
+        const dhParam = dhParameters[index]
+        const translationSign = dhParam.reverse_rotation_direction ? -1 : 1
+
+        // Apply linear translation along Y axis
+        // Convert from millimeters to meters
+        object.position.y =
+          (translationSign * (updatedJointValues[index] || 0)) / 1000
+      }
+    }
+  }
+
+  const updateJoints = useCallback(() => {
+    const newJointValues = rapidlyChangingMotionState.joint_position.filter(
+      (item) => item !== undefined,
+    )
+
+    requestAnimationFrame(() => {
+      jointValues.current = newJointValues
+      interpolatorRef.current?.setTarget(newJointValues)
+    })
+  }, [rapidlyChangingMotionState])
+
+  /**
+   * Fire an update joints call on every motion state change.
+   * requestAnimationFrame used to avoid blocking main thread
+   */
+  // biome-ignore lint/correctness/useExhaustiveDependencies: pre-biome code
+  useEffect(() => {
+    updateJoints()
+  }, [rapidlyChangingMotionState, updateJoints])
+
+  /**
+   * As some consumer applications (eg. storybook) deliver
+   * mobx observable for rapidlyChangingMotionState, we need to
+   * register the watcher to get the newest value updates
+   */
+  useAutorun(() => {
+    updateJoints()
+  })
+
+  return <group ref={setGroupRef}>{children}</group>
+}

package/src/components/robots/MotionGroupVisualizer.tsx

@@ -0,0 +1,73 @@
+import { JointTypeEnum } from "@wandelbots/nova-js/v2"
+import type React from "react"
+import { useEffect, useMemo, useState } from "react"
+
+import { externalizeComponent } from "../../externalizeComponent"
+import {
+  SupportedLinearAxis,
+  type SupportedLinearAxisProps,
+} from "./SupportedLinearAxis"
+import { SupportedRobot, type SupportedRobotProps } from "./SupportedRobot"
+
+export type MotionGroupVisualizerProps = {
+  instanceUrl: string
+  inverseSolver?: string | null
+} & (SupportedRobotProps | SupportedLinearAxisProps)
+
+export const MotionGroupVisualizer: React.FC<MotionGroupVisualizerProps> =
+  externalizeComponent((props: MotionGroupVisualizerProps) => {
+    const { inverseSolver, dhParameters, ...rest } = props
+
+    /**
+     * Joint type to find out - in combination with inverseSolver - whether the
+     * active robot is a turn table
+     */
+    const [jointType, setJointType] = useState<JointTypeEnum>(
+      JointTypeEnum.RevoluteJoint,
+    )
+
+    /**
+     * Sets the joint type according to delivered dh parameter type
+     */
+    useEffect(() => {
+      if (dhParameters.length) {
+        setJointType(dhParameters[0].type ?? JointTypeEnum.RevoluteJoint)
+      }
+    }, [dhParameters])
+
+    /**
+     * The turntable models return inverseSolver = null - however these models
+     * should be rendered with SupportedRobot instead of SupportedLinearAxis
+     */
+    const isTurnTable = useMemo(() => {
+      return inverseSolver === null && jointType === JointTypeEnum.RevoluteJoint
+    }, [inverseSolver, jointType])
+
+    /**
+     * Linear axis check
+     */
+    const isLinearAxis = useMemo(() => {
+      return (
+        inverseSolver === null && jointType === JointTypeEnum.PrismaticJoint
+      )
+    }, [inverseSolver, jointType])
+
+    /**
+     * Robot differentiation for readability reasons
+     */
+    const isRobot = useMemo(() => {
+      return !!inverseSolver
+    }, [inverseSolver])
+
+    if (isRobot || isTurnTable) {
+      return <SupportedRobot dhParameters={dhParameters} {...rest} />
+    }
+
+    if (isLinearAxis) {
+      return <SupportedLinearAxis dhParameters={dhParameters} {...rest} />
+    }
+
+    return null
+  })
+
+export default MotionGroupVisualizer

package/src/components/robots/Robot.tsx

@@ -0,0 +1,57 @@
+import type { ThreeElements } from "@react-three/fiber"
+
+import type { Group } from "three"
+import type { ConnectedMotionGroup } from "../../lib/ConnectedMotionGroup"
+import { defaultGetModel } from "./robotModelLogic"
+import { SupportedRobot } from "./SupportedRobot"
+
+export type RobotProps = {
+  connectedMotionGroup: ConnectedMotionGroup
+  getModel?: (modelFromController: string) => Promise<string>
+  flangeRef?: React.Ref<Group>
+  transparentColor?: string
+  postModelRender?: () => void
+} & ThreeElements["group"]
+
+/**
+ * The Robot component is a wrapper around the SupportedRobot component
+ * for usage with @wandelbots/nova-js ConnectedMotionGroup object.
+ *
+ * @param {RobotProps} props - The properties for the Robot component.
+ * @param {ConnectedMotionGroup} props.connectedMotionGroup - The connected motion group containing motion state and parameters.
+ * @param {Function} [props.getModel=defaultGetModel] - Optional function to get the model URL. Defaults to defaultGetModel.
+ * @param {Object} props - Additional properties passed to the SupportedRobot component.
+ *
+ * @returns {JSX.Element} The rendered SupportedRobot component.
+ */
+export function Robot({
+  connectedMotionGroup,
+  getModel = defaultGetModel,
+  flangeRef,
+  transparentColor,
+  postModelRender,
+  ...props
+}: RobotProps) {
+  if (!connectedMotionGroup.dhParameters) {
+    return null
+  }
+
+  return (
+    <SupportedRobot
+      rapidlyChangingMotionState={
+        connectedMotionGroup.rapidlyChangingMotionState
+      }
+      modelFromController={connectedMotionGroup.modelFromController || ""}
+      dhParameters={connectedMotionGroup.dhParameters}
+      getModel={getModel}
+      flangeRef={flangeRef}
+      transparentColor={transparentColor}
+      postModelRender={postModelRender}
+      {...props}
+    />
+  )
+}
+
+export { defaultGetModel }
+
+export default Robot

package/src/components/robots/RobotAnimator.test.tsx

@@ -0,0 +1,98 @@
+import type { DHParameter, MotionGroupState } from "@wandelbots/nova-js/v2"
+import { describe, expect, it, vi } from "vitest"
+import RobotAnimator from "./RobotAnimator"
+
+// Mock the dependencies
+vi.mock("./robotModelLogic", () => ({
+  collectJoints: vi.fn(),
+}))
+
+vi.mock("../utils/interpolation", () => ({
+  ValueInterpolator: vi.fn().mockImplementation(() => ({
+    setTarget: vi.fn(),
+    getCurrentValues: vi.fn(() => []),
+    destroy: vi.fn(),
+  })),
+}))
+
+describe("RobotAnimator", () => {
+  it("should export the component correctly", () => {
+    expect(RobotAnimator).toBeDefined()
+    expect(typeof RobotAnimator).toBe("function")
+  })
+
+  it("should handle props with different numbers of joints", () => {
+    // Test that the component accepts different numbers of DH parameters
+    const mockMotionState4Joints: MotionGroupState = {
+      joint_position: [0.1, 0.2, 0.3, 0.4],
+    } as unknown as MotionGroupState
+
+    const mockDHParameters4Joints: DHParameter[] = [
+      { theta: 0, reverse_rotation_direction: false },
+      { theta: 0, reverse_rotation_direction: false },
+      { theta: 0, reverse_rotation_direction: false },
+      { theta: 0, reverse_rotation_direction: false },
+    ]
+
+    const mockMotionState7Joints: MotionGroupState = {
+      joint_position: [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7],
+    } as unknown as MotionGroupState
+
+    const mockDHParameters7Joints: DHParameter[] = Array(7).fill({
+      theta: 0,
+      reverse_rotation_direction: false,
+    })
+
+    // These should not throw TypeScript errors
+    expect(() => {
+      const props4 = {
+        rapidlyChangingMotionState: mockMotionState4Joints,
+        dhParameters: mockDHParameters4Joints,
+        children: null,
+      }
+      // Verify props are correctly typed
+      expect(props4.dhParameters).toHaveLength(4)
+      expect(props4.rapidlyChangingMotionState.joint_position).toHaveLength(4)
+    }).not.toThrow()
+
+    expect(() => {
+      const props7 = {
+        rapidlyChangingMotionState: mockMotionState7Joints,
+        dhParameters: mockDHParameters7Joints,
+        children: null,
+      }
+      expect(props7.dhParameters).toHaveLength(7)
+      expect(props7.rapidlyChangingMotionState.joint_position).toHaveLength(7)
+    }).not.toThrow()
+  })
+
+  it("should use custom interpolation for smooth value transitions", () => {
+    // Test the rotation calculation logic
+    const dhParam1 = { theta: 0.1, reverse_rotation_direction: false }
+    const dhParam2 = { theta: -0.2, reverse_rotation_direction: true }
+    const jointValue1 = 0.5
+    const jointValue2 = 1.0
+
+    // Calculate expected rotations
+    const expectedRotation1 = 1 * jointValue1 + 0.1 // 0.6
+    const expectedRotation2 = -1 * jointValue2 + -0.2 // -1.2
+
+    expect(expectedRotation1).toBe(0.6)
+    expect(expectedRotation2).toBe(-1.2)
+
+    // Test edge cases
+    const dhParamReverse = { theta: 0, reverse_rotation_direction: true }
+    const jointValueZero = 0
+    const expectedRotationReverse = -1 * jointValueZero + 0 // 0
+
+    expect(expectedRotationReverse).toBe(0)
+
+    // Test rotation direction logic
+    const testValue = 1.5
+    const normalParam = { theta: 0, reverse_rotation_direction: false }
+    const reversedParam = { theta: 0, reverse_rotation_direction: true }
+
+    expect(1 * testValue + 0).toBe(1.5) // Normal direction
+    expect(-1 * testValue + 0).toBe(-1.5) // Reversed direction
+  })
+})

package/src/components/robots/RobotAnimator.tsx

@@ -0,0 +1,116 @@
+import { useFrame, useThree } from "@react-three/fiber"
+import type { DHParameter, MotionGroupState } from "@wandelbots/nova-js/v2"
+import type React from "react"
+import { useCallback, useEffect, useRef } from "react"
+import type { Group, Object3D } from "three"
+import { useAutorun } from "../utils/hooks"
+import { ValueInterpolator } from "../utils/interpolation"
+import { collectJoints } from "./robotModelLogic"
+
+type RobotAnimatorProps = {
+  rapidlyChangingMotionState: MotionGroupState
+  dhParameters: DHParameter[]
+  onRotationChanged?: (joints: Object3D[], jointValues: number[]) => void
+  children: React.ReactNode
+}
+
+export default function RobotAnimator({
+  rapidlyChangingMotionState,
+  dhParameters,
+  onRotationChanged,
+  children,
+}: RobotAnimatorProps) {
+  const jointValues = useRef<number[]>([])
+  const jointObjects = useRef<Object3D[]>([])
+  const interpolatorRef = useRef<ValueInterpolator | null>(null)
+  const { invalidate } = useThree()
+
+  // Initialize interpolator
+  // biome-ignore lint/correctness/useExhaustiveDependencies: pre-biome code
+  useEffect(() => {
+    const initialJointValues = rapidlyChangingMotionState.joint_position.filter(
+      (item) => item !== undefined,
+    )
+
+    interpolatorRef.current = new ValueInterpolator(initialJointValues, {
+      tension: 120, // Controls spring stiffness - higher values create faster, more responsive motion
+      friction: 20, // Controls damping - higher values reduce oscillation and create smoother settling
+      threshold: 0.001,
+    })
+
+    return () => {
+      interpolatorRef.current?.destroy()
+    }
+  }, [])
+
+  // Animation loop that runs at the display's refresh rate
+  useFrame((state, delta) => {
+    if (interpolatorRef.current) {
+      const isComplete = interpolatorRef.current.update(delta)
+      setRotation()
+
+      // Trigger a re-render only if the animation is still running
+      if (!isComplete) {
+        invalidate()
+      }
+    }
+  })
+
+  function setGroupRef(group: Group | null) {
+    if (!group) return
+
+    jointObjects.current = collectJoints(group)
+
+    // Set initial position
+    setRotation()
+    invalidate()
+  }
+
+  function setRotation() {
+    const updatedJointValues = interpolatorRef.current?.getCurrentValues() || []
+
+    if (onRotationChanged) {
+      onRotationChanged(jointObjects.current, updatedJointValues)
+    } else {
+      for (const [index, object] of jointObjects.current.entries()) {
+        const dhParam = dhParameters[index]
+        const rotationOffset = dhParam.theta || 0
+        const rotationSign = dhParam.reverse_rotation_direction ? -1 : 1
+
+        object.rotation.y =
+          rotationSign * (updatedJointValues[index] || 0) + rotationOffset
+      }
+    }
+  }
+
+  const updateJoints = useCallback(() => {
+    const newJointValues = rapidlyChangingMotionState.joint_position.filter(
+      (item) => item !== undefined,
+    )
+
+    requestAnimationFrame(() => {
+      jointValues.current = newJointValues
+      interpolatorRef.current?.setTarget(newJointValues)
+    })
+  }, [rapidlyChangingMotionState])
+
+  /**
+   * Fire an update joints call on every motion state change.
+   * requestAnimationFrame used to avoid blocking main thread
+   */
+  // biome-ignore lint/correctness/useExhaustiveDependencies: pre-biome code
+  useEffect(() => {
+    updateJoints()
+  }, [rapidlyChangingMotionState, updateJoints])
+
+  /**
+   * As some consumer applications (eg. storybook) deliver
+   * mobx observable for rapidlyChangingMotionState, we need to
+   * register the watcher to get the newest value updates
+   */
+  useAutorun(() => {
+    updateJoints()
+  })
+
+  return <group ref={setGroupRef}>{children}</group>
+}