# facebookresearch/ai4animationpy architecture

> Architecture diagram of the GitHub repository facebookresearch/ai4animationpy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/facebookresearch/ai4animationpy
- Repository: https://github.com/facebookresearch/ai4animationpy

## Overview

AI4AnimationPy is a Python framework for motion-capture processing, neural-network training and inference, and character-animation visualization. A typical workflow imports motion, builds animation features, trains or runs a model, then applies predicted motion to a character in the ECS scene and optionally renders it. The README also documents standalone, headless, and manual execution, motion editing, IK, and rendering capabilities. The graph combines these documented capabilities with sampled demo behavior; some subsystem wiring is documented rather than visible in the excerpts.

Main entry points: [`ai4animation/Components/Actor.py`](https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Components/Actor.py) (Character actor), [`ai4animation/Scene.py`](https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Scene.py) (Scene and entities), [`ai4animation/Animation/Motion.py`](https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Animation/Motion.py) (Motion representation), [`ai4animation/AI/Models`](https://github.com/facebookresearch/ai4animationpy/tree/main/ai4animation/AI/Models) (Neural models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and ECS"]
  node_engine["Framework runtime<br/>[AI4Animation.py]"]
  node_scene["Scene and entities<br/>[Scene.py]"]
  node_components["ECS components<br/>[Component.py]"]
end

subgraph group_motion["Motion Data"]
  node_importers["Motion importers"]
  node_motion["Motion representation<br/>[Motion.py]"]
  node_dataset["Dataset and modules<br/>[Dataset.py]"]
  node_exporter["GLB exporter<br/>[GLBExporter.py]"]
end

subgraph group_learning["AI and Inference"]
  node_features["Feature tensors<br/>[FeedTensor.py]"]
  node_sampler["Batch sampler<br/>[DataSampler.py]"]
  node_models["Neural models"]
  node_optimizers["Training optimizers"]
end

subgraph group_animation["Character Animation"]
  node_actor["Character actor<br/>[Actor.py]"]
  node_prediction["Motion prediction<br/>[Program.py]"]
  node_sequence["Motion sequences<br/>[TimeSeries.py]"]
  node_ik["FABRIK solver<br/>[FABRIK.py]"]
  node_math["Animation math<br/>[Transform.py]"]
end

subgraph group_visual["Visualization"]
  node_editor["Motion editor<br/>[MotionEditor.py]"]
  node_renderer["Render pipeline<br/>[RenderPipeline.py]"]
  node_mesh["Skinned mesh<br/>[SkinnedMesh.py]"]
end

node_user(("Researcher / operator"))
node_motion_files["Motion files"]

node_user -->|"selects mode"| node_engine
node_engine -->|"runs callbacks"| node_scene
node_scene -->|"manages lifecycle"| node_components
node_motion_files -->|"provides files"| node_importers
node_importers -->|"loads motion"| node_motion
node_motion -->|"supplies clips"| node_dataset
node_dataset -->|"provides samples"| node_sampler
node_sampler -->|"builds batches"| node_features
node_features -->|"feeds tensors"| node_models
node_models -->|"trains with"| node_optimizers
node_models -->|"predicts motion"| node_prediction
node_user -->|"controls character"| node_prediction
node_prediction -->|"constructs sequence"| node_sequence
node_sequence -->|"drives pose"| node_actor
node_actor -->|"solves joints"| node_ik
node_ik -->|"uses transforms"| node_math
node_actor -->|"updates skin"| node_mesh
node_editor -->|"browses motion"| node_dataset
node_editor -->|"displays character"| node_actor
node_scene -->|"draws scene"| node_renderer
node_renderer -->|"renders skin"| node_mesh
node_motion -->|"exports motion"| node_exporter
node_actor -->|"uses transforms"| node_math

click node_engine "https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/AI4Animation.py"
click node_scene "https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Scene.py"
click node_components "https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Components/Component.py"
click node_actor "https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Components/Actor.py"
click node_importers "https://github.com/facebookresearch/ai4animationpy/tree/main/ai4animation/Import"
click node_motion "https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Animation/Motion.py"
click node_dataset "https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Animation/Dataset.py"
click node_features "https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/AI/FeedTensor.py"
click node_sampler "https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/AI/DataSampler.py"
click node_models "https://github.com/facebookresearch/ai4animationpy/tree/main/ai4animation/AI/Models"
click node_optimizers "https://github.com/facebookresearch/ai4animationpy/tree/main/ai4animation/AI/Optimizers"
click node_prediction "https://github.com/facebookresearch/ai4animationpy/blob/main/Demos/Locomotion/Biped/Program.py"
click node_sequence "https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Animation/TimeSeries.py"
click node_ik "https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/IK/FABRIK.py"
click node_editor "https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Components/MotionEditor.py"
click node_renderer "https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Standalone/RenderPipeline.py"
click node_mesh "https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Standalone/SkinnedMesh.py"
click node_math "https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Math/Transform.py"
click node_exporter "https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Export/GLBExporter.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_engine,node_scene,node_components toneBlue
class node_importers,node_motion,node_dataset,node_exporter toneAmber
class node_features,node_sampler,node_models,node_optimizers toneMint
class node_actor,node_prediction,node_sequence,node_ik,node_math toneRose
class node_editor,node_renderer,node_mesh,node_user,node_motion_files toneIndigo
```

## Components

### Runtime and ECS

- [Framework runtime](https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/AI4Animation.py): `ai4animation/AI4Animation.py`
- [Scene and entities](https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Scene.py): `ai4animation/Scene.py`
- [ECS components](https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Components/Component.py): `ai4animation/Components/Component.py`

### Motion Data

- [Motion importers](https://github.com/facebookresearch/ai4animationpy/tree/main/ai4animation/Import): `ai4animation/Import`
- [Motion representation](https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Animation/Motion.py): `ai4animation/Animation/Motion.py`
- [Dataset and modules](https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Animation/Dataset.py): `ai4animation/Animation/Dataset.py`
- [GLB exporter](https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Export/GLBExporter.py): `ai4animation/Export/GLBExporter.py`

### AI and Inference

- [Feature tensors](https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/AI/FeedTensor.py): `ai4animation/AI/FeedTensor.py`
- [Batch sampler](https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/AI/DataSampler.py): `ai4animation/AI/DataSampler.py`
- [Neural models](https://github.com/facebookresearch/ai4animationpy/tree/main/ai4animation/AI/Models): `ai4animation/AI/Models`
- [Training optimizers](https://github.com/facebookresearch/ai4animationpy/tree/main/ai4animation/AI/Optimizers): `ai4animation/AI/Optimizers`

### Character Animation

- [Character actor](https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Components/Actor.py): `ai4animation/Components/Actor.py`
- [Motion prediction](https://github.com/facebookresearch/ai4animationpy/blob/main/Demos/Locomotion/Biped/Program.py): `Demos/Locomotion/Biped/Program.py`
- [Motion sequences](https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Animation/TimeSeries.py): `ai4animation/Animation/TimeSeries.py`
- [FABRIK solver](https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/IK/FABRIK.py): `ai4animation/IK/FABRIK.py`
- [Animation math](https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Math/Transform.py): `ai4animation/Math/Transform.py`

### Visualization

- [Motion editor](https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Components/MotionEditor.py): `ai4animation/Components/MotionEditor.py`
- [Render pipeline](https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Standalone/RenderPipeline.py): `ai4animation/Standalone/RenderPipeline.py`
- [Skinned mesh](https://github.com/facebookresearch/ai4animationpy/blob/main/ai4animation/Standalone/SkinnedMesh.py): `ai4animation/Standalone/SkinnedMesh.py`

### Other components

- **Researcher / operator**
- **Motion files**

## Connections

- Researcher / operator → Framework runtime: selects mode
- Framework runtime → Scene and entities: runs callbacks
- Scene and entities → ECS components: manages lifecycle
- Motion files → Motion importers: provides files
- Motion importers → Motion representation: loads motion
- Motion representation → Dataset and modules: supplies clips
- Dataset and modules → Batch sampler: provides samples
- Batch sampler → Feature tensors: builds batches
- Feature tensors → Neural models: feeds tensors
- Neural models → Training optimizers: trains with
- Neural models → Motion prediction: predicts motion
- Researcher / operator → Motion prediction: controls character
- Motion prediction → Motion sequences: constructs sequence
- Motion sequences → Character actor: drives pose
- Character actor → FABRIK solver: solves joints
- FABRIK solver → Animation math: uses transforms
- Character actor → Skinned mesh: updates skin
- Motion editor → Dataset and modules: browses motion
- Motion editor → Character actor: displays character
- Scene and entities → Render pipeline: draws scene
- Render pipeline → Skinned mesh: renders skin
- Motion representation → GLB exporter: exports motion
- Character actor → Animation math: uses transforms