How soma-bionics/movedb-core works
Project Type and Purpose
• This is a Python-based core library (not a standalone web or desktop app) for motion capture data operations (“MoveDB Core”).
• It focuses on reading C3D files, processing time-series and force-platform data, validating it, and exporting to OpenSim formats.
Top-Level Architectural Components
a. User Application Layer
• Client code or scripts (e.g., a researcher's Python script, CLI wrappers, notebooks) that import movedb.core.Trial.
b. Public API Layer (src/movedb)
• movedb.core – Domain classes (Trial, Points, Analogs, Event, ForcePlatform, enums)
• movedb.file_io – I/O adapters (C3DLoader using ezc3d, OpenSimExporter using opensim SDK)
• movedb.utils – Pure-Python helper functions (data normalization, logging, validation utilities)
c. External Dependencies
• ezc3d – Native C library bindings for C3D I/O
• opensim (OpenSim-org SDK) – For model export and inverse kinematics
• pydantic – Data validation and type safety
Data Flow and Component Interactions
1. The User Application invokes:
Trial.from_c3d_file(path)
↓
2. C3DLoader (in movedb.file_io)
• Reads binary C3D → produces raw trajectories & analog frames
↓
3. movedb.core.Trial constructor
• Instantiates data classes: Points (time-series), Analogs, Event, EZC3DForcePlatform
• Uses movedb.utils for gap detection, validation (Pydantic)
↓
4. Business Logic
• Data transformations (units, coordinate systems)
• Force platform processing (filtering, mappings)
↓
5. Export / Downstream Services
• Trial.to_trc(), to_mot(), to_xml() via OpenSimExporter → writes TRC/MOT/XML
• Optionally: run_opensim_ik() calls opensim API to compute IK results
Architectural Patterns & Design Principles
• Modular layering: clear separation of I/O (movedb.file_io), domain model (movedb.core), helpers (movedb.utils).
• Dependency inversion: core classes depend on abstracted loader/exporter interfaces.
• Single responsibility: each submodule has isolated concerns (I/O vs. model vs. utils).
• Type safety via Pydantic models for all core data containers.
Detail Without Overthinking
• Every logical component (core classes, file-io adapters, utils, external libs).
• Directional data flow from file input through processing to file output.