---
path: /studio/aja/human-mesh-recovery
surface: studio
domain: aja
auth: signed-in + studio entitlement
source: apps/oshun/web/src/app/studio/aja/human-mesh-recovery/page.tsx
status: walked + e2e-covered
last_walked:
  '2026-07-04 focused real-dev-infra Playwright route walk - anonymous redirect,
  Aja-admin PCK catalog, exact shipped partial pose, edited perfect pose through
  the real BFF, local/BFF validation, malformed/transport failures,
  loading/403/503/malformed catalog states, pending controls, breadcrumbs,
  route-map + quick-action affordances, mobile/touch/axe, and direct BFF
  auth/schema gates. Evidence:
  WALKTHROUGH/results/v1-real-infra-run-2026-06-22.md §297.'
---

# 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.

- [x] **Loading** - `data-aja-hmr-loading` "Loading keypoint-accuracy
      metric...".
- [x] **Unauthorized** - `data-aja-hmr-unauthorized` (401/403; default "Aja
      workspace scope required to score keypoint accuracy.").
- [x] **Error** - `data-aja-hmr-error` for non-OK, malformed catalog, network
      failure, or unavailable `fetch`.
- [x] **Ready (form)** - `data-aja-hmr-catalog` with metric, threshold count,
      default normalization, threshold spans, and idle `data-aja-hmr-form`.
- [x] **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.
- [x] **Validation / assess error** - `data-aja-hmr-assess-error` for local JSON
      / normalization validation, BFF validation-detail messages, malformed
      success payloads, and transport failures.
- [x] **Pending** - pose textareas, normalization input, and submit disable
      while `data-aja-hmr-form-state="assessing"` /
      `data-aja-hmr-submit-state="assessing"`.
- [x] **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`)

- [x] **Recovered pose** - textarea `data-aja-hmr-prediction`, aria-label
      "prediction motion json", JSON `{ joints, frames }`.
- [x] **Ground-truth pose** - textarea `data-aja-hmr-ground-truth`, aria-label
      "ground truth motion json", JSON `{ joints, frames }`.
- [x] **Normalization value** - input `data-aja-hmr-norm`, aria-label
      "normalization value"; must be positive.
- [x] **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

- [x] **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

- [x] **Route entries** (6) - non-interactive listing with exact path ordering.

### Quick-action lane

- [x] **"Open Aja Multi-View Reconstruction workspace"** -
      `/studio/aja/multi-view-reconstruction`
- [x] **"Open Aja Depth Analysis workspace"** - `/studio/aja/depth-analysis`
- [x] **"Open Aja Depth Sensing workspace"** - `/studio/aja/depth-sensing`
- [x] **"Open Aja Pose Estimation workspace"** - `/studio/aja/pose-estimation`
- [x] **"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`](../../studio-overview.md)
- Shell:
  [`../../../shell/04-auth-session.md`](../../../shell/04-auth-session.md)
- Sibling routes:
  [`./studio-aja-multi-view-reconstruction.md`](./studio-aja-multi-view-reconstruction.md),
  [`./studio-aja-depth-analysis.md`](./studio-aja-depth-analysis.md),
  [`./studio-aja-depth-sensing.md`](./studio-aja-depth-sensing.md),
  [`./studio-aja-pose-estimation.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.