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

package/src/Setup.tsx

@@ -0,0 +1,33 @@
+import { OrbitControls } from "@react-three/drei"
+import { Canvas, type CanvasProps } from "@react-three/fiber"
+import type * as React from "react"
+import { Vector3 } from "three"
+import { PresetEnvironment } from "./components/3d-viewport/PresetEnvironment"
+
+type Props = React.PropsWithChildren<
+  CanvasProps & {
+    cameraFov?: number
+    cameraPosition?: Vector3
+    controls?: boolean
+    lights?: boolean
+  }
+>
+
+export const Setup = ({
+  children,
+  cameraFov = 25,
+  cameraPosition = new Vector3(-2, 1, 1),
+  controls = true,
+  lights = true,
+  ...restProps
+}: Props) => (
+  <Canvas
+    shadows
+    camera={{ position: cameraPosition, fov: cameraFov }}
+    {...restProps}
+  >
+    {children}
+    {lights && <PresetEnvironment />}
+    {controls && <OrbitControls makeDefault />}
+  </Canvas>
+)

package/src/components/3d-viewport/CoordinateSystemTransform.tsx

@@ -0,0 +1,57 @@
+import type { CoordinateSystem } from "@wandelbots/nova-js/v2"
+import type { ReactNode } from "react"
+import { Quaternion, Vector3 } from "three"
+
+/**
+ * Applies a API coordinate system transformation to
+ * all react-three child components.
+ */
+export const CoordinateSystemTransform = ({
+  coordinateSystem,
+  children,
+}: {
+  coordinateSystem?: CoordinateSystem
+  children: ReactNode
+}) => {
+  const position = new Vector3(
+    (coordinateSystem?.position?.[0] ?? 0) / 1000,
+    (coordinateSystem?.position?.[1] ?? 0) / 1000,
+    (coordinateSystem?.position?.[2] ?? 0) / 1000,
+  )
+
+  const orientationType = coordinateSystem?.orientation_type
+
+  let quaternion: Quaternion
+
+  if (orientationType === "QUATERNION") {
+    quaternion = new Quaternion(
+      coordinateSystem?.orientation?.[0] ?? 0,
+      coordinateSystem?.orientation?.[1] ?? 0,
+      coordinateSystem?.orientation?.[2] ?? 0,
+      coordinateSystem?.orientation?.[3] ?? 1,
+    )
+  } else {
+    if (orientationType && orientationType !== "ROTATION_VECTOR") {
+      console.warn(
+        `Unsupported orientation type ${orientationType}. Only ROTATION_VECTOR and QUATERNION are supported.`,
+      )
+    }
+    // Default to ROTATION_VECTOR
+    const rotationVector = new Vector3(
+      coordinateSystem?.orientation?.[0] ?? 0,
+      coordinateSystem?.orientation?.[1] ?? 0,
+      coordinateSystem?.orientation?.[2] ?? 0,
+    )
+    const magnitude = rotationVector.length()
+    const axis = rotationVector.normalize()
+    quaternion = new Quaternion().setFromAxisAngle(axis, magnitude)
+  }
+
+  return (
+    <group position={position} quaternion={quaternion}>
+      {children}
+    </group>
+  )
+}
+
+export default CoordinateSystemTransform

package/src/components/3d-viewport/PresetEnvironment.tsx

