# Galatea Domain

> **Galatea** - Robotics, Kinematics, and Fashion Robotics

Library-only domain providing advanced robotics frameworks for humanoid fashion
robots, including inverse/forward kinematics solvers, hardware abstraction,
computer vision, safety systems compliant with ISO 13482, fleet management,
choreographed show performances, garment handling, and AI-driven behavior. Named
after the mythological statue brought to life by Pygmalion.

---

## Overview

The Galatea domain implements a complete robotics software stack purpose-built
for humanoid robots that operate in fashion retail and entertainment
environments. The domain spans from low-level firmware and motor control up
through perception, AI behavioral engines, and choreographed multi-robot show
orchestration. A distinguishing characteristic is its focus on garment
management (outfit tracking, cloth manipulation, quick-change systems) and
inclusivity (body profiles, cultural configuration, multilingual support).

All libraries use Zod for runtime schema validation and export a library
identifier constant (`GALATEA_LIBRARY_ID`) for runtime module identification.

---

## Architecture

```
             @galatea/sdk          @galatea/analytics
             (developer SDK)       (engagement, A/B, revenue)
                    |                      |
    +-------+-------+-------+------+------+------+
    |       |       |       |      |      |      |
 fleet  choreography  show  garment  simulation  ai
    |       |       events  mgmt      |      |
    +-------+-------+-------+------+------+------+
                            |
         +------------------+------------------+
         |                  |                  |
    kinematics    whole-body-control    locomotion
         |                  |                  |
         +------------------+------------------+
                            |
              +-------------+-------------+
              |             |             |
         hardware-     perception     safety
         abstraction   (vision,       (ISO 13482,
         (joints,       SLAM,         force limits)
          sensors)      depth)
              |             |             |
              +-------------+-------------+
                            |
                     @galatea/core
              (types, constants, utils, errors)
```

### Layer Summary

1. **Core** - Shared types (joint angles, poses, coordinate frames), constants,
   utilities, error definitions, and configuration
2. **Hardware** - Joint interfaces, actuator profiles, sensor fusion, body
   morphing, face/hand systems, thermal management, tactile skin, RFID
3. **Motion** - Forward/inverse kinematics, dynamics, collision geometry,
   Jacobian computation, URDF parsing, gait planning, balance control
4. **Intelligence** - VLA runtime, behavioral engine, natural motion generation,
   reinforcement learning, teleoperation, large behavior models
5. **Application** - Fleet orchestration, choreography, garment management, show
   scheduling, simulation, analytics

---

## Libraries (20)

### `@galatea/core` - Core Robotics Framework

Foundational types, constants, utilities, error definitions, and configuration
shared across all Galatea libraries. Defines coordinate frame types, joint angle
representations, robot configuration schemas, and standardized error codes.

**Key exports:** `types`, `constants`, `utils`, `errors`, `config`

**Dependencies:** `zod`

### `@galatea/kinematics` - IK/FK Solvers and Joint Calculations

Computational kinematics library providing:

- **forward-kinematics** - Denavit-Hartenberg parameter chain evaluation, end
  effector position/orientation computation
- **inverse-kinematics** - Analytical and numerical IK solvers (Jacobian
  transpose, damped least squares, CCD)
- **dynamics** - Recursive Newton-Euler dynamics, inertia tensor computation,
  torque calculation
- **collision-geometry** - Swept volume collision detection, self-collision
  checking, safety margin computation
- **jacobian-computation** - Geometric and analytical Jacobian matrix
  computation for velocity-level control
- **urdf-parser** - URDF/XACRO robot description file parser for kinematic chain
  construction

**Dependencies:** `zod`

### `@galatea/hardware-abstraction` - Robot Hardware Abstraction Layer

Unified hardware interface abstracting physical robot components:

- **joint-interface** - Standardized joint command/feedback API across actuator
  types
- **actuator-profiles** - Motor characterization profiles (torque curves,
  thermal limits, backlash)
