FEATURE - Rig joints viewer mode

[DrHepa]

Feature request — Rig joints viewer mode

Summary

Add a Rig joints viewer mode for rigged GLB models.

The goal is to provide a lightweight rig inspection view in the Generate viewer, showing the skeleton structure without introducing the full Rig Editor or PoseClip authoring tools yet.

This would be a frontend-only viewer feature.

---

Motivation

When working with rigged models, it is useful to quickly inspect whether the generated/imported GLB has a valid skeleton and whether the joints/bones are positioned correctly.

This is especially helpful for extensions or workflows that output rigged characters, such as UniRig/Kimodo-style outputs.

Right now, the viewer has visual modes like:

• Solid
• Wireframe
• Normals
• Matcap
• UV checker

A Rig joints mode would add a rig-specific inspection view for models that contain a skeleton.

---

Proposed behavior

When the loaded model contains a rig/skeleton:

• enable a new Rig joints view mode in the viewer toolbar;
• render the mesh as a translucent shell;
• render bone connection lines;
• render joint markers on detected bones;
• keep the overlay aligned while orbiting, auto-rotating, or viewing animated/posed models.

When the loaded model does not contain a rig:

• keep the Rig joints button disabled;
• show a tooltip/label such as Rig joints (rig only).

---

Current local prototype

I have a local/private prototype working with this visual direction:

• translucent mesh shell;
• cyan/sky-blue bone lines;
• violet/white octahedron joint markers;
• selected joint/segment can be emphasized in brighter cyan.

Current visual design values:

// Mesh shell
color: '#f8fafc'
opacity: 0.28
roughness: 0.82
metalness: 0.02
transparent: true
depthWrite: false
side: THREE.DoubleSide

// Default joint marker
geometry: new THREE.OctahedronGeometry(0.026, 0)

color: '#f5f3ff'
emissive: '#7c3aed'
emissiveIntensity: 0.55
roughness: 0.35
metalness: 0.08
depthTest: false
depthWrite: false

// Bone line
color: '#38bdf8'
opacity: 0.98
depthTest: false
depthWrite: false

---

Implementation notes

The local prototype detects rigged models by traversing the loaded GLB scene and checking for SkinnedMesh objects with a skeleton:

scene.traverse((child) => {
  if (!(child instanceof THREE.SkinnedMesh) || !child.skeleton) return
  // collect skeleton / bones
})

The viewer derives basic rig stats:

type RigStats = {
  hasRig: boolean
  skinnedMeshCount: number
  boneCount: number
  jointCount: number
}

The toolbar can then enable/disable the Rig joints mode based on hasRig.

The overlay should not rely on THREE.SkeletonHelper directly. In the local prototype, custom LineSegments and marker meshes are updated every frame using bone world positions converted into scene-local coordinates:

bone.getWorldPosition(worldPosition)
target.copy(worldPosition)
scene.worldToLocal(target)

This is important because the model root can be recentered after loading, and using local-space positions avoids overlay drift/misalignment.

---

Suggested scope

In scope:

• Add Rig joints viewer mode.
• Detect rig/skeleton availability.
• Disable the mode when no rig exists.
• Show translucent mesh shell.
• Show bone connection lines.
• Show joint markers.
• Keep overlay aligned during camera orbit / auto-rotate / animation playback.
• Keep it frontend-only.

Out of scope:

• Rig Editor.
• PoseClip.
• Bone renaming.
• Rig metadata sidecars.
• Bone influence coloring.
• Editing or moving joints/bones.
• Backend/API changes.

---

Files likely involved

Potentially:

src/areas/generate/models.ts
src/areas/generate/components/ViewerToolbar.tsx
src/areas/generate/components/Viewer3D.tsx

Optional tests:

src/areas/generate/components/ViewerToolbar.test.ts
src/areas/generate/components/Viewer3D.test.ts

---

Feedback requested

Before turning this into a PR, I’d like feedback on the visual style and scope:

1. Should Rig joints include both bone lines and joint markers, like the current prototype?
2. Is the octahedron/diamond marker shape okay?
3. Is the marker size readable enough?
4. Should the palette stay violet/cyan, or would you prefer different colors?
5. Should the overlay always be visible through the mesh (depthTest: false), or should it be partially occluded?
6. Should bone influence coloring be a separate later issue?

If this sounds useful, I can prepare a small focused PR for the Rig joints viewer mode only, keeping Rig Editor and PoseClip as separate future suggestions/issues.