@@ -0,0 +1,81 @@
+import { Environment, Lightformer } from "@react-three/drei"
+
+/**
+ * Renders a preset environment for the 3D scene.
+ * This component wraps the scene with an `Environment` component
+ * and builds a lightmap build with `Lightformers`.
+ */
+export function PresetEnvironment() {
+  return (
+    <Environment>
+      <Lightformers />
+    </Environment>
+  )
+}
+
+function Lightformers({ positions = [2, 0, 2, 0, 2, 0, 2, 0] }) {
+  return (
+    <>
+      {/* Ceiling */}
+      <Lightformer
+        intensity={5}
+        rotation-x={Math.PI / 2}
+        position={[0, 5, -9]}
+        scale={[10, 10, 1]}
+      />
+      <group rotation={[0, 0.5, 0]}>
+        <group>
+          {positions.map((x, i) => (
+            <Lightformer
+              // biome-ignore lint/suspicious/noArrayIndexKey: pre-biome code
+              key={i}
+              form="circle"
+              intensity={5}
+              rotation={[Math.PI / 2, 0, 0]}
+              position={[x, 4, i * 4]}
+              scale={[3, 1, 1]}
+            />
+          ))}
+        </group>
+      </group>
+      {/* Sides */}
+      <Lightformer
+        intensity={40}
+        rotation-y={Math.PI / 2}
+        position={[-5, 1, -1]}
+        scale={[20, 0.1, 1]}
+      />
+      <Lightformer
+        intensity={20}
+        rotation-y={-Math.PI}
+        position={[-5, -2, -1]}
+        scale={[20, 0.1, 1]}
+      />
+
+      <Lightformer
+        rotation-y={Math.PI / 2}
+        position={[-5, -1, -1]}
+        scale={[20, 0.5, 1]}
+        intensity={5}
+      />
+      <Lightformer
+        rotation-y={-Math.PI / 2}
+        position={[10, 1, 0]}
+        scale={[20, 1, 1]}
+        intensity={10}
+      />
+
+      {/* Key */}
+      <Lightformer
+        form="ring"
+        color="white"
+        intensity={5}
+        scale={10}
+        position={[-15, 4, -18]}
+        target={[0, 0, 0]}
+      />
+    </>
+  )
+}
+
+export default PresetEnvironment

package/src/components/3d-viewport/SafetyZonesRenderer.tsx

