feat: Add linear axis support (#509)

[Storybook
Link](https://wandelbotsgmbh.github.io/wandelbots-js-react-components/overview.html)

---------

Co-authored-by: 3m5. Marcin Szalomski <marcin.szalomski@partner.wandelbots.com>

Author: BrunoBellmannWandelbots

src/3d.ts

@@ -5,11 +5,13 @@ export * from "./components/3d-viewport/SafetyZonesRenderer"
 export * from "./components/3d-viewport/TrajectoryRenderer"
 export * from "./components/RobotCard"
 export * from "./components/robots/AxisConfig"
+export * from "./components/robots/LinearAxis"
 export {
-  MANUFACTURER_HOME_CONFIGS,
   extractManufacturer,
-  getDefaultHomeConfig,
+  getDefaultHomeConfig, MANUFACTURER_HOME_CONFIGS
 } from "./components/robots/manufacturerHomePositions"
 export * from "./components/robots/Robot"
 export { defaultGetModel } from "./components/robots/robotModelLogic"
+export * from "./components/robots/SupportedLinearAxis"
 export * from "./components/robots/SupportedRobot"
+

src/components/robots/DHLinearAxis.tsx

@@ -0,0 +1,128 @@
+import { Line } from "@react-three/drei"
+import type { DHParameter } from "@wandelbots/nova-js/v2"
+import React, { useRef } from "react"
+import type * as THREE from "three"
+import { Matrix4, Quaternion, Vector3 } from "three"
+import LinearAxisAnimator from "./LinearAxisAnimator"
+import type { DHLinearAxisProps } from "./SupportedLinearAxis"
+
+export function DHLinearAxis({
+  rapidlyChangingMotionState,
+  dhParameters,
+  ...props
+}: DHLinearAxisProps) {
+  // reused in every update
+  const accumulatedMatrix = new Matrix4()
+
+  const tcpMeshRef = useRef<THREE.Mesh | null>(null)
+  const tcpLineRef = useRef<any>(null)
+
+  // Calculate initial TCP position
+  function calculateTcpPosition(jointValues: number[]): Vector3 {
+    const tempMatrix = new Matrix4()
+    
+    for (let i = 0; i < dhParameters.length; i++) {
+      const param = dhParameters[i]
+      const jointValue = jointValues[i] ?? 0
+      
+      const matrix = new Matrix4()
+        .makeRotationY(param.theta!) // Base rotation (if any)
+        .multiply(
+          new Matrix4().makeTranslation(
+            param.a! / 1000,
+            (param.d! + jointValue * (param.reverse_rotation_direction ? -1 : 1)) / 1000,
+            0
+          )
+        ) // Translate along X by a, and Y by d + joint_position
+        .multiply(new Matrix4().makeRotationX(param.alpha!)) // Rotate around X
+      
+      tempMatrix.multiply(matrix)
+    }
+    
+    const position = new Vector3()
+    const quaternion = new Quaternion()
+    const scale = new Vector3()
+    tempMatrix.decompose(position, quaternion, scale)
+    return position
+  }
+
+  // Calculate initial TCP position for rendering
+  const initialTcpPosition = calculateTcpPosition(rapidlyChangingMotionState.joint_position)
+
+  function setTranslation(joints: THREE.Object3D[], jointValues: number[]) {
+    accumulatedMatrix.identity()
+
+    let tcpPosition = new Vector3()
+
+    // Process all joints based on dhParameters length, not joints array
+    // Since we're using DHLinearAxis directly without a model, we don't have joint objects
+    for (let jointIndex = 0; jointIndex < dhParameters.length; jointIndex++) {
+      const jointValue = jointValues[jointIndex] ?? 0
+      const param = dhParameters[jointIndex]
+      
+      // Calculate and accumulate transformation
+      const matrix = new Matrix4()
+        .makeRotationY(param.theta!) // Base rotation (if any)
+        .multiply(
+          new Matrix4().makeTranslation(
+            param.a! / 1000,
+            (param.d! + jointValue * (param.reverse_rotation_direction ? -1 : 1)) / 1000,
+            0
+          )
+        )
+        .multiply(new Matrix4().makeRotationX(param.alpha!))
+      
+      accumulatedMatrix.multiply(matrix)
+    }
+
+    // Get final TCP position from accumulated matrix
+    const position = new Vector3()
+    const quaternion = new Quaternion()
+    const scale = new Vector3()
+    accumulatedMatrix.decompose(position, quaternion, scale)
+    tcpPosition = position
+
+    // Update TCP marker
+    if (tcpMeshRef.current) {
+      tcpMeshRef.current.position.set(tcpPosition.x, tcpPosition.y, tcpPosition.z)
+    }
+
+    // Update TCP line
+    if (tcpLineRef.current) {
+      const lineGeometry = tcpLineRef.current.geometry
+      if (lineGeometry && lineGeometry.setPositions) {
+        lineGeometry.setPositions([0, 0, 0, tcpPosition.x, tcpPosition.y, tcpPosition.z])
+      }
+    }
+  }
+
+  return (
+    <>
+      <LinearAxisAnimator
+        rapidlyChangingMotionState={rapidlyChangingMotionState}
+        dhParameters={dhParameters}
+        onTranslationChanged={setTranslation}
+      >
+        <group {...props} name="Scene">
+          {/* Base (origin) - Green sphere representing initial previous position */}
+          <mesh name="Base" position={[0, 0, 0]}>
+            <sphereGeometry args={[0.02, 32, 32]} />
+            <meshStandardMaterial color={"green"} depthTest={true} />
+          </mesh>
+          {/* Line from Base to TCP */}
+          <Line
+            ref={tcpLineRef}
+            points={[new Vector3(0, 0, 0), initialTcpPosition]}
+            color={"White"}
+            lineWidth={5}
+          />
+          {/* TCP (Tool Center Point) - Red sphere that shows final position */}
+          <mesh ref={tcpMeshRef} name="TCP" position={initialTcpPosition}>
+            <sphereGeometry args={[0.025, 32, 32]} />
+            <meshStandardMaterial color={"red"} depthTest={true} />
+          </mesh>
+        </group>
+      </LinearAxisAnimator>
+    </>
+  )
+}

src/components/robots/LinearAxis.tsx

@@ -0,0 +1,73 @@
+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 }
+

src/components/robots/LinearAxisAnimator.tsx

@@ -0,0 +1,116 @@
+import { useFrame, useThree } from "@react-three/fiber"
+import type { DHParameter, MotionGroupState } from "@wandelbots/nova-js/v2"
+import React, { 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
+  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 X axis
+        // Convert from millimeters to meters
+        // ToDo: change back to y axis when we want to display the proper orientation
+        object.position.x =
+          (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
+   */
+  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>
+}