feat(RB-3107): Add motion group visualizer (#510)

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

---------

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

Author: 3 people

.storybook/preview.tsx

@@ -24,7 +24,7 @@ const preview: Preview = {
           "Getting Started",
           "3D View",
           [
-            "Robot",
+            "Model Visualization",
             "TrajectoryRenderer",
             "SafetyZonesRenderer",
             "CollisionSceneRenderer",

package-lock.json

@@ -93,7 +93,7 @@
     "@types/react": "^19.1.8",
     "@types/three": "^0.182.0",
     "@vitejs/plugin-react": "^4.3.4",
-    "@wandelbots/nova-js": "^3.5.0",
+    "@wandelbots/nova-js": "^3.5.2",
     "add": "^2.0.6",
     "eslint-plugin-storybook": "^10.1.10",
     "glob": "^13.0.0",
@@ -176,7 +176,7 @@
   "dependencies": {
     "@mui/x-charts": "^8.27.0",
     "@mui/x-data-grid": "^8.27.0",
-    "@wandelbots/nova-js": "3.5.1",
+    "@wandelbots/nova-js": "^3.5.2",
     "axios": "^1.13.2",
     "dotenv": "^17.2.3",
     "i18next-browser-languagedetector": "^8.2.0",

package.json

@@ -14,4 +14,5 @@ export * from "./components/robots/Robot"
 export { defaultGetModel } from "./components/robots/robotModelLogic"
 export * from "./components/robots/SupportedLinearAxis"
 export * from "./components/robots/SupportedRobot"
+export * from "./components/robots/MotionGroupVisualizer"
 

src/3d.ts

@@ -0,0 +1,113 @@
+import React, { useCallback, useEffect, useMemo, useState } from "react"
+import { NovaClient } from "@wandelbots/nova-js/v2"
+import type { KinematicModel } from "@wandelbots/nova-api/v2"
+
+import { externalizeComponent } from "../../externalizeComponent"
+import { SupportedRobot, type SupportedRobotProps } from "./SupportedRobot"
+import { SupportedLinearAxis, type SupportedLinearAxisProps } from "./SupportedLinearAxis"
+
+export type MotionGroupVisualizerProps = {
+  instanceUrl: string
+  inverseSolver?: string | null
+} & (SupportedRobotProps | SupportedLinearAxisProps)
+
+export const MotionGroupVisualizer: React.FC<MotionGroupVisualizerProps> = externalizeComponent((props: MotionGroupVisualizerProps) => {
+  const {
+    instanceUrl,
+    inverseSolver: inverseSolverProp,
+    modelFromController,
+    ...rest
+  } = props
+
+  const [inverseSolver, setInverseSolver] = useState<string | null | undefined>(
+    inverseSolverProp,
+  )
+  const [, forceThreeRerender] = useState<boolean>(false)
+
+  /**
+   * Fetches the kinematic model from the API and saved the inverse_solver property, which defined
+   * whether the motion group should be displayed as a robot or linear axis
+   */
+  const fetchKinematicModel = useCallback(async () => {
+    const nova = new NovaClient({ instanceUrl })
+
+    try {
+      const kinematicModel: KinematicModel =
+        await nova.api.motionGroupModels.getMotionGroupKinematicModel(
+          modelFromController,
+        )
+
+      setInverseSolver(kinematicModel.inverse_solver)
+    } catch (err) {
+      console.warn(
+        `Failed to fetch kinematic model from API for ${modelFromController}, falling back to local config`,
+      )
+    } finally {
+      /**
+       * The following is a workaround to force a rerender of the Three.js scene, due
+       * to a race condition (if the component gets re-initialized, the robot
+       * is rendered with the initial joint position). The forceThreeRerender tells
+       * the Three.JS to re-render with the right joint position
+       *
+       * TODO remove the three rerender function and get rid of the
+       *  stale state condition
+       *  https://wandelbots.atlassian.net/browse/RB-3134
+       */
+      setTimeout(() => forceThreeRerender(true), 0)
+    }
+  }, [modelFromController, instanceUrl])
+
+  /**
+   * Checks the delivered inverseSolver property from the consumer
+   * Defined, Null - carry on with the delivered value - the inverseSolver was fetched via consumer app
+   * Undefined - carry out a request to fetch the inverseSolver value
+   */
+  useEffect(() => {
+    const shouldKinematicBeFetched =
+      inverseSolverProp === undefined && !!modelFromController && !!instanceUrl
+
+    if (shouldKinematicBeFetched) {
+      fetchKinematicModel()
+    }
+  }, [inverseSolverProp, modelFromController, fetchKinematicModel, instanceUrl])
+
+  /**
+   * The turntable models return inverseSolver = null - however these models
+   * should be rendered with SupportedRobot instead of SupportedLinearAxis
+   *
+   * TODO
+   * In the future - this hard coded check would be replaced with a new "type" property
+   * from dh parameters
+   */
+  const isTurnTable = useMemo(() => {
+    return [
+      "KUKA_DKP250",
+      "KUKA_DKP500_2",
+      "YASKAWA_TURN1",
+      "YASKAWA_TURN2",
+      "YASKAWA_TURN3",
+    ].includes(modelFromController)
+  }, [modelFromController])
+
+  if (inverseSolver || isTurnTable) {
+    return (
+      <SupportedRobot
+        instanceUrl={instanceUrl}
+        modelFromController={modelFromController}
+        {...rest}
+      />
+    )
+  }
+
+  if (inverseSolver === null) {
+    return (
+      <SupportedLinearAxis
+        instanceUrl={instanceUrl}
+        modelFromController={modelFromController}
+        {...rest}
+      />
+    )
+  }
+
+  return null
+})

src/components/robots/MotionGroupVisualizer.tsx

@@ -21,7 +21,8 @@ export type SupportedLinearAxisProps = {
   modelFromController: string
   dhParameters: DHParameter[]
   flangeRef?: React.Ref<THREE.Group>
-  getModel?: (modelFromController: string) => Promise<string> | undefined
+  instanceUrl?: string
+  getModel?: (modelFromController: string, instanceUrl?: string) => Promise<string> | undefined
   postModelRender?: () => void
   transparentColor?: string
 } & ThreeElements["group"]
@@ -35,6 +36,7 @@ export const SupportedLinearAxis = externalizeComponent(
     flangeRef,
     postModelRender,
     transparentColor,
+    instanceUrl,
     ...props
   }: SupportedLinearAxisProps) => {
     const [robotGroup, setRobotGroup] = useState<THREE.Group | null>(null)
@@ -77,7 +79,7 @@ export const SupportedLinearAxis = externalizeComponent(
             >
               <GenericRobot
                 modelURL={(() => {
-                  const result = getModel(modelFromController)
+                  const result = getModel(modelFromController, instanceUrl)
                   if (!result) {
                     const mockBlob = new Blob([], { type: 'model/gltf-binary' })
                     const mockFile = new File([mockBlob], `${modelFromController}.glb`, { type: 'model/gltf-binary' })

src/components/robots/SupportedLinearAxis.tsx

@@ -22,7 +22,8 @@ export type SupportedRobotProps = {
   modelFromController: string
   dhParameters: DHParameter[]
   flangeRef?: React.Ref<THREE.Group>
-  getModel?: (modelFromController: string) => Promise<string> | undefined
+  instanceUrl?: string
+  getModel?: (modelFromController: string, instanceUrl?: string) => Promise<string> | undefined
   postModelRender?: () => void
   transparentColor?: string
 } & ThreeElements["group"]
@@ -36,6 +37,7 @@ export const SupportedRobot = externalizeComponent(
     flangeRef,
     postModelRender,
     transparentColor,
+    instanceUrl,
     ...props
   }: SupportedRobotProps) => {
     const [robotGroup, setRobotGroup] = useState<THREE.Group | null>(null)
@@ -78,7 +80,7 @@ export const SupportedRobot = externalizeComponent(
             >
               <GenericRobot
                 modelURL={(() => {
-                  const result = getModel(modelFromController)
+                  const result = getModel(modelFromController, instanceUrl)
                   if (!result) {
                     const mockBlob = new Blob([], { type: 'model/gltf-binary' })
                     const mockFile = new File([mockBlob], `${modelFromController}.glb`, { type: 'model/gltf-binary' })

src/components/robots/SupportedRobot.tsx

@@ -40,15 +40,15 @@ export async function revokeAllModelUrls(): Promise<void> {
   modelCache.clear()
 }
 
-export async function defaultGetModel(modelFromController: string): Promise<string> {
+export async function defaultGetModel(modelFromController: string, instanceUrlProp?: string): Promise<string> {
   // Check cache first
   if (modelCache.has(modelFromController)) {
     return modelCache.get(modelFromController)!
   }
 
   // Create the promise and cache it immediately to prevent duplicate calls
   const modelPromise = (async () => {
-    const instanceUrl = import.meta.env.WANDELAPI_BASE_URL    
+    const instanceUrl = instanceUrlProp || import.meta.env.WANDELAPI_BASE_URL
     const nova = new NovaClient({ instanceUrl })
 
     // Configure axios to handle binary responses for GLB files

src/components/robots/robotModelLogic.ts

@@ -0,0 +1,56 @@
+import { Canvas, Meta, Source } from '@storybook/addon-docs/blocks';
+import * as MotionGroupVisualizerStories from '../stories/robots/MotionGroupVisualizer.stories';
+
+
+<Meta title="3D View/Model Visualization/MotionGroupVisualizer"/>
+
+# MotionGroupVisualizer
+
+This `MotionGroupVisualizer` component adds the robot or linear axis to the 3D viewport. It can be used on top of a robot or linear axis if we want to include the internal differentiation of what should be rendered.
+
+The differentiation is dependent on the `inverseSolver` variable, which can also be passed as a prop:
+- `inverseSolver` set: `SupportedRobot` component is returned.
+- `inverseSolver` null: `SupportedLinearAxis` component is returned.
+- `inverseSolver` undefined: internal kinematics request to find out what the `inverseSolver` state is.
+
+Use it together with the `ConnectedMotionGroup` from this library:
+
+```tsx
+import { NovaClient } from "@wandelbots/nova-js/v2"
+import { ConnectedMotionGroup } from "@wandelbots/wandelbots-js-react-components/core"
+import { MotionGroupVisualizer } from "@wandelbots/wandelbots-js-react-components/3d"
+
+const instanceUrl = "https://your-nova-instance.com"
+const nova = new NovaClient({ instanceUrl })
+const connectedMotionGroup = await ConnectedMotionGroup.connect(nova, "0@your-motion-group-id");
+
+<MotionGroupVisualizer
+  instanceUrl={instanceUrl}
+  modelFromController={connectedMotionGroup.modelFromController}
+  rapidlyChangingMotionState={connectedMotionGroup.rapidlyChangingMotionState}
+  dhParameters={connectedMotionGroup.dhParameters ?? []}
+/>
+```
+
+The model files are loaded from your connected Nova instance.
+
+```tsx
+const file = await nova.api.motionGroupModels.getMotionGroupGlbModel(modelFromController)
+const url = URL.createObjectURL(file)
+return url
+```
+
+
+In case you want to use the application offline, you can download the models and host them locally. You can override the URL resolver of the `MotionGroupVisualizer` component by passing a `getModel` function like:
+
+```tsx
+<MotionGroupVisualizer
+  instanceUrl={instanceUrl}
+  modelFromController={connectedMotionGroup.modelFromController}
+  rapidlyChangingMotionState={connectedMotionGroup.rapidlyChangingMotionState}
+  dhParameters={connectedMotionGroup.dhParameters ?? []}
+  getModel={() => `public/${connectedMotionGroup.modelFromController}.glb`}
+/>
+```
+
+<Canvas of={MotionGroupVisualizerStories.MotionGroupVisualizerStory} />

stories/MotionGroupVisualizer.mdx

@@ -2,7 +2,7 @@ import { Canvas, Meta, Source } from '@storybook/addon-docs/blocks';
 import * as RobotStories from '../stories/robots/Robot.stories';
 
 
-<Meta title="3D View/Robot/Robot"/>
+<Meta title="3D View/Model Visualization/Robot"/>
 
 # Robot