@@ -0,0 +1,198 @@
+import type { ThreeElements } from "@react-three/fiber"
+import { useMemo } from "react"
+import * as THREE from "three"
+import { ConvexGeometry, RoundedBoxGeometry } from "three-stdlib"
+
+import type {
+  Capsule,
+  Collider,
+  ConvexHull,
+  DHParameter,
+  MotionGroupDescription,
+  RectangularCapsule,
+  Sphere,
+} from "@wandelbots/nova-js/v2"
+
+import {
+  dhParametersToPlaneSize,
+  orientationToQuaternion,
+  verticesToCoplanarity,
+} from "../utils/converters"
+
+export type SafetyZonesRendererProps = {
+  safetyZones: MotionGroupDescription["safety_zones"]
+  dhParameters?: DHParameter[]
+} & ThreeElements["group"]
+
+export function SafetyZonesRenderer({
+  safetyZones,
+  dhParameters,
+  ...props
+}: SafetyZonesRendererProps) {
+  /**
+   * Common material properties for safety zone meshes
+   */
+  const safetyZoneMaterialProps = {
+    attach: "material" as const,
+    color: "#009f4d",
+    opacity: 0.2,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+    polygonOffset: true,
+  }
+
+  /**
+   * Plane size for the plane safety zones, returns the reach distance
+   * of the robot
+   */
+  const planeSize = dhParametersToPlaneSize(dhParameters ?? [])
+
+  /**
+   * Helper function to render plane, sphere, and capsule meshes
+   * @param id number
+   * @param zone Collider
+   */
+  const renderMesh = (id: number, zone: Collider) => {
+    if (!zone?.pose?.position || !zone?.pose?.orientation) {
+      return null
+    }
+
+    const position = new THREE.Vector3(
+      zone.pose.position[0] / 1000,
+      zone.pose.position[1] / 1000,
+      zone.pose.position[2] / 1000,
+    )
+    const orientation = new THREE.Vector3(
+      zone.pose.orientation[0],
+      zone.pose.orientation[1],
+      zone.pose.orientation[2],
+    )
+
+    let geometry: React.ReactElement | null
+
+    const materialProps =
+      zone.shape.shape_type === "plane"
+        ? { ...safetyZoneMaterialProps, side: THREE.DoubleSide }
+        : { ...safetyZoneMaterialProps, side: THREE.FrontSide }
+
+    switch (zone.shape.shape_type) {
+      /**
+       * Plane shape, uses DH parameters to calculate the size of the plane (reach distance of a robot)
+       */
+      case "plane":
+        geometry = <planeGeometry args={[planeSize, planeSize]} />
+        break
+
+      /**
+       * Sphere shape
+       */
+      case "sphere": {
+        const radius = (zone?.shape as Sphere).radius / 1000
+        geometry = <sphereGeometry args={[radius]} />
+        break
+      }
+
+      /**
+       * Capsule shape
+       */
+      case "capsule": {
+        const capsuleRadius = (zone?.shape as Capsule).radius / 1000
+        const height = (zone?.shape as Capsule).cylinder_height / 1000
+        geometry = <capsuleGeometry args={[capsuleRadius, height]} />
+        break
+      }
+
+      /**
+       * Convex hull, checks at first if the vertices are coplanar - if yes, adds a small offset for
+       * renderer to be able to visualize the convex hull.
+       */
+      case "convex_hull": {
+        const vertices = (zone?.shape as ConvexHull).vertices.map(
+          (v) => new THREE.Vector3(v[0] / 1000, v[1] / 1000, v[2] / 1000),
+        )
+        // Check if the vertices are on the same plane
+        const coplanarityResult = verticesToCoplanarity(vertices)
+        if (coplanarityResult.isCoplanar && coplanarityResult.normal) {
+          const offset = 0.0001
+          const newVertex = new THREE.Vector3().addVectors(
+            vertices[0],
+            coplanarityResult.normal.multiplyScalar(offset),
+          )
+          vertices.push(newVertex)
+        }
+        try {
+          geometry = (
+            <primitive
+              object={new ConvexGeometry(vertices)}
+              attach="geometry"
+            />
+          )
+        } catch (error) {
+          console.log("Error creating ConvexGeometry:", error)
+          return null
+        }
+        break
+      }
+
+      /**
+       * Convex hull around four spheres. Sphere center points in x/y-plane,
+       * offset by either combination "+/- sizeX" or "+/- sizeY".
+       * Alternative description: Rectangle in x/y-plane with a 3D padding (source: nova-api docs)
+       *
+       * Basically a rounded box with a rectangular cross-section.
+       */
+      case "rectangular_capsule": {
+        const shape = zone.shape as RectangularCapsule
+        const rcRadius = shape.radius / 1000
+        const width = shape.sphere_center_distance_x / 1000
+        const height = shape.sphere_center_distance_y / 1000
+        const depth = rcRadius * 2
+
+        geometry = (
+          <primitive
+            object={new RoundedBoxGeometry(width, height, depth, 2, rcRadius)}
+            attach="geometry"
+          />
+        )
+        break
+      }
+
+      default: {
+        console.warn(
+          "Unsupported safety zone shape type:",
+          zone.shape.shape_type,
+        )
+        geometry = null
+      }
+    }
+
+    return (
+      <mesh
+        key={`safety-zone-${zone.shape.shape_type}-${id}`}
+        renderOrder={id}
+        position={position}
+        quaternion={orientationToQuaternion(orientation)}
+      >
+        {geometry}
+        <meshStandardMaterial {...materialProps} polygonOffsetFactor={-id} />
+      </mesh>
+    )
+  }
+
+  /**
+   * Helper variable render safety zones
+   */
+  // biome-ignore lint/correctness/useExhaustiveDependencies: pre-biome code
+  const renderedSafetyZones = useMemo(() => {
+    return Object.values(safetyZones ?? {}).map(
+      (zone: Collider, index: number) => {
+        return renderMesh(index, zone)
+      },
+    )
+  }, [safetyZones, planeSize])
+
+  return <group {...props}>{renderedSafetyZones}</group>
+}
+
+export default SafetyZonesRenderer

package/src/components/3d-viewport/TrajectoryRenderer.tsx

