Aja Inverse Kinematics

Purpose#

Admin lane console wired to the real @aja/optimization-ik FABRIK solver via /v1/admin/aja/inverse-kinematics: solve a two-bone arm (shoulder→elbow→wrist) so the wrist reaches a target, reporting reachability, convergence, chain length / target distance, residual position error, and iteration count. The operator sets the upper-arm and forearm lengths and a target.

Entry points#

• Direct URL — /studio/aja/inverse-kinematics (signed-in + studio entitlement)
• Sibling quick-actions from this page — Animation Blending, Back to Studio

Layout regions#

page.tsx mounts ShellLayout with active="studio" and renders three panels.

• Workspace panel (data-aja-inverse-kinematics-workspace):
  • <h1> "Aja Inverse Kinematics Workspace" (via WorkspaceHeading)
  • <p data-aja-inverse-kinematics-summary> — "Solve a two-bone arm with the FABRIK solver so the wrist reaches a target — preview reach, convergence, and the residual position error."
  • data-aja-ik-solver (solver + chain + tolerance) + the solve form
• Route Map panel (data-aja-inverse-kinematics-route-map): <h2> "Route Map" + one <article> per STUDIO_AJA_INVERSE_KINEMATICS_ROUTE_MAP entry (5 entries)
• Quick actions panel: .quickAction <Link>s — see Interactions

States#

• Loading — data-aja-ik-loading "Loading inverse-kinematics solver…"
• Unauthorized — on 401/403, data-aja-ik-unauthorized ("Access restricted." + reason, default "Aja workspace scope required to view inverse kinematics.")
• Error — non-OK / malformed / unreachable → data-aja-ik-error
• Ready (form) — catalog present: data-aja-ik-solver + the solve form
• Result — data-aja-ik-result with data-aja-ik-reach (reachable / converged), data-aja-ik-total (chain length / target distance), data-aja-ik-position-error, data-aja-ik-iterations
• Validation error — data-aja-ik-solve-error (e.g. "Bone lengths must be positive numbers." / "Target coordinates must be finite numbers.")

Interactions#

Solve form (data-aja-ik-solve-form)#

• Upper-arm length (m) — input data-aja-ik-field-upper
• Forearm length (m) — input data-aja-ik-field-forearm
• Target X / Y / Z — input data-aja-ik-field-x / -y / -z
• Solve IK — button data-aja-ik-solve-submit; POST /v1/admin/aja/inverse-kinematics/solve with { upperArmLength, forearmLength, target }

Route Map panel (data-aja-inverse-kinematics-route-map)#

Non-interactive <article> blocks from STUDIO_AJA_INVERSE_KINEMATICS_ROUTE_MAP (5 entries): /studio/aja/inverse-kinematics plus …/scenes/[sceneId], …/exports/[exportId], …/revisions/[revisionId], …/governance/[policyId].

Quick actions panel#

• Open Aja Animation Blending workspace → /studio/aja/animation-blending
• Back to Studio workspace index → /studio

Data & contracts#

• Reads: GET /v1/admin/aja/inverse-kinematics (catalog: solver, chain, positionTolerance) on mount via buildBffAuthHeaders(), cache: 'no-store'
• Writes: POST …/solve → { solution }
• Realtime: none
• Caching: client fetch on mount (no-store); SSR shell only
• Auth: BFF endpoints admin-scoped + fail-closed (401/403 → unauthorized render); the route is signed-in + studio (proxy gate)

Cross-references#

• Parent: ../../studio-overview.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioAjaInverseKinematicsWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioAjaInverseKinematicsRouteMap.ts
• Sibling from quick-actions: /studio/aja/animation-blending

Open questions / known gaps#

• Route-map sub-routes are descriptive only; confirm implementation status
• Document the exact studio entitlement / proxy gate governing /studio/aja/*