Metadata-Version: 2.4
Name: octxqr
Version: 1.0.1
Summary: A robust tool suite for transferring files via animated QR codes using Zstandard compression and a Flask web receiver.
Author-email: Jiří Vik <mimic2300@gmail.com>
License-Expression: MIT
Project-URL: Repository, https://gitlab.com/OphiteCorp/pytxqr-protocol
Keywords: mimic,ophitecorp,qr-code,animated-qr,file-transfer,zstandard,compression,cli,flask,qr-receiver,data-transmission
Classifier: Framework :: Flask
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
Classifier: Topic :: System :: Archiving :: Compression
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: Czech
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: qrcode>=8.2
Requires-Dist: zstandard>=0.25.0
Requires-Dist: flask>=3.1.3
Requires-Dist: rich>=15.0.0
Dynamic: license-file

<p align="center">
  <img src="https://gitlab.com/OphiteCorp/pytxqr-protocol/-/raw/main/logo.png" alt="logo" width="50%">
</p>

**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.

<p align="center">
  <img src="https://gitlab.com/OphiteCorp/pytxqr-protocol/-/raw/main/donate.png" alt="donate" width="200px">
  <br/>
  <strong>❤️ <a href="https://www.paypal.com/donate/?hosted_button_id=BGUBNNAMCSHFL" target="_blank">Poděkuj | Donate | Buy me a coffee</a> ❤️</strong>
</p>

---

## 💪 Ukázka vygenerovaného GIF souboru s animací
Pokud chceš vědět co je uvnitř, tak použij aplikaci. Na mobilu třeba přes termux nebo webkameru na PC. Příkaz pro čtení: `py octxqr -r` a následně `http://127.0.0.1:5000` ;-)
<p align="center">
  <img src="https://gitlab.com/OphiteCorp/pytxqr-protocol/-/raw/main/output/octxqr_animation.gif" alt="example gif" width="45%">
</p>

---

## 🛠️ 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é:

```bash
pip install octxqr
```

Pokud bude potřeba udělat jen aktualizaci tak:
```bash
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:
```bash
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í:
```bash
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:
```bash
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:
```bash
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:
```bash
# 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:
```bash
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 | 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:
```python
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.
