octxqr 1.0.0

octxqr je optimalizovaná a vysoce robustní verze protokolu TXQR, která umožňuje přenášet libovolné soubory jako sekvenci animovaných QR kódů (GIF) a následně je v reálném čase skrze kameru rekonstruovat a sestavit zpět. Obsahuje moderní webový přijímač postavený na frameworku Flask.

Aplikace je navržena pro bezchybný přenos dat z počítače (monitoru) do mobilního zařízení (testováno na telefonu s Android 15) pomocí optické cesty přes kameru. Zajišťuje jednotnou velikost a objem dat každého QR kódu, což zabraňuje nežádoucímu přezaostřování a skákání optiky.

❤️ Poděkuj | Donate | Buy me a coffee ❤️

---

💪 Ukázka vygenerovaného GIF souboru s animací

Pokud chcete vědět, co je uvnitř, tak použijde aplikaci :)

---

🛠️ Klíčové vlastnosti a architektura

• Maximální kompresní poměr: Integrovaná komprese Zstandard (level 22) radikálně redukuje objem přenášených dat a minimalizuje celkový počet snímků v animaci.

• Uniformní datové bloky a stabilní matice: Pevná velikost chunku v kombinaci se zarovnáním mezerami (ljust) zajišťuje konstantní délku payloadu a identickou verzi QR matice pro všechny snímky, což zcela eliminujte nežádoucí přezaostřování a "skákání" optiky kamery.

• Bezpečná správa hlavičky: Integrovaná 2-bajtová big-endian struktura pro délku vnitřní hlavičky spolehlivě odděluje kontrolní součet CRC32 a URL-enkódovaný název souboru od samotných binárních dat.

• Plná podpora Unicode a diakritiky: Spolehlivý přenos názvů souborů obsahujících unicode znaky, mezery a speciální symboly s ochranou proti Path Traversal útokům (sanitizace cest).

• Thread-Safe relace přenosu: Správa stavu přijímače pomocí vláknově bezpečné komponenty (TransferSession chráněná přes threading.Lock) pro bezchybný souběžný příjem dat.

• Dvoustranná flexibilita (CLI & API): Možnost pohodlného ovládání přes konzolové příkazy nebo přímé programové integrace do vlastních Python skriptů.

• Chytrý webový přijímač: Flask server s vypnutou mezipamětí statických souborů, maskováním serverových verzí, přehráním zvukového signálu (beep) po dokončení přenosu a detailními statistikami průběhu.

• Estetické konzolové logování: Vlastní handler CleanRichHandler postavený na knihovně rich poskytuje přehledný, barevně odlišený výstup bez rušivých časových razítek a systémových cest.

• Nativní komprese: Automatická komprese vstupních souborů pro zmenšení počtu snímků v animaci.

• Flexibilní nastavení QR kódů: Možnost úpravy velikosti chunků (-c), chybové korekce (-e), velikosti boxů (-box-size) a okrajů (-border).

• Vlastní zprávy v hlavičce: Přidání doprovodného textu viditelného při skenování (-m).

• Integrovaný webový přijímač: Flask server s webovým rozhraním pro plynulé skenování kamerou a automatické ukládání souborů (-r).

• Integrovaný automatický otevření: Po úspěšném dokončení čtení QR kódu a uložení na disk soubor otevře. Pro čtečku použít parametr -run.

---

📦 Instalace

Je potřeba mít verzi Python 3.14 a vyšší!

Aplikaci lze nainstalovat přímo z PyPI přes pip. Stačí stáhnou Python install manager a poté:

pip install octxqr

Pokud bude potřeba udělat jen aktualizaci tak:

pip install --upgrade --no-cache-dir octxqr

Parametr --no-cache-dir je tam proto, aby pip nepodstrčil starší verzi z disku, ale skutečně se stáhla poslední.

---

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

Po instalaci je ihned k dispozici příkaz octxqr.

Příklady použití: 1) Základní vygenerování sekvence QR kódů do animovaného GIFu:

octxqr -f "private.cer" -o "animace.gif"

