motionbids 0.1.0__tar.gz

motionbids-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+    
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+    
+    - name: Install dependencies
+      run: |
+        uv pip install --system -e ".[docs]"
+    
+    - name: Build documentation
+      run: |
+        mkdocs build --strict
+    
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: ./site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    
+    steps:
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

motionbids-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,45 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ['3.10', '3.11', '3.12']
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+    
+    - name: Install dependencies
+      run: |
+        uv pip install --system -e ".[dev]"
+    
+    - name: Run tests
+      run: |
+        pytest tests/ -v --cov=motionbids --cov-report=xml --cov-report=term
+    
+    - name: Upload coverage to Codecov
+      if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
+      uses: codecov/codecov-action@v4
+      with:
+        file: ./coverage.xml
+        fail_ci_if_error: false
+        token: ${{ secrets.CODECOV_TOKEN }}

motionbids-0.1.0/.gitignore

@@ -0,0 +1,69 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.hypothesis/
+
+# Distribution
+*.whl
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Example outputs
+example_bids_dataset/
+bids_out/
+bids_root/
+*.tsv
+*.json
+!pyproject.toml
+!.github/**/*.json
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb
+
+# uv
+.uv/
+uv.lock
+
+# JOSS paper draft
+paper.md
+paper.bib

motionbids-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 motionbids contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

