# Aja Domain

> **Aja** - Motion AI and Animation

Named after the Yoruba Orisha Aja (forest guide), this domain provides
comprehensive motion processing from video input to production-ready animation.
It covers pose estimation, skeletal retargeting, motion quality assessment, and
format conversion.

---

## Architecture

### Apps (4)

| App                   | Framework | Port | Purpose                                                                              |
| --------------------- | --------- | ---- | ------------------------------------------------------------------------------------ |
| `svc-motion-pipeline` | Fastify   | 8090 | Pipeline orchestration, jobs, result delivery                                        |
| `svc-motion-ai`       | Hono      | 3040 | AI motion processing (video-to-motion, retargeting, live capture)                    |
| `svc-reference-video` | --        | --   | Reference video library (ingestion, search, annotation, collaboration)               |
| `cli`                 | Commander | --   | CLI tools (`aja process`, `convert`, `inspect`, `debug`, `config`, `jobs`, `health`) |

### Libraries (38)

**Core Motion Processing (5):**

| Library                   | Purpose                                                               |
| ------------------------- | --------------------------------------------------------------------- |
| `@aja/motion-formats`     | Multi-format support (BVH, FBX, GLB, USD, Alembic, C3D, TRC, ASF/AMC) |
| `@aja/motion-processing`  | Filters, smoothing, interpolation                                     |
| `@aja/motion-quality`     | Quality metrics and assessment                                        |
| `@aja/motion-validation`  | Data validation and error detection                                   |
| `@aja/motion-integration` | Integration layer                                                     |

**Video Analysis (4):**

| Library                          | Purpose                        |
| -------------------------------- | ------------------------------ |
| `@aja/pose-lifting`              | 2D to 3D pose lifting          |
| `@aja/depth-sensing`             | Monocular and stereo depth     |
| `@aja/multi-view-reconstruction` | Multi-camera 3D reconstruction |
| `@aja/human-mesh-recovery`       | SMPL/SMPL-X mesh recovery      |

**Skeletal and Avatar (6):**

| Library                   | Purpose                         |
| ------------------------- | ------------------------------- |
| `@aja/skeleton-mapping`   | Skeleton hierarchy conversion   |
| `@aja/optimization-ik`    | Inverse kinematics solvers      |
| `@aja/avatar-library`     | Avatar definitions and presets  |
| `@aja/avatar-integration` | Avatar binding and animation    |
| `@aja/avatar-preview-ui`  | React avatar preview components |
| `@aja/bone-mapping-ui`    | Interactive bone mapping UI     |

**Retargeting and Blending (5):**

| Library                        | Purpose                         |
| ------------------------------ | ------------------------------- |
| `@aja/semantic-retargeting`    | Semantic motion retargeting     |
| `@aja/proportional-adaptation` | Body proportion adaptation      |
| `@aja/blend-shape-retargeting` | Facial blend shape retargeting  |
| `@aja/neural-retargeting`      | ML-based retargeting            |
| `@aja/animation-blending`      | Motion blending and transitions |

**Domain Pipelines (2):**

| Library                        | Purpose                             |
| ------------------------------ | ----------------------------------- |
| `@aja/domain-motion-pipelines` | Pre-configured pipelines per domain |
| `@aja/fitness-animation`       | Fitness-specific analysis           |

**Infrastructure (8):**

| Library                           | Purpose                         |
| --------------------------------- | ------------------------------- |
| `@aja/motion-pipeline-sdk`        | TypeScript SDK                  |
| `@aja/motion-pipeline-sdk-python` | Python SDK with Jupyter support |
| `@aja/batch-inference`            | Batch processing                |
| `@aja/video-chunking`             | Video splitting for processing  |
| `@aja/model-optimization`         | Model compression               |
| `@aja/pipeline-parallelism`       | Distributed processing          |
| `@aja/distributed-workers`        | Worker coordination             |
| `@aja/result-aggregation`         | Result combining                |

**Security and Compliance (6):**

| Library                     | Purpose                       |
| --------------------------- | ----------------------------- |
| `@aja/privacy-protection`   | Privacy-preserving processing |
| `@aja/consent-management`   | Consent tracking              |
| `@aja/content-security`     | Security protocols            |
| `@aja/content-watermarking` | Digital watermarking          |
| `@aja/content-moderation`   | Content filtering             |
| `@aja/data-retention`       | Retention policy enforcement  |

**Utility (1):**

| Library               | Purpose                         |
| --------------------- | ------------------------------- |
| `@aja/pipeline-cache` | LRU caching for pipeline stages |

### Technology Stack

| Layer     | Technologies                                  |
| --------- | --------------------------------------------- |
| SDKs      | TypeScript (Node.js), Python (Jupyter/ML)     |
| Motion    | Custom parsers for 13+ animation formats      |
| ML Models | Pose estimation, depth sensing, mesh recovery |
| Build     | `@nx/js:tsc`                                  |
| Testing   | Vitest                                        |

---

## Processing Pipeline

Aja's motion processing flows through five stages:

```
1. Input Sources
   ├── Video files → Pose Estimation
   ├── Motion Capture (C3D, TRC)
   ├── Animation files (BVH, FBX)
   └── Live MoCap hardware
         │
2. Video Analysis Layer
   ├── Pose Lifting (2D → 3D)
   ├── Depth Sensing
   ├── Multi-View Reconstruction
   └── Human Mesh Recovery (SMPL-X)
         │
3. Motion Processing Layer
   ├── Filtering and Smoothing
   ├── Validation
   └── Quality Assessment
         │
4. Retargeting Layer
   ├── Skeleton Mapping
   ├── Proportional Adaptation
   ├── Neural Retargeting
   └── Animation Blending
         │
5. Output Formats
   ├── BVH, FBX, GLB
   └── Engine-native formats
```

---

## Domain Pipelines

Pre-configured pipelines optimized for specific use cases:

| Domain   | Capabilities                                          |
| -------- | ----------------------------------------------------- |
| Fitness  | Exercise form analysis, rep counting, range of motion |
| Dance    | Choreography capture, style transfer, sync            |
| Sports   | Performance analysis, technique breakdown             |
| Medical  | Gait analysis, rehabilitation, clinical assessment    |
| Gaming   | Real-time capture, gesture recognition                |
| Film/VFX | High-fidelity capture, facial performance             |

---

## Quality Metrics

`@aja/motion-quality` evaluates motion data across four dimensions:

- **Temporal Smoothness** - Jitter detection, acceleration consistency
- **Anatomical Plausibility** - Joint limits, bone lengths, self-penetration
- **Ground Contact** - Foot sliding, plane alignment
- **Semantic Accuracy** - Pose matching, action confidence

---

## Supported Motion Formats

`@aja/motion-formats` handles 13+ formats:

BVH, FBX, GLB/GLTF, USD/USDA, Alembic (ABC), C3D, TRC, ASF/AMC, Collada (DAE),
MDD, PC2, OBJ sequences, custom JSON

---

## Development

```bash
# Run the motion pipeline service
pnpm nx dev @aja/svc-motion-pipeline

# Run tests
pnpm nx test @aja/motion-formats

# Build all Aja libraries
pnpm nx run-many --target=build --projects=tag:scope:aja
```

---

## CI/CD

Aja uses the core CI pipeline (`ci.yml`) and the general ECS deployment pipeline
(`deploy-ecs.yml`).

## Related Documentation

- [Architecture](./architecture.md) - Detailed Aja domain architecture
- [Monorepo Architecture](../../architecture.md) - Monorepo overview
- [Cross-Domain Integration](../../cross-domain-integration.md)