- **sensor-fusion** - Multi-sensor fusion combining IMU, encoders, force/torque,
  and vision
- **body-morphing** - Configurable body dimensions for different robot platforms
- **face-system** - Facial expression actuator control (eyes, mouth, brows)
- **hand-system** - Dexterous hand control with finger-level articulation
- **thermal-management** - Motor and electronics thermal monitoring and
  throttling
- **rfid-reader** - RFID tag reader interface for garment identification
- **tactile-skin** - Capacitive tactile skin sensor array processing

**Dependencies:** `zod`

### `@galatea/locomotion` - Walking, Running, and Movement

Bipedal locomotion control:

- **gait-planner** - Walking gait generation (trot, walk, run patterns)
- **balance-controller** - Center of pressure and ZMP-based balance maintenance
- **footstep-planner** - Footstep placement planning with obstacle avoidance
- **step-controller** - Individual step execution with swing/stance phase timing
- **push-recovery** - Disturbance recovery using stepping and hip strategies
- **stair-navigation** - Stair ascent/descent with terrain estimation
- **walking-styles** - Configurable walking style parameters (pace, elegance,
  energy)

**Dependencies:** `zod`

### `@galatea/whole-body-control` - Full-Body Motion Control

Whole-body control framework for coordinated multi-joint motion:

- **task-space-controller** - Operational space control for Cartesian-space
  tasks
- **impedance-controller** - Variable impedance control for compliant
  interaction
- **admittance-controller** - Force-to-motion admittance control for safe
  human-robot interaction
- **postural-controller** - Posture maintenance during task execution
  (null-space optimization)
- **center-of-mass** - Center of mass tracking and momentum regulation
- **momentum-controller** - Angular momentum control for dynamic motion

**Dependencies:** `zod`

### `@galatea/perception` - Computer Vision and Sensor Fusion

Robot perception and environment understanding:

- **audience-awareness** - Audience detection, attention tracking, and
  engagement estimation
- **camera-only-perception** - Vision-only perception pipeline (no LiDAR/depth
  required)
- **depth-processing** - Depth camera (Intel RealSense, ZED) point cloud
  processing
- **fit-analysis** - Garment fit analysis using visual measurement
- **garment-recognition** - Garment type, color, and style classification
- **obstacle-detection** - Dynamic and static obstacle detection for navigation
- **person-detection** - Person detection, pose estimation, and tracking
- **slam** - Simultaneous Localization and Mapping for indoor retail
  environments
- **visual-servoing** - Image-based and position-based visual servo control

**Dependencies:** `zod`

### `@galatea/ai` - AI for Robotics

AI and machine learning systems for robot intelligence:

- **vla-runtime** - Vision-Language-Action model runtime for instruction
  following
- **behavioral-engine** - Finite state machine and behavior tree execution
- **natural-motion-gen** - Natural motion generation from high-level
  descriptions
- **customer-engagement** - Customer interaction management and dialog
- **llm-interaction** - Large language model integration for conversational
  ability
- **emotion-expression** - Emotional expression generation and modulation
- **fashion-trend-ai** - Fashion trend analysis and recommendation
- **attention-prediction** - Visual attention prediction for scene understanding
- **reinforcement-learning** - RL training infrastructure for policy learning
- **quiet-locomotion** - Noise-minimized locomotion policy optimization
- **end-to-end-control** - End-to-end neural network control policies
- **large-behavior-model** - Foundation behavior model fine-tuning
- **motor-cortex-policy** - Motor cortex-inspired hierarchical control
- **teleoperation** - Remote teleoperation interface and control mapping
- **data-collection** - Robot experience data collection for training
- **training-infrastructure** - Distributed training infrastructure management

**Dependencies:** `zod`

### `@galatea/safety` - Safety Systems and Compliance

ISO 13482 compliant safety infrastructure:

- **iso-13482** - ISO 13482 personal care robot safety standard compliance
  checking
