ocactivity-gen 🏃‍♂️🚴‍♀️🏔️

ocactivity-gen (pyactivity) je Python nástroj a konzolová aplikace pro generování estetických grafických kartogramů a vizualizací sportovních aktivit (běh, chůze, turistika, cyklistika apod.).

Dokáže zpracovat soubory Garmin FIT a GPX, extrahovat z nich metriky (vzdálenost, čas, tempo, rychlost, stoupání, klesání, tep, teplotu, kalorie, kroky) a vykreslit trasy na mapové podklady z OpenStreetMap/Mapy.com společně s výškovým profilem a statistikami.

🛠️ Hlavní funkce

• Podpora Garmin FIT & GPX: Automatické vytěžování telemetrie, GPS trasy a časových dat.
• Inteligentní vyhlazování GPX: Filtr GPS šumu pomocí 2D Kalmanova filtru.
• Rychlá analýza dat: Adaptivní prahy pohybů a hysterézní filtr převýšení pro přesný výpočet stoupání a času v pohybu.
• Generování výškového profilu: Graf nadmořské výšky.
• Flexibilní mapa: Stahování a kešování mapových dlaždic (OSM / Mapy.com) s automatickým přizpůsobením zoomu.
• Dynamic Element Stacking: Zobrazované statistiky se řadí dynamicky bez mezer i v případě, že některé metriky chybí.
• Podpora vlastních fotek: Možnost překrýt mapu vlastní fotografií na pozadí.
• Vodoznak a EXIF metadata: Vkládání loga/vodoznaku a zápis autorství do EXIF/PNG metadat.
• Export obrázku: Možnost exportovat jak do JPG, tak PNG.
• Vlastní aktivita: Možnost vytvoření úplně nové aktivity podle vstupních parametrů.

📦 Instalace

Aplikaci lze nainstalovat přímo z PyPI pomocí pip:

pip install ocactivity-gen

🚀 Použití z příkazové řádky (CLI)

Po instalaci je ihned k dispozici příkaz ocactivity-gen.

Příklady použití:

1. Vygenerování obrázku z FIT souboru:

ocactivity-gen -file "aktivity/zavod.fit" -name "Horský Ultra Běh 🏔️"

2. Vygenerování z GPX souboru s vlastní fotkou na pozadí:

ocactivity-gen -file "vylet.gpx" -bg "moje_fotka.jpg" -name "Víkendová procházka" -out "vylet.png"

3. Ruční vytvoření aktivity bez datového souboru:

ocactivity-gen -type "Běh" -distance 10500 -pace "4:45" -avgspeed "12.6" -ascent 250 -time 2980 -name "Ranní desítka"

4. Přepsání načtených hodnot z FIT souboru a skrytí grafu a teploty:

ocactivity-gen -file "zavod.fit" -nograph -avgtemp -999 -name "Závod bez grafu a teploty"

5. Pokud je potřeba použít jiné mapové podklady, třeba mapy.com. Je dobré změnit i cache, aby se nepoužívali staré podklady.

ocactivity-gen -file "activity.fit" -mapcache "mapy" -mapurl "https://api.mapy.cz/v1/maptiles/basic/256/{z}/{x}/{y}?apikey={YOUR_API_KEY}" -name "Nedělní výlet"

6. Více příkladů v help:

ocactivity-gen -h

🎛️ Přehled parametrů CLI

-file = Cesta k FIT nebo GPX souboru.
-bg = Cesta k fotce na pozadí.
-name = Název nebo popis aktivity.
-type = Typ aktivity (např. "Běh", "Turistika").
-distance = Vzdálenost v metrech.
-avgspeed = Průměrná rychlost v km/h.
-maxspeed = Maximální rychlost v km/h.
-pace = Tempo v min/km (např. "4:30").
-ascent = Stoupání v metrech.
-descent = Klesání v metrech.
-time = Čas v pohybu v sekundách.
-avghr = Průměrná tepová frekvence (bpm).
-maxhr = Maximální tepová frekvence (bpm).
-avgtemp = Průměrná teplota (°C).
-maxtemp = Maximální teplota (°C).
-kcal = Spálené kalorie.
-steps = Počet kroků.
-cdate = Datum a čas spuštění aktivity ve formátu YYYY-MM-DD HH:MM:SS.
-fdate = Datum a čas zastavení aktivity ve formátu YYYY-MM-DD HH:MM:SS.
-elapsedtime = Celkový čas akvitity v sekundách včetně přestávek.
-idletime = Součet času odpočinku nebo čekání v sekundách.
-nograph = Vypne vykreslování grafu převýšení.
-nogpx = Vypne vykreslování trasy na mapě.
-grayscale = Použije na pozadí částečný černobilý efekt, aby se snížila intenzita barev.
-kmstep = Nastaví vzdálenost v kilometrech mezi značkami na trase.
-lang = Nastaví lokalizaci popisků (CZ, EN).
-out = Cílová cesta pro uložení výsledku (.jpg / .png).
-mapurl = URL adresa pro mapové podklady.
-mapcache = Název cache adresáře do kterého se budou ukládat mapové dlaždice.\

