Metadata-Version: 2.4
Name: pygpmf_oz
Version: 0.3.0
Summary: A module to read GPMF data embedded in GoPro video files. Modernized fork with Python 3.9+ and Windows support.
Home-page: https://github.com/ozand/pygpmf_oz
Author: Alexis Mignon
Author-email: alexis.mignon@gmail.com
Maintainer: ozand
License: MIT
Project-URL: Bug Tracker, https://github.com/ozand/pygpmf_oz/issues
Project-URL: Source, https://github.com/ozand/pygpmf_oz
Project-URL: Documentation, https://github.com/ozand/pygpmf_oz#readme
Keywords: gopro,gpmf,gps,video,metadata
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: gpxpy>=1.5.0
Requires-Dist: ffmpeg-python>=0.2.0
Requires-Dist: geopandas>=0.12.0
Requires-Dist: contextily>=1.3.0
Requires-Dist: matplotlib>=3.5.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# pygpmf-oz

> **Modernized Python library for extracting and analyzing GoPro GPMF (telemetry) data**  
> Supports Python 3.9-3.13 | Windows, Linux, macOS | Active Development 2026

[![PyPI version](https://badge.fury.io/py/pygpmf-oz.svg)](https://pypi.org/project/pygpmf-oz/)
[![Python versions](https://img.shields.io/pypi/pyversions/pygpmf-oz.svg)](https://pypi.org/project/pygpmf-oz/)
[![Documentation Status](https://readthedocs.org/projects/pygpmf-oz/badge/?version=latest)](https://pygpmf-oz.readthedocs.io/en/latest/?badge=latest)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Test Coverage](https://img.shields.io/badge/coverage-79.51%25-brightgreen)](htmlcov/index.html)

---

## 🚀 What's New in v0.2.0

- ✅ **Python 3.9-3.13 support** (including Python 3.13!)
- ✅ **Windows native support** with UTF-8 encoding
- ✅ **Modernized dependencies** (numpy 1.21+, pandas 1.3+, matplotlib 3.5+)
- ✅ **Published on PyPI** - `pip install pygpmf-oz`
- 🔜 **Coming soon**: Hero 11-13 support, GyroFlow integration, ML analytics

📖 **Documentation**: [pygpmf-oz.readthedocs.io](https://pygpmf-oz.readthedocs.io/)  
📋 **Full roadmap**: [DEVELOPMENT_ROADMAP.md](DEVELOPMENT_ROADMAP.md)

---

## 📦 Installation

```bash
pip install pygpmf-oz
```

For development:
```bash
git clone https://github.com/ozand/pygpmf.git
cd pygpmf
pip install -e .
```

---

## 🎯 Quick Start

A python Module to extract GPMF information from GoPro videos.

More information on the format is available on the
[GoPro GitHub page](https://github.com/gopro/gpmf-parser).

The primary aim of this project is to extract GPS tracks and sensor data
from GoPro video files. We use `ffmpeg-python` to extract the GPMF stream from video files.

```python
import gpmf

# Read the binary stream from the file
stream = gpmf.io.extract_gpmf_stream(my_file)

# Extract GPS low level data from the stream
gps_blocks = gpmf.gps.extract_gps_blocks(stream)

# Parse low level data into more usable format
gps_data = list(map(gpmf.gps.parse_gps_block, gps_blocks))
```

We rely on `gpxpy` to easily convert GPS data into GPX segments:  

```python
import gpxpy

gpx = gpxpy.gpx.GPX()
gpx_track = gpxpy.gpx.GPXTrack()
gpx.tracks.append(gpx_track)
gpx_track.segments.append(gpmf.gps.make_pgx_segment(gps_data))

print(gpx.to_xml())
```
```
<?xml version="1.0" encoding="UTF-8"?>
<gpx xmlns="http://www.topografix.com/GPX/1/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd" version="1.1" creator="gpx.py -- https://github.com/tkrajina/gpxpy">
  <trk>
    <trkseg>
      <trkpt lat="44.1287283" lon="5.427715">
        <ele>833.759</ele>
        <time>2020-07-03T12:36:56.940000Z</time>
        <sym>Square</sym>
        <fix>3d</fix>
        <pdop>1.82</pdop>
        <extensions>
          <speed_2d>
            <value>9.221</value>
            <unit>m/s</unit>
          </speed_2d>
          <speed_3d>
            <value>9.25</value>
            <unit>m/s</unit>
          </speed_3d>
        </extensions>
      </trkpt>
      ...
    </trkseg>
  </trk>
</gpx>
```

You can also make an image from you gps track:

```python
import gpmf

# Read the binary stream from the file
stream = gpmf.io.extract_gpmf_stream(my_file)
gpmf.gps_plot.plot_gps_trace_from_stream(stream)
```

![GPS Track Image](./images/GH010215.png)

---

## 🎓 Use Cases

### 🚴 Sports & Fitness
- Extract GPS tracks for training analysis
- Export to GPX for Strava/Garmin compatibility
- Analyze speed, elevation, distance

### 🎬 Video Production
- Sync telemetry overlays with video
- Create data visualizations for dashboards
- Export metadata for After Effects

### 🔬 Research & Analysis
- Scientific motion studies
- Vehicle telemetry analysis
- ML training data extraction

### 🎮 FPV & Action Sports
- Video stabilization with GyroFlow (coming Q2 2026)
- G-force analysis
- Jump/trick detection

---

## 🗺️ Development Roadmap

### Q1 2026: Stabilization & Documentation ⚡
- [x] PyPI publication (v0.2.0)
- [ ] Comprehensive unit tests
- [ ] Sphinx documentation + ReadTheDocs
- [ ] Hero 11/12/13 support

### Q2 2026: GyroFlow Integration 🎯
- [ ] Export gyro data for GyroFlow
- [ ] Video stabilization workflow
- [ ] Python API integration

### Q3 2026: ML Analytics 🤖
- [ ] Automatic activity detection
- [ ] Trip analysis & statistics
- [ ] Interactive dashboards (Plotly)

### Q4 2026: Real-time & Streaming 📡
- [ ] Live telemetry streaming
- [ ] WebSocket API
- [ ] OBS Studio integration

📖 **Full roadmap**: [DEVELOPMENT_ROADMAP.md](DEVELOPMENT_ROADMAP.md)

---

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

**Help needed with**:
- Testing with Hero 11/12/13 files
- Documentation & examples
- Feature development
- Bug reports & feedback

---

## 📚 Documentation

- **Quick Start**: [EXECUTIVE_SUMMARY.md](EXECUTIVE_SUMMARY.md)
- **Full Roadmap**: [DEVELOPMENT_ROADMAP.md](DEVELOPMENT_ROADMAP.md)
- **Russian Documentation**: [README_RU.md](README_RU.md)
- **Windows Installation**: [WINDOWS_INSTALL.md](WINDOWS_INSTALL.md)
- **Changelog**: [CHANGELOG.md](CHANGELOG.md)

---

## 🔗 Related Projects

- [GoPro GPMF Parser](https://github.com/gopro/gpmf-parser) - Official C/C++ parser
- [GyroFlow](https://github.com/gyroflow/gyroflow) - Video stabilization using gyro data
- [Telemetry Extractor](https://goprotelemetryextractor.com/) - Commercial GUI tool

---

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

---

## 🙏 Credits

**Original Author**: Alexis Mignon  
**Maintainer**: ozand  
**Contributors**: See [CHANGELOG.md](CHANGELOG.md)

Based on the unmaintained [alexis-mignon/pygpmf](https://github.com/alexis-mignon/pygpmf) fork.

---

**⭐ If you find this useful, please star the repo!**  
**📦 PyPI**: https://pypi.org/project/pygpmf-oz/  
**🐛 Issues**: https://github.com/ozand/pygpmf/issues
