Imported from nandurstudio/FitGpxEditorPro (AGENTS.md). Install upstream with npx skills add nandurstudio/FitGpxEditorPro. Copyright stays with the author.

FitGpxEditorPro — Konteks Project

Deskripsi

Aplikasi Streamlit untuk memanipulasi file FIT/GPX aktivitas olahraga dengan fitur anti-ban (bypass duplicate check Strava, Garmin Connect, Cause.id).

Struktur Project

FitGpxEditorPro/
├── run.py                          # Entry point: streamlit run run.py
├── src/fitgpxeditor/
│   ├── app.py                      # Streamlit main loop (modular)
│   ├── config.py                   # Konstanta, device presets, paths
│   ├── core/
│   │   ├── geo.py                  # Haversine, extend_coords, offset, jitter
│   │   ├── gpx_parser.py           # parse_gpx_coords(bytes), parse_gpx_full(path)
│   │   ├── fit_parser.py           # parse_fit_coords(fit_file)
│   │   ├── fit_builder.py          # build_fit_file(...) → bytes
│   │   ├── sync_server.py          # HTTP server localhost:8505 untuk iframe sync
│   │   └── anti_ban.py             # HR/cadence/speed jitter generators
│   ├── generators/
│   │   ├── smart_randomizer.py     # randomize_by_time_mode()
│   │   ├── heart_rate.py           # generate_heart_rates()
│   │   ├── cadence.py              # generate_cadences()
│   │   └── splits.py               # generate_splits_html()
│   └── ui/
│       ├── map_widget.py           # render_preview_map(), render_edit_map()
│       └── strava_mockup.py        # render_strava_mockup() → HTML string
├── resources/                      # Template Jolly_Roger.fit & .gpx
├── scripts/                        # CLI utilities (import dari core)
│   ├── parse_gpx.py
│   ├── modify_fit.py
│   └── modify_gpx.py
├── tests/                          # Pytest test stubs
├── .gitignore
├── pyproject.toml
├── pytest.ini
├── requirements.txt
└── AGENTS.md                       # ← file ini

Tech Stack

• Frontend: Streamlit, Leaflet.js, Leaflet Routing Machine, OSRM
• Backend: Python 3.10+, fit-tool, xml.etree.ElementTree
• Dev: pytest, ruff

Arsitektur Kunci

1. Komunikasi iframe ↔ Streamlit: HTTP server lokal (127.0.0.1:8505) untuk sync real-time antara Leaflet map (iframe) dan parent Streamlit
2. Anti-Ban Engine: GPS jitter (±1-2m), speed jitter (sinusoidal + noise), HR/cadence curve (warm-up → steady state), device spoofing (7 preset), coordinate offset (±30m), route reversal
3. FIT Building: Baca template → copy non-record messages → update metadata → generate record messages dengan extended coordinates + jitter
4. Smart Auto-Generator: Randomisasi parameter berdasarkan mode waktu (Pagi/Siang/Sore/Malam)

Konvensi Kode

• Bahasa: Python, UI dalam Bahasa Indonesia
• Import: Relative import antar modul dalam package (from ..core.geo import ...)
• State Management: st.session_state untuk semua UI state
• CSS/HTML: Inline styles dalam f-string untuk komponen kustom
• Testing: pytest, test files di tests/

Perintah Penting

streamlit run run.py                          # Jalankan app
pytest                                        # Run tests
python scripts/parse_gpx.py                   # Parse & statistik GPX
python scripts/modify_gpx.py                  # Edit GPX CLI
python scripts/modify_fit.py                  # Rebuild FIT CLI

Key Files Reference

• src/fitgpxeditor/config.py — Semua device presets, path, konstanta di satu tempat
• src/fitgpxeditor/core/geo.py — extend_coords_to_distance() adalah core logic perpanjangan rute
• src/fitgpxeditor/core/fit_builder.py — build_fit_file() adalah function terpanjang & terpenting
• src/fitgpxeditor/app.py — Entry point, sesuaikan jika Streamlit page config berubah

Catatan

• Template Jolly_Roger.fit adalah file FIT sample yang digunakan sebagai template untuk semua output
• Koordinat default: -6.287919, 107.174775 (Cikarang, Bekasi)
• resources/__init__.py ada untuk make it a package (opsional)