# OpenCap Visualizer
Generate videos from OpenCap biomechanics data files with both command-line interface and Python API.
This tool uses the deployed [OpenCap Visualizer](https://opencap-visualizer.onrender.com/) to create videos from biomechanics data files (.json, .osim/.mot pairs) using headless browser automation.
## Features
- **Dual Interface**: Both command-line tool and Python API
- **No Local Setup Required**: Uses deployed web application by default
- **Multiple Data Formats**: Supports JSON files and OpenSim .osim/.mot pairs
- **Subject Comparison**: Generate videos with multiple subjects
- **Anatomical Camera Views**: Use biomechanics-friendly camera angles
- **Customizable**: Colors, zoom, centering, loops, and dimensions
- **Automatic 3D Geometry**: Loads realistic human models from cloud storage
## Installation
```bash
pip install opencap-visualizer
```
**Note**: After installation, you'll need to install browser dependencies:
```bash
playwright install chromium
```
## Command Line Usage
### Basic Examples
```bash
# Single subject
opencap-visualizer data.json -o output.mp4
# Multiple subjects comparison
opencap-visualizer subject1.json subject2.json -o comparison.mp4
# With custom settings
opencap-visualizer data.json --camera anterior --colors red --loops 2 -o front_view.mp4
# OpenSim files
opencap-visualizer model.osim motion.mot -o simulation.mp4
```
### Advanced Examples
```bash
# Multiple subjects with different colors
opencap-visualizer s1.json s2.json s3.json --colors red green blue --camera sagittal -o side_comparison.mp4
# High-resolution with custom zoom
opencap-visualizer data.json --width 3840 --height 2160 --zoom 0.8 --camera superior -o 4k_top_view.mp4
# Interactive mode for manual exploration
opencap-visualizer data.json --interactive --camera anterior
```
### Camera Views
#### Anatomical Views (Recommended)
- `anterior` / `frontal` / `coronal` - Front-facing view
- `posterior` - Back view
- `sagittal` / `lateral` - Side profile view
- `superior` - Top-down view
- `inferior` - Bottom-up view
#### Technical Views
- `top`, `bottom`, `front`, `back`, `left`, `right`
- `isometric`, `default`
- Corner views: `frontTopRight`, `backBottomLeft`, etc.
### Command Line Options
```
positional arguments:
FILE Data files (.json, or .osim/.mot pairs)
optional arguments:
-o, --output PATH Output video file (default: animation_video.mp4)
--camera VIEW Camera position (default: isometric)
--colors COLOR... Subject colors (hex or names: red, blue, #ff0000)
--loops N Animation loops to record (default: 1)
--width PX Video width (default: 1920)
--height PX Video height (default: 1080)
--zoom FACTOR Zoom factor (>1.0 = zoom out, default: 1.5)
--no-center Disable auto-centering on subjects
--timeout SEC Loading timeout in seconds (default: 120)
--interactive Open browser for manual exploration
--vue-app-path PATH Custom Vue app index.html path
--dev-server-url URL Custom Vue development server URL
-v, --verbose Enable verbose output
```
## Python API Usage
### Basic Examples
```python
import opencap_visualizer as ocv
# Simple usage
success = ocv.create_video("data.json", "output.mp4")
if success:
print("Video generated successfully!")
# Multiple subjects with settings
success = ocv.create_video(
["subject1.json", "subject2.json"],
"comparison.mp4",
camera="anterior",
colors=["red", "blue"],
loops=2,
verbose=True
)
```
### Class-based Usage
```python
import opencap_visualizer as ocv
# Create visualizer instance
visualizer = ocv.OpenCapVisualizer(verbose=True)
# Generate video synchronously
success = visualizer.generate_video_sync(
input_files=["subject1.json", "subject2.json"],
output_path="comparison.mp4",
camera="sagittal",
colors=["#ff0000", "#00ff00"],
width=1920,
height=1080,
zoom=1.2
)
print(f"Success: {success}")
```
### Async Usage
```python
import asyncio
import opencap_visualizer as ocv
async def generate_videos():
# Using convenience function
success = await ocv.create_video_async(
"data.json",
"output.mp4",
camera="anterior",
colors=["blue"]
)
# Using class
visualizer = ocv.OpenCapVisualizer(verbose=True)
success = await visualizer.generate_video(
["s1.json", "s2.json", "s3.json"],
"triple_comparison.mp4",
camera="posterior",
colors=["red", "green", "blue"],
center_subjects=True,
zoom=1.5
)
return success
# Run async function
success = asyncio.run(generate_videos())
```
### API Reference
#### `OpenCapVisualizer` Class
```python
class OpenCapVisualizer:
def __init__(self, verbose: bool = False)
async def generate_video(
self,
input_files: Union[str, List[str]],
output_path: str = "animation_video.mp4",
*,
vue_app_path: Optional[str] = None,
dev_server_url: Optional[str] = None,
width: int = 1920,
height: int = 1080,
timeout_seconds: int = 120,
loops: int = 1,
camera: Optional[str] = None,
center_subjects: bool = True,
zoom: float = 1.5,
colors: Optional[List[str]] = None,
interactive: bool = False
) -> bool
def generate_video_sync(self, ...) -> bool # Synchronous wrapper
```
#### Convenience Functions
```python
async def create_video_async(input_files, output_path, **kwargs) -> bool
def create_video(input_files, output_path, **kwargs) -> bool
```
## Data Formats
### JSON Files
The tool accepts biomechanics JSON files with the following structure:
```json
{
"Data": {
"ModelScalingVars": "path/to/model.osim",
"Results": "path/to/motion.mot",
"FrameTimesOG": [0.0, 0.033, 0.066, ...]
}
}
```
### OpenSim Files
Alternatively, provide `.osim` (model) and `.mot` (motion) file pairs:
```bash
opencap-visualizer model.osim motion.mot -o output.mp4
```
## Dependencies
The tool automatically detects the best available option:
1. **Deployed Version** (Recommended): `https://opencap-visualizer.onrender.com/`
- No local setup required
- Always up-to-date
- Requires internet connection
2. **Local Development Server**: `http://localhost:3000`
- Start with `npm run serve` in the Vue.js project
- Faster for development/testing
3. **Built Files**: Local `dist/index.html`
- Build with `npm run build` in the Vue.js project
- Works offline
## Configuration
### Custom Servers
```bash
# Use local development server
opencap-visualizer data.json --dev-server-url http://localhost:3000
# Use custom built files
opencap-visualizer data.json --vue-app-path /path/to/dist/index.html
```
### Environment Variables
```bash
# Set default development server
export OPENCAP_DEV_SERVER=http://localhost:3000
```
## Troubleshooting
### Browser Installation
If you get browser-related errors:
```bash
playwright install chromium
```
### Connection Issues
- Check internet connection for deployed version
- For local development: `npm run serve` in Vue project
- For built files: `npm run build` in Vue project
### File Format Issues
- Ensure JSON files contain valid biomechanics data structure
- For OpenSim files, provide both `.osim` and `.mot` files
- Check file paths are correct and accessible
### Video Generation Issues
- Increase timeout: `--timeout 300`
- Enable verbose mode: `--verbose` or `verbose=True`
- Try interactive mode: `--interactive`
## License
MIT License - see LICENSE file for details.
## Contributing
Contributions welcome! Please see the source repository for guidelines.
## Support
For issues and questions:
- GitHub Issues: [https://github.com/utahmobl/opencap-visualizer/issues](https://github.com/utahmobl/opencap-visualizer/issues)
- Web App: [https://opencap-visualizer.onrender.com/](https://opencap-visualizer.onrender.com/)
Raw data
{
"_id": null,
"home_page": "https://github.com/utahmobl/opencap-visualizer",
"name": "opencap-visualizer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "biomechanics, motion-capture, visualization, video, opencap, opensim",
"author": "Selim Gilon",
"author_email": "Selim Gilon <selim.gilon@utah.edu>",
"download_url": "https://files.pythonhosted.org/packages/dc/5e/b56d77365055b147147b5424e88d6d1236a6c3ddc080924fad8c4a008b43/opencap_visualizer-1.1.0.tar.gz",
"platform": "any",
"description": "# OpenCap Visualizer\n\nGenerate videos from OpenCap biomechanics data files with both command-line interface and Python API.\n\nThis tool uses the deployed [OpenCap Visualizer](https://opencap-visualizer.onrender.com/) to create videos from biomechanics data files (.json, .osim/.mot pairs) using headless browser automation.\n\n## Features\n\n- **Dual Interface**: Both command-line tool and Python API\n- **No Local Setup Required**: Uses deployed web application by default\n- **Multiple Data Formats**: Supports JSON files and OpenSim .osim/.mot pairs\n- **Subject Comparison**: Generate videos with multiple subjects\n- **Anatomical Camera Views**: Use biomechanics-friendly camera angles\n- **Customizable**: Colors, zoom, centering, loops, and dimensions\n- **Automatic 3D Geometry**: Loads realistic human models from cloud storage\n\n## Installation\n\n```bash\npip install opencap-visualizer\n```\n\n**Note**: After installation, you'll need to install browser dependencies:\n```bash\nplaywright install chromium\n```\n\n## Command Line Usage\n\n### Basic Examples\n\n```bash\n# Single subject\nopencap-visualizer data.json -o output.mp4\n\n# Multiple subjects comparison\nopencap-visualizer subject1.json subject2.json -o comparison.mp4\n\n# With custom settings\nopencap-visualizer data.json --camera anterior --colors red --loops 2 -o front_view.mp4\n\n# OpenSim files\nopencap-visualizer model.osim motion.mot -o simulation.mp4\n```\n\n### Advanced Examples\n\n```bash\n# Multiple subjects with different colors\nopencap-visualizer s1.json s2.json s3.json --colors red green blue --camera sagittal -o side_comparison.mp4\n\n# High-resolution with custom zoom\nopencap-visualizer data.json --width 3840 --height 2160 --zoom 0.8 --camera superior -o 4k_top_view.mp4\n\n# Interactive mode for manual exploration\nopencap-visualizer data.json --interactive --camera anterior\n```\n\n### Camera Views\n\n#### Anatomical Views (Recommended)\n- `anterior` / `frontal` / `coronal` - Front-facing view\n- `posterior` - Back view \n- `sagittal` / `lateral` - Side profile view\n- `superior` - Top-down view\n- `inferior` - Bottom-up view\n\n#### Technical Views\n- `top`, `bottom`, `front`, `back`, `left`, `right`\n- `isometric`, `default`\n- Corner views: `frontTopRight`, `backBottomLeft`, etc.\n\n### Command Line Options\n\n```\npositional arguments:\n FILE Data files (.json, or .osim/.mot pairs)\n\noptional arguments:\n -o, --output PATH Output video file (default: animation_video.mp4)\n --camera VIEW Camera position (default: isometric)\n --colors COLOR... Subject colors (hex or names: red, blue, #ff0000)\n --loops N Animation loops to record (default: 1)\n --width PX Video width (default: 1920)\n --height PX Video height (default: 1080)\n --zoom FACTOR Zoom factor (>1.0 = zoom out, default: 1.5)\n --no-center Disable auto-centering on subjects\n --timeout SEC Loading timeout in seconds (default: 120)\n --interactive Open browser for manual exploration\n --vue-app-path PATH Custom Vue app index.html path\n --dev-server-url URL Custom Vue development server URL\n -v, --verbose Enable verbose output\n```\n\n## Python API Usage\n\n### Basic Examples\n\n```python\nimport opencap_visualizer as ocv\n\n# Simple usage\nsuccess = ocv.create_video(\"data.json\", \"output.mp4\")\nif success:\n print(\"Video generated successfully!\")\n\n# Multiple subjects with settings\nsuccess = ocv.create_video(\n [\"subject1.json\", \"subject2.json\"],\n \"comparison.mp4\", \n camera=\"anterior\",\n colors=[\"red\", \"blue\"],\n loops=2,\n verbose=True\n)\n```\n\n### Class-based Usage\n\n```python\nimport opencap_visualizer as ocv\n\n# Create visualizer instance\nvisualizer = ocv.OpenCapVisualizer(verbose=True)\n\n# Generate video synchronously\nsuccess = visualizer.generate_video_sync(\n input_files=[\"subject1.json\", \"subject2.json\"],\n output_path=\"comparison.mp4\",\n camera=\"sagittal\", \n colors=[\"#ff0000\", \"#00ff00\"],\n width=1920,\n height=1080,\n zoom=1.2\n)\n\nprint(f\"Success: {success}\")\n```\n\n### Async Usage\n\n```python\nimport asyncio\nimport opencap_visualizer as ocv\n\nasync def generate_videos():\n # Using convenience function\n success = await ocv.create_video_async(\n \"data.json\", \n \"output.mp4\",\n camera=\"anterior\",\n colors=[\"blue\"]\n )\n \n # Using class\n visualizer = ocv.OpenCapVisualizer(verbose=True)\n success = await visualizer.generate_video(\n [\"s1.json\", \"s2.json\", \"s3.json\"],\n \"triple_comparison.mp4\",\n camera=\"posterior\",\n colors=[\"red\", \"green\", \"blue\"],\n center_subjects=True,\n zoom=1.5\n )\n \n return success\n\n# Run async function\nsuccess = asyncio.run(generate_videos())\n```\n\n### API Reference\n\n#### `OpenCapVisualizer` Class\n\n```python\nclass OpenCapVisualizer:\n def __init__(self, verbose: bool = False)\n \n async def generate_video(\n self,\n input_files: Union[str, List[str]],\n output_path: str = \"animation_video.mp4\",\n *,\n vue_app_path: Optional[str] = None,\n dev_server_url: Optional[str] = None,\n width: int = 1920,\n height: int = 1080,\n timeout_seconds: int = 120,\n loops: int = 1,\n camera: Optional[str] = None,\n center_subjects: bool = True,\n zoom: float = 1.5,\n colors: Optional[List[str]] = None,\n interactive: bool = False\n ) -> bool\n \n def generate_video_sync(self, ...) -> bool # Synchronous wrapper\n```\n\n#### Convenience Functions\n\n```python\nasync def create_video_async(input_files, output_path, **kwargs) -> bool\ndef create_video(input_files, output_path, **kwargs) -> bool\n```\n\n## Data Formats\n\n### JSON Files\nThe tool accepts biomechanics JSON files with the following structure:\n```json\n{\n \"Data\": {\n \"ModelScalingVars\": \"path/to/model.osim\",\n \"Results\": \"path/to/motion.mot\",\n \"FrameTimesOG\": [0.0, 0.033, 0.066, ...]\n }\n}\n```\n\n### OpenSim Files \nAlternatively, provide `.osim` (model) and `.mot` (motion) file pairs:\n```bash\nopencap-visualizer model.osim motion.mot -o output.mp4\n```\n\n## Dependencies\n\nThe tool automatically detects the best available option:\n\n1. **Deployed Version** (Recommended): `https://opencap-visualizer.onrender.com/`\n - No local setup required\n - Always up-to-date\n - Requires internet connection\n\n2. **Local Development Server**: `http://localhost:3000`\n - Start with `npm run serve` in the Vue.js project\n - Faster for development/testing\n\n3. **Built Files**: Local `dist/index.html`\n - Build with `npm run build` in the Vue.js project\n - Works offline\n\n## Configuration\n\n### Custom Servers\n```bash\n# Use local development server\nopencap-visualizer data.json --dev-server-url http://localhost:3000\n\n# Use custom built files\nopencap-visualizer data.json --vue-app-path /path/to/dist/index.html\n```\n\n### Environment Variables\n```bash\n# Set default development server\nexport OPENCAP_DEV_SERVER=http://localhost:3000\n```\n\n## Troubleshooting\n\n### Browser Installation\nIf you get browser-related errors:\n```bash\nplaywright install chromium\n```\n\n### Connection Issues\n- Check internet connection for deployed version\n- For local development: `npm run serve` in Vue project\n- For built files: `npm run build` in Vue project\n\n### File Format Issues\n- Ensure JSON files contain valid biomechanics data structure\n- For OpenSim files, provide both `.osim` and `.mot` files\n- Check file paths are correct and accessible\n\n### Video Generation Issues\n- Increase timeout: `--timeout 300`\n- Enable verbose mode: `--verbose` or `verbose=True`\n- Try interactive mode: `--interactive`\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nContributions welcome! Please see the source repository for guidelines.\n\n## Support\n\nFor issues and questions:\n- GitHub Issues: [https://github.com/utahmobl/opencap-visualizer/issues](https://github.com/utahmobl/opencap-visualizer/issues)\n- Web App: [https://opencap-visualizer.onrender.com/](https://opencap-visualizer.onrender.com/) \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Tool for creating videos from OpenCap biomechanics data with both CLI and Python API",
"version": "1.1.0",
"project_urls": {
"Bug Reports": "https://github.com/utahmobl/opencap-visualizer/issues",
"Homepage": "https://github.com/utahmobl/opencap-visualizer",
"Source": "https://github.com/utahmobl/opencap-visualizer",
"Web App": "https://opencap-visualizer.onrender.com/"
},
"split_keywords": [
"biomechanics",
" motion-capture",
" visualization",
" video",
" opencap",
" opensim"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a6b81b17cd3f5154f4559f3e2a0a9fa7321611f74f92ddc33775ac29d7d927d5",
"md5": "89383b2c4b3e58adc02d76659933fd01",
"sha256": "71ba57f7cbe289dce17f860c52150b3449faab8fd5a4ea8fa409b485f9b65816"
},
"downloads": -1,
"filename": "opencap_visualizer-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "89383b2c4b3e58adc02d76659933fd01",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 24096,
"upload_time": "2025-07-30T15:37:34",
"upload_time_iso_8601": "2025-07-30T15:37:34.662529Z",
"url": "https://files.pythonhosted.org/packages/a6/b8/1b17cd3f5154f4559f3e2a0a9fa7321611f74f92ddc33775ac29d7d927d5/opencap_visualizer-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "dc5eb56d77365055b147147b5424e88d6d1236a6c3ddc080924fad8c4a008b43",
"md5": "a66fcc78e47d4b419d7ee66d2e3a3b97",
"sha256": "c8bbea523471c0a28c7fdbddec517711e6e795538c756b50b1a6d2d931584435"
},
"downloads": -1,
"filename": "opencap_visualizer-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "a66fcc78e47d4b419d7ee66d2e3a3b97",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 32291,
"upload_time": "2025-07-30T15:37:35",
"upload_time_iso_8601": "2025-07-30T15:37:35.801250Z",
"url": "https://files.pythonhosted.org/packages/dc/5e/b56d77365055b147147b5424e88d6d1236a6c3ddc080924fad8c4a008b43/opencap_visualizer-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-30 15:37:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "utahmobl",
"github_project": "opencap-visualizer",
"github_not_found": true,
"lcname": "opencap-visualizer"
}
JSON
