Metadata-Version: 2.1
Name: pose-platform
Version: 1.25.0
Summary: Pose CLI — open motion-analysis toolkit for sports scientists
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-platform
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
Provides-Extra: llm
Provides-Extra: server

# 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

# Download sample data
curl -O https://posecap.com/samples/sample_sprint.csv

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

# Explore available tools
pose tools && pose sports

# LLM-powered analysis (optional)
export POSE_DEEPSEEK_API_KEY=sk-xxx
pose chat ./data
```

## Installation

- **Python 3.10+** required. Works on macOS, Linux, Windows.
- **Optional**: `pip install openai anthropic` for LLM chat support.
- **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 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},
}
```
