Metadata-Version: 2.4
Name: pose-platform
Version: 1.25.5
Summary: Pose CLI — motion analysis toolkit. Install sports via extras: pose-platform[badminton]
License: Pose Platform License v1.0
Project-URL: Homepage, https://posecap.com/posecli/
Project-URL: Documentation, https://posecap.com/posecli/docs/
Project-URL: Repository, https://github.com/posecap/pose-cli
Keywords: motion-analysis,sports-science,biomechanics,skeleton-tracking,pose-estimation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy<2,>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.11
Requires-Dist: pyyaml>=6.0
Provides-Extra: badminton
Requires-Dist: pose-sport-badminton; extra == "badminton"
Provides-Extra: all-sports
Requires-Dist: pose-platform[badminton]; extra == "all-sports"
Provides-Extra: llm
Requires-Dist: openai>=1.50; extra == "llm"
Requires-Dist: anthropic>=0.30; extra == "llm"
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == "server"
Requires-Dist: uvicorn>=0.29; extra == "server"
Requires-Dist: pydantic>=2.0; extra == "server"
Requires-Dist: httpx>=0.27; extra == "server"
Requires-Dist: python-multipart>=0.0.9; extra == "server"
Requires-Dist: pyjwt>=2.0; extra == "server"
Provides-Extra: all
Requires-Dist: pose-cli[all-sports,llm]; extra == "all"

# Pose CLI

**Open motion-analysis toolkit for sports scientists.**
`pip install pose-platform` — analyze 3D skeleton data on your machine.

[![PyPI version](https://img.shields.io/pypi/v/pose-platform)](https://pypi.org/project/pose-platform/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)

```bash
pip install pose-platform
pose analyze data/session.csv --tool stats
```

---

## What is Pose CLI?

Pose CLI turns 3D body-skeleton data into reproducible sports analytics.
It runs **entirely on your machine** — your data never leaves your computer.

```
Pose Coach Recording → JointData3D CSV → pose analyze --tool <name> → JSON Output
```

**11 built-in analysis tools**, two supported sports:

| Category | Tools | Sport |
|----------|-------|-------|
| **General** (any movement) | `stats`, `detect_peak_energy`, `segment_motion_phases`, `detect_velocity`, `detect_action_boundaries`, `detect_highlight` | `freeplay` |
| **Running** (reference implementation) | `measure_running_speed`, `score_sprint`, `analyze_running_gait`, `score_running_efficiency` | `sprint` |
| **Multi-sport** | `analyze_motion_angles` | both |

Sprint tools serve as a reference for building your own sport-specific tools.
[See contributing guide →](https://posecap.com/posecli/docs/#contributing)

## Quickstart

```bash
pip install pose-platform

# 获取示例数据（内置在包中，无需网络）
pose sample

# Run your first analysis
pose analyze sample_sprint.csv --tool stats

# Explore available tools
pose tools && pose sports

# LLM-powered analysis (optional — needs openai SDK + API key)
pip install openai>=1.50
export POSE_DEEPSEEK_API_KEY=sk-xxx
pose chat ./data
```

## Installation

- **Python 3.10+** required. Works on macOS, Linux, Windows.
- **`pose chat` LLM 对话**：需额外安装 `pip install openai>=1.50`，并设置 API Key：
  ```bash
  # DeepSeek（推荐，邮箱注册即得）
  export POSE_DEEPSEEK_API_KEY=sk-xxx
  # 或 Qwen / 其他 CN provider
  export POSE_CN_API_KEY=sk-xxx
  ```
  详见 [pose chat 使用指南](#commands)。
- **Full guide**: [posecap.com/posecli/docs/](https://posecap.com/posecli/docs/)

## Data Format

Pose CLI reads **JointData3D CSV** (12-column, no header):

```
timestamp, joint, wx, wy, wz, mx, my, mz, ldq_x, ldq_y, ldq_z, ldq_w
```

Record with Pose Coach (iOS, TestFlight) or convert from OpenPose / MediaPipe / motion capture.
[Data format reference →](https://posecap.com/posecli/docs/#data-format)

## Commands

```bash
pose analyze <file.csv> --tool <name> [--param key=value]  # Run analysis
pose sample                                                    # Copy sample data to CWD
pose tools [--sport <id>] [--detail]                         # List tools
pose sports                                                   # List sports
pose gaps list|submit|show|summary                            # Track feature requests
pose chat [data_dir]                                          # LLM-powered analysis
pose cache list|clear                                         # Manage cache
pose telemetry stats [--since 7d]                             # Usage statistics
pose version [--changelog]                                    # Version info
```

## Extending Pose CLI

Every analysis tool is a Python class. Build your own:

```python
from capabilities.tools.base import DirectTool
from capabilities.tools.loader import load_pose
import json
from pathlib import Path

class MyTool(DirectTool):
    name = "my_tool"
    supported_sports = ["basketball"]  # or [] for all
    input_schema = {"type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"]}

    def run(self, tool_input: dict, output_dir: Path) -> str:
        pose = load_pose(tool_input["path"])
        # your analysis here
        return json.dumps({"result": 42}, ensure_ascii=False)
```

Register a new sport in 3 lines of config.
[Contributing →](https://posecap.com/posecli/docs/#contributing)

## From Source (Platform Developers)

Pose CLI is the public distribution of the Pose Platform. The full platform
(in this repository) also includes the Pose Coach backend, operations tooling,
and badminton-specific analysis tools — these are excluded from the pip package.

```bash
git clone <repo-url>
cd pose_platform
pip install -e .
```

## License

Pose CLI is distributed under the [Pose Platform License v1.0](LICENSE.txt):
- **Research use**: free for academic and educational purposes
- **Commercial use**: requires a separate agreement
- **Attribution**: cite the Pose Platform in publications

## Citation

```bibtex
@software{pose_platform,
  title = {Pose Platform: Open Motion Analysis Toolkit},
  author = {{PoseCap Inc.}},
  year = {2026},
  url = {https://github.com/posecap/pose-platform},
}
```