- **risk-assessment** - Automated risk assessment with hazard identification
- **force-limiting** - Real-time force and torque limiting for safe interaction
- **emergency-systems** - Emergency stop, safe state transition, and alarm
  management
- **functional-safety** - Functional safety monitoring with watchdog timers
- **regulatory-toolkit** - Regulatory compliance documentation generation
- **audit-logger** - Safety-critical event audit logging with tamper detection
- **access-control** - Physical and logical access control for robot operations

**Dependencies:** `zod`

### `@galatea/communication` - Robot-to-Robot and Human Communication

Communication protocols and networking:

- **ethercat-master** - EtherCAT industrial fieldbus master for real-time motor
  control
- **canfd-interface** - CAN FD interface for embedded device communication
- **dds-bridge** - Data Distribution Service (DDS) bridge for ROS 2 interop
- **wifi-mesh** - WiFi mesh networking for multi-robot coordination
- **cloud-connector** - Cloud platform connectivity for telemetry and updates
- **ptp-sync** - IEEE 1588 Precision Time Protocol synchronization

**Dependencies:** `zod`

### `@galatea/firmware` - Robot Firmware Management

Low-level firmware abstraction:

- **motor-drivers** - Motor driver firmware interface (BLDC, stepper, servo)
- **sensor-interfaces** - Sensor firmware protocols (SPI, I2C, UART)
- **safety-controller** - Hardware safety controller firmware interface
- **power-management** - Battery management, power distribution, charging
- **comms-bus** - Communication bus firmware abstraction
- **rtos-runtime** - Real-time operating system runtime interface
- **bootloader** - Secure bootloader and firmware update management
- **board-support** - Board support packages for target hardware platforms

**Dependencies:** `zod`

### `@galatea/choreography` - Motion Choreography and Shows

Choreographed multi-robot performance system:

- **show-designer** - Visual show design tool with timeline and keyframe editing
- **show-dsl** - Domain-specific language for show scripting
- **formation-engine** - Multi-robot formation planning and transitions
- **music-sync** - Audio beat detection and music synchronization
- **lighting-bridge** - DMX/ArtNet lighting control integration
- **stage-mapper** - Stage geometry mapping and robot positioning
- **timing-engine** - Precise timing coordination across robots and effects
- **rehearsal-engine** - Rehearsal mode with preview and collision checking
- **show-scheduler** - Show scheduling with maintenance window management

**Dependencies:** `zod`

### `@galatea/fleet` - Multi-Robot Fleet Management

Fleet operations and remote management:

- **orchestrator** - Multi-robot task allocation and coordination
- **health-monitoring** - Real-time robot health dashboards and alerting
- **scheduling-engine** - Robot scheduling for shifts, shows, and maintenance
- **ota-updates** - Over-the-air firmware and software update distribution
- **raas-billing** - Robotics-as-a-Service billing and usage metering
- **remote-diagnostics** - Remote diagnostic and troubleshooting tools
- **capacity-planning** - Fleet capacity planning and demand forecasting
- **incident-management** - Incident tracking and resolution workflow
- **federated-learning** - Federated learning across fleet for shared model
  improvement
- **digital-nervous-system** - Fleet-wide telemetry aggregation and anomaly
  detection

**Dependencies:** `zod`

### `@galatea/garment-management` - Clothing and Costume Systems

Fashion and garment handling:

- **outfit-tracking** - RFID and vision-based outfit tracking and inventory
- **digital-product-passport** - Digital product passport for garment provenance
- **cloth-manipulation** - Robotic cloth grasping, folding, and dressing
  assistance
- **quick-change** - Rapid outfit change mechanisms and sequencing
- **fit-validation** - Garment fit validation against body measurements
- **wardrobe-scheduler** - Wardrobe rotation scheduling for fashion shows
- **fabric-safety** - Fabric safety assessment (tear detection, sharp edge
  avoidance)
- **size-adaptation** - Garment size adaptation for different robot body
  configurations

