Studio Aja - Human Mesh Recovery

Purpose#

Admin lane console for the real @aja/motion-validation calculatePCK metric. The operator submits a recovered pose and a ground-truth pose (each a { joints, frames } JSON) plus a normalization value; the lane scores the recovered pose with Percentage of Correct Keypoints - the share of joints within a normalized distance of ground truth, per threshold - and reports the AUC of the PCK-vs-threshold curve.

Entry points#

• Direct URL / bookmark - /studio/aja/human-mesh-recovery; metadata sets alternates.canonical.
• Studio nav - Domain-bridge studios section of /studio.
• Breadcrumb parent - /studio/aja/multi-view-reconstruction.
• Sibling quick-actions on this page - Multi-View Reconstruction, Depth Analysis, Depth Sensing, Pose Estimation, Back to Studio.

Layout regions#

page.tsx renders inside <ShellLayout active="studio">:

• Breadcrumb panel (data-aja-human-mesh-recovery-breadcrumbs): <nav aria-label="Aja Human Mesh Recovery breadcrumbs"> → Studio / Aja Multi-View Reconstruction / Human Mesh Recovery.
• Workspace <StudioAjaHumanMeshRecoveryWorkspace />:
  • <h1> "Aja Human Mesh Recovery Workspace" + summary (data-aja-human-mesh-recovery-summary).
  • Capability Summary panel (data-aja-human-mesh-recovery-capability-summary, 4 cards).
  • Human Mesh Recovery Operations Lane (data-aja-human-mesh-recovery-operations-lane) with the live PCK form.
• Route Map panel (data-aja-human-mesh-recovery-route-map): 6 STUDIO_AJA_HUMAN_MESH_RECOVERY_ROUTE_MAP entries exposed with data-aja-human-mesh-recovery-route-entry / data-route-path.
• Quick-action lane (data-aja-human-mesh-recovery-quick-actions): five Link.quickAction anchors.

States#

The lane fetches GET /v1/admin/aja/human-mesh-recovery on mount.

• Loading - data-aja-hmr-loading "Loading keypoint-accuracy metric...".
• Unauthorized - data-aja-hmr-unauthorized (401/403; default "Aja workspace scope required to score keypoint accuracy.").
• Error - data-aja-hmr-error for non-OK, malformed catalog, network failure, or unavailable fetch.
• Ready (form) - data-aja-hmr-catalog with metric, threshold count, default normalization, threshold spans, and idle data-aja-hmr-form.
• Result - data-aja-hmr-result with stable AUC, threshold count, joint count, per-threshold data-aja-hmr-pck-row, and per-joint data-aja-hmr-per-joint-row evidence.
• Validation / assess error - data-aja-hmr-assess-error for local JSON / normalization validation, BFF validation-detail messages, malformed success payloads, and transport failures.
• Pending - pose textareas, normalization input, and submit disable while data-aja-hmr-form-state="assessing" / data-aja-hmr-submit-state="assessing".
• Mobile/touch containment - form controls and route actions remain at least 44 px tall with no horizontal overflow.

Interactions#

Operations lane (data-aja-hmr-form)#

• Recovered pose - textarea data-aja-hmr-prediction, aria-label "prediction motion json", JSON { joints, frames }.
• Ground-truth pose - textarea data-aja-hmr-ground-truth, aria-label "ground truth motion json", JSON { joints, frames }.
• Normalization value - input data-aja-hmr-norm, aria-label "normalization value"; must be positive.
• Compute PCK - submit data-aja-hmr-submit; fires POST /v1/admin/aja/human-mesh-recovery/assess with { prediction, groundTruth, normalizationValue }; locked with data-aja-hmr-submit-state="assessing" while the real request is pending.

Capability Summary#

• 4 cards (data-aja-human-mesh-recovery-capability=<id>): mesh-recovery-control-plane, diagnostics-and-trace-observability, security-permission-audit-controls, and api-parity-and-contract-assurance - non-interactive.

Route Map panel#

• Route entries (6) - non-interactive listing with exact path ordering.

Quick-action lane#

• "Open Aja Multi-View Reconstruction workspace" - /studio/aja/multi-view-reconstruction
• "Open Aja Depth Analysis workspace" - /studio/aja/depth-analysis
• "Open Aja Depth Sensing workspace" - /studio/aja/depth-sensing
• "Open Aja Pose Estimation workspace" - /studio/aja/pose-estimation
• "Back to Studio workspace index" - /studio

Data & contracts#

• Reads: GET /v1/admin/aja/human-mesh-recovery (catalog: metric, summary, defaultThresholds, defaultNormalizationValue); client fails closed unless the expected pck metric, default thresholds [0.05, 0.1, 0.15, 0.2], and default normalization 0.15 are present.
• Writes: POST /v1/admin/aja/human-mesh-recovery/assess → { result: { thresholds, pck, auc, perJoint } }; client fails closed unless thresholds are positive finite numbers, PCK scores and AUC are finite in [0, 1], and every per-joint row has threshold-aligned finite scores.
• Realtime: none.
• Caching: client fetch on mount (cache: 'no-store'); SSR shell.
• Auth/role check: BFF endpoints are admin-scoped and fail-closed (401/403 → unauthorized render); route is gated signed-in + studio via proxy.

Cross-references#

• Parent: ../../studio-overview.md
• Shell: ../../../shell/04-auth-session.md
• Sibling routes: ./studio-aja-multi-view-reconstruction.md, ./studio-aja-depth-analysis.md, ./studio-aja-depth-sensing.md, ./studio-aja-pose-estimation.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioAjaHumanMeshRecoveryWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioAjaHumanMeshRecoveryRouteMap.ts

Verification evidence#

• apps/oshun/web/e2e/studio-aja-human-mesh-recovery.spec.ts runs against the real Next Studio shell and local BFF, forwarding browser bearer auth rather than mocking the keypoint-accuracy contract.
• The spec covers anonymous redirect, Aja-admin catalog load, exact shipped partial-pose PCK/AUC output, edited perfect-pose output, local validation with no POST, BFF validation details, malformed result, transport failure, loading / 503 / malformed / non-admin states, pending form locking, breadcrumbs, mobile no-overflow / 44px controls, scoped axe, and direct BFF 401/403/400/200 gates.

Open questions / known gaps#

• Route-map sub-routes are advertised but have no page.tsx in V1.