PoseGuard AI Documentation

Everything you need to install, configure, script, and deploy PoseGuard AI in your animation pipeline.

Installation CLI Reference Python SDK REST API Supported Formats Troubleshooting

Installation

PoseGuard AI requires Python 3.10+ and standard CPU-compatible packages. No NVIDIA GPU or CUDA installation is necessary.

Download PoseGuard AI v1.0.2-beta (ZIP) GitHub Release

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

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>.