PoseGuard AI Documentation
Everything you need to install, configure, script, and deploy PoseGuard AI in your animation pipeline.
Installation
PoseGuard AI requires Python 3.10+ and standard CPU-compatible packages. No NVIDIA GPU or CUDA installation is necessary.
Windows 10 / 11 (Command Prompt)
git clone https://github.com/A35-777/PoseGaurd-AI.git
cd poseguard-ai
py -3.12 -m venv .venv
call .venv\Scripts\activate.bat
python -m pip install --upgrade pip
pip install -r requirements.txt
pip install -e .
Linux (Bash)
git clone https://github.com/A35-777/PoseGaurd-AI.git
cd poseguard-ai
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
pip install -e .
Verify installation: Run poseguard info to confirm the 235K parameter model checkpoint loads properly.
Command Line Interface (`poseguard`)
1. `poseguard analyze`
Inspect a single animation sequence and generate a terminal summary, JSON report, or CSV defect table.
# Terminal summary
poseguard analyze data\raw\subj_01_walk_clean.bvh
# Export JSON report
poseguard analyze data\raw\subj_01_walk_clean.bvh --format json --out-file report.json
# Analyze only specific defect categories
poseguard analyze clip.bvh --filter foot_sliding ground_penetration
2. `poseguard serve`
Launch the interactive 3D Web Studio and REST API server.
poseguard serve --host 127.0.0.1 --port 8000
3. `poseguard batch`
Scan and analyze an entire folder of animation assets for batch production QA.
poseguard batch ./animations/ --format text
4. `poseguard inspect`
Display skeleton joint hierarchy, bounding boxes, duration, and frame rate without running defect classifiers.
poseguard inspect character_run.bvh
Python SDK Integration
Integrate PoseGuard AI directly into your Python animation pipelines, Blender addons, or Maya exporters.
from poseguard import PoseGuard, PoseGuardConfig
# Initialize detector with default CPU model
detector = PoseGuard()
# Optional: customize thresholds
custom_config = PoseGuardConfig(
slide_velocity_threshold=0.06, # Stricter sliding bound (m/s)
penetration_threshold=0.015 # Stricter floor clipping (m)
)
custom_detector = PoseGuard(config=custom_config)
# Run complete analysis
result = detector.analyze("walk_cycle.bvh")
print(f"Overall Quality Status: {result.quality_summary.overall_status}")
print(f"Defect-Free Frames: {result.quality_summary.defect_free_frame_percentage:.1f}%")
for defect in result.defects:
print(f"[{defect.severity}] {defect.type} on {defect.joint}")
print(f" Frames {defect.start_frame}-{defect.end_frame} ({defect.duration_sec:.2f}s)")
print(f" Confidence: {defect.confidence:.2f} | Status: {defect.verification_status}")
print(f" Action: {defect.suggested_correction}")
REST API Reference
When running poseguard serve, the following endpoints are available at http://127.0.0.1:8000:
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/info |
Returns software version, model parameter counts, RAM usage, and supported defects. |
POST |
/api/upload |
Multipart form upload of .bvh, .npz, or .npy file. Returns parsed skeleton and 3D preview points. |
GET |
/api/demo/{name} |
Loads one of the built-in clean or defect sample animations for one-click testing. |
POST |
/api/analyze |
Executes hybrid defect diagnosis on an active session ID. |
GET |
/api/export/json/{session_id} |
Downloads complete structured JSON diagnostic report. |
GET |
/api/export/csv/{session_id} |
Downloads comma-separated defect incident table. |
Supported Formats
- BioVision Hierarchy (.bvh): Pure Python forward kinematics parsing with canonical joint mapping for CMU, Mixamo, and standard biped rigs.
- NumPy Archives (.npz, .npy): Ingests 3D Cartesian joint positions arrays of shape
[T, J, 3]or dictionary archives containingpositions,fps, andjoint_names. - FBX Workflow: Export FBX sequences to BVH using standard Blender scripts for seamless parsing.
Troubleshooting
Animation shows elevated ground penetration on clean walk
Ensure the character's ground plane is aligned with \(Y=0.0\). If the animation floor is offset, specify --ground-y <height> in the CLI or set it in the 3D Studio ground plane slider.
Unusual skeleton joint naming causes missing detections
PoseGuard automatically maps common joint names (e.g. LeftUpLeg, l_thigh, LeftLeg → LeftHip). Check recognized joints with poseguard inspect <file>.