@@ -0,0 +1,41 @@
+import { Line } from "@react-three/drei"
+import type { Pose } from "@wandelbots/nova-js/v2"
+import * as THREE from "three"
+
+export type TrajectoryRendererProps = {
+  trajectory: Pose[]
+} & React.JSX.IntrinsicElements["group"]
+
+export function TrajectoryRenderer({
+  trajectory,
+  ...props
+}: TrajectoryRendererProps) {
+  const points =
+    trajectory
+      ?.map((pose: Pose) => {
+        if (pose.position && pose.position.length >= 3) {
+          const [x, y, z] = pose.position
+          if (Number.isFinite(x) && Number.isFinite(y) && Number.isFinite(z)) {
+            return new THREE.Vector3(x / 1000, z / 1000, -y / 1000)
+          }
+        }
+        return null
+      })
+      .filter((point): point is THREE.Vector3 => point !== null) || []
+
+  return (
+    <group {...props}>
+      {points.length > 0 && (
+        <Line
+          points={points}
+          lineWidth={3}
+          polygonOffset={true}
+          polygonOffsetFactor={10}
+          polygonOffsetUnits={10}
+        />
+      )}
+    </group>
+  )
+}
+
+export default TrajectoryRenderer

package/src/components/3d-viewport/collider/ColliderCollection.tsx

@@ -0,0 +1,35 @@
+import type { ThreeElements } from "@react-three/fiber"
+import type { Collider } from "@wandelbots/nova-js/v2"
+import ColliderElement from "./ColliderElement"
+
+export type MeshChildrenProvider = (
+  key: string,
+  collider: Collider,
+) => React.ReactNode
+
+type ColliderCollectionProps = {
+  name?: string
+  colliders: Record<string, Collider>
+  meshChildrenProvider: MeshChildrenProvider
+} & ThreeElements["group"]
+
+export default function ColliderCollection({
+  name,
+  colliders,
+  meshChildrenProvider,
+  ...props
+}: ColliderCollectionProps) {
+  return (
+    <group name={name} {...props}>
+      {Object.entries(colliders).map(([colliderKey, collider]) => (
+        <ColliderElement
+          key={colliderKey}
+          name={colliderKey}
+          collider={collider}
+        >
+          {meshChildrenProvider(colliderKey, collider)}
+        </ColliderElement>
+      ))}
+    </group>
+  )
+}

package/src/components/3d-viewport/collider/ColliderElement.tsx

@@ -0,0 +1,36 @@
+import type { Collider } from "@wandelbots/nova-js/v2"
+import type React from "react"
+import * as THREE from "three"
+import { colliderShapeToBufferGeometry } from "./colliderShapeToBufferGeometry"
+
+type ColliderElementProps = {
+  name?: string
+  collider: Collider
+  children?: React.ReactNode
+}
+
+export default function ColliderElement({
+  name,
+  collider,
+  children,
+}: ColliderElementProps) {
+  const position = collider.pose?.position ?? [0, 0, 0]
+  const rotation = collider.pose?.orientation ?? [0, 0, 0]
+  if (collider.margin) {
+    console.warn(`${name} margin is not supported`)
+  }
+  return (
+    <mesh
+      name={name}
+      position={new THREE.Vector3(
+        position[0],
+        position[1],
+        position[2],
+      ).divideScalar(1000)}
+      rotation={new THREE.Euler(rotation[0], rotation[1], rotation[2], "XYZ")}
+      geometry={colliderShapeToBufferGeometry(collider.shape)}
+    >
+      {children}
+    </mesh>
+  )
+}

package/src/components/3d-viewport/collider/CollisionSceneRenderer.tsx

@@ -0,0 +1,26 @@
+import type { CollisionSetup } from "@wandelbots/nova-js/v2"
+import ColliderCollection, {
+  type MeshChildrenProvider,
+} from "./ColliderCollection"
+
+type CollisionSceneRendererProps = {
+  scene: CollisionSetup
+  meshChildrenProvider: MeshChildrenProvider
+}
+
+export default function CollisionSceneRenderer({
+  scene,
+  meshChildrenProvider,
+}: CollisionSceneRendererProps) {
+  const colliders = scene.colliders
+  return (
+    <group>
+      {colliders && (
+        <ColliderCollection
+          meshChildrenProvider={meshChildrenProvider}
+          colliders={colliders}
+        />
+      )}
+    </group>
+  )
+}

package/src/components/3d-viewport/collider/colliderShapeToBufferGeometry.ts