**Dependencies:** `zod`

### `@galatea/pose-engine` - Pose Estimation and Generation

Humanoid pose management:

- **breathing-simulator** - Subtle breathing motion simulation for lifelike
  presence
- **contrapposto-solver** - Classical contrapposto pose calculation for natural
  standing
- **hand-pose-library** - Pre-defined hand gesture and pose library
- **micro-movement-gen** - Micro-movement generation to avoid static appearance
- **pose-library** - Curated full-body pose library with fashion model poses
- **pose-optimizer** - Pose optimization under joint limits and stability
  constraints
- **pose-validation** - Pose safety and feasibility validation
- **transition-planner** - Smooth trajectory planning between poses

**Dependencies:** `zod`

### `@galatea/simulation` - Physics Simulation and Testing

Simulation and digital twin:

- **physics-engine** - Rigid body physics simulation for robot dynamics
- **cloth-simulator** - Cloth physics simulation for garment behavior
- **digital-twin** - Real-time digital twin mirroring physical robot state
- **show-preview** - Show choreography preview in simulation
- **rl-training-env** - Reinforcement learning training environment (Gym-like)
- **wear-simulator** - Garment wear and tear simulation
- **virtual-showroom** - Virtual showroom for customer-facing demonstrations
- **scenario-tester** - Automated scenario testing for safety validation

**Dependencies:** `zod`

### `@galatea/analytics` - Motion and Business Analytics

Engagement and business analytics:

- **engagement-tracker** - Customer engagement duration and interaction tracking
- **ab-testing** - A/B testing framework for robot behavior optimization
- **heatmap-engine** - Store traffic heatmap generation from robot sensors
- **pos-integration** - Point-of-sale system integration for purchase
  attribution
- **inventory-bridge** - Retail inventory system bridge for stock awareness
- **revenue-attribution** - Revenue attribution modeling for robot interactions
- **reporting-dashboard** - Analytics reporting dashboard data aggregation

**Dependencies:** `zod`

### `@galatea/sdk` - Developer SDK

TypeScript client SDK for external developers:

- **client-ts** - TypeScript client for robot control, telemetry, and show
  management APIs

**Dependencies:** `zod`

### `@galatea/database` - Database Stores

Persistence layer with specialized stores (pose-store, event-store,
telemetry-store, garment-store, show-store) for robotics data.

**Dependencies:** `zod`

### `@galatea/inclusivity` - Accessibility and Inclusivity

Inclusivity features including accessibility adaptations, body profile
configurations for diverse body types, cultural customizations for different
markets, and multilingual support for international deployment.

**Dependencies:** `zod`

### `@galatea/event-handlers` - Event Processing

Event handler modules for robot status events, safety system events, garment
interaction events, show performance events, and customer interaction events.

**Dependencies:** `zod`

---

## Technology Stack

| Component  | Technology                            |
| ---------- | ------------------------------------- |
| Language   | TypeScript (ESM)                      |
| Runtime    | Node.js                               |
| Build      | Nx with `@nx/js:tsc`                  |
| Testing    | Vitest                                |
| Validation | Zod (all libraries)                   |
| Protocols  | EtherCAT, CAN FD, DDS, WiFi Mesh, PTP |
| Safety     | ISO 13482 compliance                  |

---

## Development

```bash
# Test a specific library
pnpm nx test @galatea/core

# Build all Galatea libraries
pnpm nx run-many --target=build --projects=tag:scope:galatea

# Lint a library
pnpm nx lint @galatea/kinematics

# Run all domain tests
pnpm nx run-many --target=test --projects=tag:scope:galatea
```

### Configuration

- **Project tags:** `["scope:galatea", "layer:domain", "type:lib"]`
- **Build executor:** `@nx/js:tsc` with `dependsOn: ["^build"]` for correct
  ordering
- All libraries export a `GALATEA_LIBRARY_ID` constant and
  `getGalateaLibraryId()` function
- All libraries use Zod for schema validation