motionbids-0.1.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: motionbids
+Version: 0.1.0
+Summary: Lightweight converter for motion data to BIDS format
+Author-email: Julius Welzel <julius.welzel@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: bidsschematools>=0.8.0
+Requires-Dist: dataclasses-json>=0.6.0
+Requires-Dist: numpy>=1.20.0
+Provides-Extra: dev
+Requires-Dist: ipykernel>=6.29.5; extra == 'dev'
+Requires-Dist: pip>=25.3; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.4.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# motionbids
+
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://github.com/JuliusWelzel/motionbids/actions/workflows/tests.yml/badge.svg)](https://github.com/JuliusWelzel/motionbids/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/JuliusWelzel/motionbids/branch/main/graph/badge.svg)](https://codecov.io/gh/JuliusWelzel/motionbids)
+
+A **lightweight** Python package for exporting motion capture data to **BIDS format**.
+
+## Quick Start
+
+```python
+from motionbids import MotionData, Channel, export_bids_motion
+import numpy as np
+
+# Your motion data (1200 timepoints, 32 channels)
+data = np.random.randn(1200, 32)
+
+# Define channels following BIDS schema
+channels = [
+    Channel(
+        channel_name=f"marker{i}_{axis}",
+        channel_component=axis,
+        channel_type="POS",
+        channel_tracked_point=f"marker{i}",
+        channel_units="mm"
+    )
+    for i in range(10)
+    for axis in ['x', 'y', 'z']
+]
+
+# Create BIDS motion object
+motion = MotionData(
+    subject_id="01",
+    task_name="walk",
+    tracksys="optical",
+    sampling_frequency=120.0,
+    tracked_points_count=10,
+    manufacturer="Vicon",
+    data=data,
+    channels=channels
+)
+
+# Export to BIDS format
+export_bids_motion(motion, out_dir="bids_dataset/")
+```
+
+**Output:**
+```
+bids_dataset/
+├── sub-01_task-walk_tracksys-optical_motion.json      # Metadata
+├── sub-01_task-walk_tracksys-optical_motion.tsv       # Time series
+└── sub-01_task-walk_tracksys-optical_channels.tsv     # Channel info
+```
+
+## Installation
+
+**📦 Not on PyPI**: This package is not yet published on PyPI. Install from source:
+
+```bash
+# Clone the repository
+git clone https://github.com/JuliusWelzel/motionbids.git
+cd motionbids
+
+# Install with uv (recommended)
+uv venv  # Create virtual environment
+uv pip install -e .
+
+# Or with pip
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+## Features
+
+✅ **Schema-driven** - Auto-syncs with BIDS specification  
+✅ **Automatic validation** - Catches errors before export  
+✅ **Simple API** - Minimal code needed  
+✅ **Complete export** - JSON, TSV, channels files  
+✅ **Cross-platform** - Tested on Linux, macOS, Windows  
+
+## Documentation
+
+**[Full Documentation](https://juliuswelzel.github.io/motionbids/)**
+
+- [Motivation](https://juliuswelzel.github.io/motionbids/motivation/) - Why BIDS for motion?
+- [Workflow](https://juliuswelzel.github.io/motionbids/workflow/) - Complete workflow guide
+- [Class Reference](https://juliuswelzel.github.io/motionbids/class-reference/) - MotionData API
+- [Schema Fields](https://juliuswelzel.github.io/motionbids/schema-fields/) - All BIDS fields
+
+## Required Fields
+
+```python
+motion = MotionData(
+    subject_id="01",              # Subject identifier
+    task_name="walk",             # Task name
+    tracksys="optical",           # Tracking system (optical/imu/video)
+    sampling_frequency=120.0,     # Sampling rate in Hz
+    tracked_points_count=10,      # Number of markers
+    data=data,                    # NumPy array (rows=time, cols=channels)
+    channels=channels             # List of Channel objects (BIDS-compliant)
+)
+```
+
+### Channel Metadata
+
+Each channel requires BIDS-compliant metadata:
+
+```python
+from motionbids import Channel
+
+channel = Channel(
+    channel_name="marker0_x",           # Channel name
+    channel_component="x",              # x, y, z, quat_x, quat_y, quat_z, quat_w, n/a
+    channel_type="POS",                 # POS, ORNT, VEL, ACCEL, GYRO, MAGN, etc.
+    channel_tracked_point="marker0",    # Label of tracked point
+    channel_units="mm"                  # Units (mm, m, rad, deg, etc.)
+)
+```
+
+## Validation
+
+**Important**: Package validation is for convenience only and is **not officially supported by BIDS**. Always use the official [BIDS Validator](https://bids-standard.github.io/bids-validator/) before sharing your dataset.
+
+```python
+from motionbids import validate_motion_data
+
+# Convenience validation (checks basic requirements)
+validate_motion_data(motion)
+
+# Then validate with official BIDS Validator:
+# https://bids-standard.github.io/bids-validator/
+```
+
+## Complete Workflow
+
+```python
+from motionbids import (
+    MotionData,
+    export_bids_motion,
+    create_bids_directory_structure,
+    export_dataset_description
+)
+
+# 1. Create directory structure
+motion_dir = create_bids_directory_structure(
+    base_dir="my_study",
+    subject_id="01",
+    session_id="01"
+)
+
+# 2. Create dataset description
+export_dataset_description(
+    bids_root="my_study",
+    name="Motion Study",
+    authors=["Your Name"]
+)
+
+# 3. Export motion data
+motion = MotionData(...)
+export_bids_motion(motion, out_dir=motion_dir)
+```
+
+## Supported Systems
+
+Works with any motion tracking technology:
+- **Optical**: Vicon, Optitrack, Qualisys
+- **IMU**: Xsens, APDM, Movella  
+- **Video**: OpenPose, MediaPipe, DeepLabCut
+- **Other**: Custom systems
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/juliuswelzel/motionbids.git
+cd motionbids
+uv pip install -e ".[dev]"
+
+# Run tests
+pytest --cov=motionbids
+```
+
+## Citation
+
+```bibtex
+@software{motionbids,
+  author = {Welzel, Julius},
+  title = {motion2bids: BIDS converter for motion capture data},
+  year = {2025},
+  url = {https://github.com/JuliusWelzel/motionbids}
+}
+```
+
+## Links
+
+- 📖 [Documentation](https://juliuswelzel.github.io/motionbids/)
+- 🐛 [Issues](https://github.com/JuliusWelzel/motionbids/issues)
+- 📜 [BIDS Spec](https://bids-specification.readthedocs.io/)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

motionbids-0.1.0/README.md

@@ -0,0 +1,204 @@
+# motionbids
+
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://github.com/JuliusWelzel/motionbids/actions/workflows/tests.yml/badge.svg)](https://github.com/JuliusWelzel/motionbids/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/JuliusWelzel/motionbids/branch/main/graph/badge.svg)](https://codecov.io/gh/JuliusWelzel/motionbids)
+
+A **lightweight** Python package for exporting motion capture data to **BIDS format**.
+
+## Quick Start
+
+```python
+from motionbids import MotionData, Channel, export_bids_motion
+import numpy as np
+
+# Your motion data (1200 timepoints, 32 channels)
+data = np.random.randn(1200, 32)
+
+# Define channels following BIDS schema
+channels = [
+    Channel(
+        channel_name=f"marker{i}_{axis}",
+        channel_component=axis,
+        channel_type="POS",
+        channel_tracked_point=f"marker{i}",
+        channel_units="mm"
+    )
+    for i in range(10)
+    for axis in ['x', 'y', 'z']
+]
+
+# Create BIDS motion object
+motion = MotionData(
+    subject_id="01",
+    task_name="walk",
+    tracksys="optical",
+    sampling_frequency=120.0,
+    tracked_points_count=10,
+    manufacturer="Vicon",
+    data=data,
+    channels=channels
+)
+
+# Export to BIDS format
+export_bids_motion(motion, out_dir="bids_dataset/")
+```
+
+**Output:**
+```
+bids_dataset/
+├── sub-01_task-walk_tracksys-optical_motion.json      # Metadata
+├── sub-01_task-walk_tracksys-optical_motion.tsv       # Time series
+└── sub-01_task-walk_tracksys-optical_channels.tsv     # Channel info
+```
+
+## Installation
+
+**📦 Not on PyPI**: This package is not yet published on PyPI. Install from source:
+
+```bash
+# Clone the repository
+git clone https://github.com/JuliusWelzel/motionbids.git
+cd motionbids
+
+# Install with uv (recommended)
+uv venv  # Create virtual environment
+uv pip install -e .
+
+# Or with pip
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+## Features
+
+✅ **Schema-driven** - Auto-syncs with BIDS specification  
+✅ **Automatic validation** - Catches errors before export  
+✅ **Simple API** - Minimal code needed  
+✅ **Complete export** - JSON, TSV, channels files  
+✅ **Cross-platform** - Tested on Linux, macOS, Windows  
+
+## Documentation
+
+**[Full Documentation](https://juliuswelzel.github.io/motionbids/)**
+
+- [Motivation](https://juliuswelzel.github.io/motionbids/motivation/) - Why BIDS for motion?
+- [Workflow](https://juliuswelzel.github.io/motionbids/workflow/) - Complete workflow guide
+- [Class Reference](https://juliuswelzel.github.io/motionbids/class-reference/) - MotionData API
+- [Schema Fields](https://juliuswelzel.github.io/motionbids/schema-fields/) - All BIDS fields
+
+## Required Fields
+
+```python
+motion = MotionData(
+    subject_id="01",              # Subject identifier
+    task_name="walk",             # Task name
+    tracksys="optical",           # Tracking system (optical/imu/video)
+    sampling_frequency=120.0,     # Sampling rate in Hz
+    tracked_points_count=10,      # Number of markers
+    data=data,                    # NumPy array (rows=time, cols=channels)
+    channels=channels             # List of Channel objects (BIDS-compliant)
+)
+```
+
+### Channel Metadata
+
+Each channel requires BIDS-compliant metadata:
+
+```python
+from motionbids import Channel
+
+channel = Channel(
+    channel_name="marker0_x",           # Channel name
+    channel_component="x",              # x, y, z, quat_x, quat_y, quat_z, quat_w, n/a
+    channel_type="POS",                 # POS, ORNT, VEL, ACCEL, GYRO, MAGN, etc.
+    channel_tracked_point="marker0",    # Label of tracked point
+    channel_units="mm"                  # Units (mm, m, rad, deg, etc.)
+)
+```
+
+## Validation
+
+**Important**: Package validation is for convenience only and is **not officially supported by BIDS**. Always use the official [BIDS Validator](https://bids-standard.github.io/bids-validator/) before sharing your dataset.
+
+```python
+from motionbids import validate_motion_data
+
+# Convenience validation (checks basic requirements)
+validate_motion_data(motion)
+
+# Then validate with official BIDS Validator:
+# https://bids-standard.github.io/bids-validator/
+```
+
+## Complete Workflow
+
+```python
+from motionbids import (
+    MotionData,
+    export_bids_motion,
+    create_bids_directory_structure,
+    export_dataset_description
+)
+
+# 1. Create directory structure
+motion_dir = create_bids_directory_structure(
+    base_dir="my_study",
+    subject_id="01",
+    session_id="01"
+)
+
+# 2. Create dataset description
+export_dataset_description(
+    bids_root="my_study",
+    name="Motion Study",
+    authors=["Your Name"]
+)
+
+# 3. Export motion data
+motion = MotionData(...)
+export_bids_motion(motion, out_dir=motion_dir)
+```
+
+## Supported Systems
+
+Works with any motion tracking technology:
+- **Optical**: Vicon, Optitrack, Qualisys
+- **IMU**: Xsens, APDM, Movella  
+- **Video**: OpenPose, MediaPipe, DeepLabCut
+- **Other**: Custom systems
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/juliuswelzel/motionbids.git
+cd motionbids
+uv pip install -e ".[dev]"
+
+# Run tests
+pytest --cov=motionbids
+```
+
+## Citation
+
+```bibtex
+@software{motionbids,
+  author = {Welzel, Julius},
+  title = {motion2bids: BIDS converter for motion capture data},
+  year = {2025},
+  url = {https://github.com/JuliusWelzel/motionbids}
+}
+```
+
+## Links
+
+- 📖 [Documentation](https://juliuswelzel.github.io/motionbids/)
+- 🐛 [Issues](https://github.com/JuliusWelzel/motionbids/issues)
+- 📜 [BIDS Spec](https://bids-specification.readthedocs.io/)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.