@@ -0,0 +1,48 @@
+import type { ColliderShape } from "@wandelbots/nova-js/v2"
+import * as THREE from "three"
+import { ConvexGeometry } from "three-stdlib"
+
+export function colliderShapeToBufferGeometry(
+  shape: ColliderShape,
+): THREE.BufferGeometry {
+  const shapeType = shape.shape_type
+  switch (shapeType) {
+    case "convex_hull":
+      return new ConvexGeometry(
+        shape.vertices.map(
+          (vertex) =>
+            new THREE.Vector3(
+              vertex[0] / 1000,
+              vertex[1] / 1000,
+              vertex[2] / 1000,
+            ),
+        ),
+      )
+    case "box":
+      return new THREE.BoxGeometry(
+        shape.size_x / 1000,
+        shape.size_y / 1000,
+        shape.size_z / 1000,
+      )
+    case "sphere":
+      return new THREE.SphereGeometry(shape.radius / 1000)
+    case "capsule":
+      return new THREE.CapsuleGeometry(
+        shape.radius / 1000,
+        shape.cylinder_height / 1000,
+      )
+    case "cylinder":
+      return new THREE.CylinderGeometry(
+        shape.radius / 1000,
+        shape.radius / 1000,
+        shape.height / 1000,
+      )
+    case "rectangle": {
+      return new THREE.BoxGeometry(shape.size_x / 1000, shape.size_y / 1000, 0)
+    }
+    default: {
+      console.warn(`${shape.shape_type} is not supported`)
+      return new THREE.BufferGeometry()
+    }
+  }
+}

package/src/components/AppHeader.md

@@ -0,0 +1,84 @@
+# AppHeader Component
+
+A navigation header component that displays the current application's icon and name, with an optional dropdown menu for switching between different applications.
+
+## Features
+
+- **App Branding**: Displays the current app's icon and name with custom typography
+- **App Switching**: Dropdown menu with blur backdrop for navigating to other apps
+- **Responsive Design**: Uses MUI AppBar for consistent styling
+- **Accessibility**: Proper ARIA labels and keyboard navigation
+- **Flexible Navigation**: Supports both URL navigation and custom click handlers
+
+## Usage
+
+```tsx
+import {
+  AppHeader,
+  type AppItem,
+} from "@wandelbots/wandelbots-js-react-components/core"
+import { Home, Settings, Person } from "@mui/icons-material"
+
+const apps: AppItem[] = [
+  {
+    id: "dashboard",
+    name: "Dashboard",
+    icon: <Home />,
+    href: "/dashboard",
+  },
+  {
+    id: "settings",
+    name: "Settings",
+    icon: <Settings />,
+    onClick: () => navigateToSettings(),
+  },
+]
+
+function MyApp() {
+  return (
+    <AppHeader
+      appIcon={<Person />}
+      appName="Robot Control Studio"
+      apps={apps}
+      onAppSelect={(app) => console.log("Selected:", app.name)}
+    />
+  )
+}
+```
+
+## Props
+
+### AppHeaderProps
+
+- **appIcon** (`ReactNode`): Icon component for the current application
+- **appName** (`string`): Display name of the current application
+- **apps** (`AppItem[]`, optional): Array of available apps for the dropdown menu
+- **onAppSelect** (`(app: AppItem) => void`, optional): Callback when an app is selected
+- **sx** (`SxProps`, optional): Additional MUI styling
+
+### AppItem
+
+- **id** (`string`): Unique identifier for the app
+- **name** (`string`): Display name of the app
+- **icon** (`ReactNode`): Icon component to display
+- **href** (`string`, optional): URL to navigate to
+- **onClick** (`() => void`, optional): Custom click handler
+
+## Styling
+
+The component uses the specified typography:
+
+- Font weight: 700 (Bold)
+- Font size: 20px
+- Line height: 24px
+- Letter spacing: 0px
+
+The dropdown arrow uses a custom SVG icon with 56% opacity.
+
+## Behavior
+
+- When apps are provided, a dropdown arrow appears on the right side
+- Clicking the arrow opens a menu with available apps
+- The background blurs when the menu is open to focus attention
+- Apps can navigate via URL (`href`) or custom handler (`onClick`)
+- The menu closes automatically when an app is selected or when clicking outside