• Pokud bude potřeba zadat vlastní zprávu, která se má vložit do QR kódů, použijte -m jako -m "moje data".
• Pokud bude problém se čtením QR kódu, tak buď zvýšit prodlevu -d 200 nebo snížit hustotu dat -c 200. Případně lze nastavit jinou opravu chyb -e Q (zvětší QR kód).

2) Generování s vlastní zprávou zobrazenou na displeji přijímače při skenování:

octxqr -f "dokument.pdf" -m "Důvěrný data"

3) Generování bez komprese, s menšími chunky, vyšší snímkovou frekvencí a vlastní cestou:

octxqr -f "data.zip" -c 300 -d 100 -nc -o "C:/outputs/sequence.gif"

4) Spuštění webového serveru (přijímače) na portu 5000 pro příjem dat skrze kameru:

octxqr -r -p 5000 -o "C:/prijate_soubory/"

• Pokud se má soubor po dokončení automaticky spustit, tak přidat parametr -run.

5) Použití vlastního kompatibilního prefixu hlavičky pro ověření relace:

# Generování s vlastním prefixem
octxqr -f "tajne.dat" -pp "9999" -o "tajne.gif"

# Spuštění přijímače se stejným prefixem
octxqr -r -p 5000 -pp "9999"

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

octxqr -h

---

🎛️ Přehled parametrů CLI

Zde jsou parametry. Pro více parametrů je potřeba se podívat do -h help.

Sdílené parametry pro generátor i čtečku

Parametr	Popis
-o, -out	Cesta k výstupnímu souboru (GIF) nebo cílovému adresáři pro ukládání dat.
-pp, -payload-prefix	Unikátní prefix hlavičky pro ověření kompatibility mezi generátorem a čtečkou.

Parametry generátoru

Parametr	Popis
-f, -file	Cesta ke vstupnímu souboru pro vytvoření GIF animace.
-m, -msg	Vlastní zpráva předávaná v hlavičce zobrazená při skenování.
-c, -chunk-size	Velikost datového bloku (v bajtech) uloženého v jednom QR kódu.
-e, -error-correction	Úroveň korekce chyb QR kódu (L, M, Q, H).
-d, -delay	Prodleva mezi snímky v GIFu v milisekundách (ovlivňuje FPS).
-border	Velikost bílého okraje kolem každého QR kódu.
-box-size	Velikost jednoho modulu (pixelu) vykreslovaného QR kódu.
-nc, -no-compress	Vypne nativní Zstandard kompresi (vhodné pro již komprimované soubory).

Parametry čtečky

Parametr	Pouze Generátor/Receiver	Popis
-r, -receive	Spustí HTTP server pro příjem a rekonstrukci souborů přes kameru.
-p, -port	Síťový port, na kterém bude webový server naslouchat.
-run	Automaticky spustí kompletně naskenovaný soubor.

---

🐍 Použití v kódu (pro vývojáře)

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

from pathlib import Path
from octxqr import (
    OCTXQRGenerator,
    OCTXQRGeneratorConfig,
    OCTXQRReceiver,
    OCTXQRReceiverConfig,
)

# 1. Generování animované QR sekvence

gen_config = OCTXQRGeneratorConfig(
    input_file=Path("dokumentace.pdf"),
    output_path="out/animace.gif",
    header_message="Interní projekt",
    chunk_size=600,
    delay_ms=120,
    use_compress=True,
    error_correction="M",
    payload_prefix="1337"
)

generator = OCTXQRGenerator(gen_config)
generator.run()

# 2. Spuštění přijímače (Flask serveru)

rec_config = OCTXQRReceiverConfig(
    output_path="prijate_soubory/",
    host="0.0.0.0",
    port=5000,
    payload_prefix="1337",
    auto_open=False,
)

receiver = OCTXQRReceiver(rec_config)
receiver.run()

---

🛡️ Bezpečnost a robustnost

Aplikace striktně uplatňuje zásady defenzivního programování, detailní ošetření výjimek s informativními chybovými hlášeními, obranu proti neplatným vstupům a automatickou verifikaci celistvosti přenesených dat porovnáním CRC32 kontrolních součetů na straně přijímače.