🐍 Použití v kódu

Díky modularitě lze knihovnu importovat do vlastního Python skriptu:

A) Podobný styl obrázku, který je generován nativně:

• Vlastní definice metrik (parametry aktivity).

from pyactivity import (
    ActivityGenerator,
    ActivityMetrics,
    ActivityParser,
    ElementStyle,
    ElevationGraphConfig,
    GeneratorConfig,
    GPXConfig,
    WatermarkConfig,
    create_element,
    default_viewport_callback,
    format_activity_type,
)

# Vytvoření metrik
metrics = ActivityMetrics(
    name="Nedělní procházka",
    activity_type="Chůze",
    distance=12345,  # Metry (12.3 km)
    moving_time=7173  # Sekundy (1h 59m 33s)
)

# Sestavení konfigurace a generátoru
config = GeneratorConfig(
    # Vlastní konfigurace GPX trasy
    gpx=GPXConfig(),
    # Vlastní konfigurace vodoznaku
    watermark=WatermarkConfig(),
    # Vykreslení prvků na obrázek
    # Název klíče musí odpovídat atributu v metrice!
    # Pokud je potřeba vlastní element, tak musí začínat prefixem: custom_
    elements={
        # Název aktivity
        "name": ElementStyle(
            is_absolute=True,
            value_pos=(360, 1180),
            value_font_size=40,
            auto_shrink=True,  # Když bude text dlouhý, tak se začne změnšovat
            value_color=(255, 255, 255, 255)
        ),
        # Typ aktivity
        "activity_type": create_element("Aktivita"),
        "custom_activity_type_marker": create_element(
            "🎯",
            is_absolute=True,
            take_pos_y_from_prev_label=True
        ),
        # Vzdálenost
        "distance": create_element("Vzdálenost"),
        "custom_distance_marker": create_element(
            "📍",
            is_absolute=True,
            take_pos_y_from_prev_label=True
        ),
        # Čas pohybu
        "moving_time": create_element("Čas"),
        "custom_moving_time_marker": create_element(
            "🕒",
            is_absolute=True,
            take_pos_y_from_prev_label=True
        )
    }
)

# Uložení obrázku
generator = ActivityGenerator(metrics=metrics, config=config)
generator.save(output_path="vystup.jpg", quality=90)

B) Načtení vlastního FIT souboru:

• Bude použit stejný kód jako v bodě (A), ale musí se udělat několik úprav.

Přidání mapování typu aktivity:

Protože FIT soubor má vlastní typy, tak se hodnoty musí přemapovat na vlastní název.

ACTIVITY_MAPPING: dict[str | None, str] = {
    "walk": "Chůze",
    "walking": "Chůze",
    "run": "Běh",
    "running": "Běh"
}

Načtení FIT souboru a metrik:

Místo vytvoření vlastních metrik je načteme z FIT souboru.

# Načtení FIT souboru a těžba dat
fit_file = Path("activity.fit")
fit_data = ActivityParser().parse_fit(fit_file)

# Získání metrik s možností je přepsat
metrics = fit_data.metrics
metrics.name = "Název aktivity"  # FIT neobsahuje název

Úprava konfigurace - GeneratorConfig:

Do GeneratorConfig přidáme následující konfiguraci.

# Obecná konfigurace
edge_vignette=False,  # Okraje obrázku nebudou mít gradient
elevation_graph_enabled=True,  # Vygeneruje graf převýšení
# Konfigurace GPX trasy
gpx=GPXConfig(
    gpx_enabled=True,  # Povolí vykreslení trasy
    gpx_path=fit_file,  # Může být GPX i FIT
    gpx_points=fit_data.gpx_points,  # Musí být vždy
    gpx_points_with_elev=fit_data.gpx_points_with_elev,  # Pouze pro FIT, protože GPX nemá převýšení
    viewport=default_viewport_callback,  # Pokud se generuje i graf převýšení, tak je dobré použít vlastní viewport
    show_start_finish=True,  # Vykreslí začátek a konec trasy
    show_km_markers=True  # Vykreslí kilometrové značky na trase
),
# Konfigurace grafu převýšení (pouze pro FIT)
elevation=ElevationGraphConfig(
    show_bubble_interval=True,  # Značky každých N-km
    show_bubble_extreme=True  # Značka na nejvyšším a nejnižším místě
),

Úprava activity_type v elements:

Aby bylo možné použít vlastní mapování pro typ aktivity, tak musíme přidat mapper.

"activity_type": create_element(
    "Aktivita",
    formatter=lambda _cfg, _met, val: format_activity_type(val, ACTIVITY_MAPPING),
),

Celkové toho nastavení je mnoho. Tady je použit pouze nutný výčet a nějaké nice-to-have. Často je možné nastavit vše, od pozice, barvy, různých hodnot. Stačí projít konfigurační objekty.