stegaQR 0.1.0__tar.gz

stegaqr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muntaser Syed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stegaqr-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: stegaQR
+Version: 0.1.0
+Summary: Neural steganographic data embedding in QR codes with switchable channel modes
+Author-email: Muntaser Syed <jemsbhai@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jemsbhai/stegaQR
+Project-URL: Repository, https://github.com/jemsbhai/stegaQR
+Project-URL: Issues, https://github.com/jemsbhai/stegaQR/issues
+Keywords: QR code,steganography,watermarking,error correction,deep learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pillow>=9.0
+Requires-Dist: opencv-python>=4.0
+Requires-Dist: qrcode[pil]>=7.0
+Requires-Dist: scipy>=1.11
+Requires-Dist: torch>=2.0
+Requires-Dist: pyzbar>=0.1.9
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Provides-Extra: analysis
+Requires-Dist: matplotlib>=3.7; extra == "analysis"
+Requires-Dist: seaborn>=0.12; extra == "analysis"
+Requires-Dist: pandas>=2.0; extra == "analysis"
+Requires-Dist: scikit-learn>=1.3; extra == "analysis"
+Dynamic: license-file
+
+# StegaQR
+
+StegaQR embeds a small private payload inside a QR code while preserving the public
+payload for ordinary QR readers. A trained neural decoder recovers the private data.
+
+The package includes a trained hybrid model, repetition and Hamming error correction,
+a command line interface, and a Python API. The bundled model carries 100 coded bits.
+With the default repetition code, it carries up to 4 hidden bytes.
+
+## Install
+
+```powershell
+pip install stegaQR
+```
+
+StegaQR supports Python 3.10 through 3.12. PyTorch is installed as a required
+dependency. Public QR decoding uses `pyzbar`. Some Linux and macOS environments also
+need the native ZBar library supplied by the operating system.
+
+## Command line
+
+Inspect the bundled model:
+
+```powershell
+stegaqr info
+```
+
+Create a QR code with a public URL and a private four byte identifier:
+
+```powershell
+stegaqr encode --public "https://example.com/p" --message "ID42" --out stego.png
+```
+
+Recover both payloads:
+
+```powershell
+stegaqr decode --image stego.png
+```
+
+The generated image includes a quiet zone and nearest neighbor upscaling for reliable
+scanning. Use `--model PATH` to select a different trained checkpoint.
+
+## Python API
+
+```python
+from stegaqr import decode_hidden, encode_hidden
+
+image = encode_hidden("https://example.com", b"ID42", device="cpu")
+public, hidden, metadata = decode_hidden(image, device="cpu")
+
+assert public == "https://example.com"
+assert hidden.rstrip(b"\x00") == b"ID42"
+```
+
+CUDA is used when requested and available. Otherwise the package falls back to CPU.
+
+## Embedding modes
+
+The research implementation supports three trained architectures:
+
+| Mode | Design | Purpose |
+|---|---|---|
+| Segregated | One encoder and decoder per color channel | Channel fault isolation |
+| Cross-channel | Joint RGB encoder and decoder | Flexible signal placement |
+| Hybrid | Joint RGB model with a QR structure mask | Protects finder and control modules |
+
+The bundled model uses the hybrid architecture with a mask-aware spatial bit grid and
+no color calibration branch.
+
+## Reported results
+
+The saved experiment matrix contains five seed comparisons for the three modes,
+capacity studies from 25 to 200 coded bits, error correction comparisons, an
+architecture ablation, and a classical baseline. The physical pilot recovered the
+public and private payloads from all 10 screen to phone photographs after QR detection
+and perspective rectification.
+
+The robust operating point has a visible color tint. It should be described as robust
+data embedding, not invisible steganography. The high PSNR operating point is visually
+subtle but was not validated for physical capture.
+
+See [`experiments/full/RESULTS.md`](experiments/full/RESULTS.md),
+[`LOGBOOK.md`](LOGBOOK.md), and [`paper/main.pdf`](paper/main.pdf) for the recorded
+evidence and limitations.
+
+## Development
+
+```powershell
+git clone https://github.com/jemsbhai/stegaQR.git
+cd stegaQR
+pip install -e ".[dev,analysis]"
+pytest
+```
+
+Train and evaluate a checkpoint:
+
+```powershell
+python scripts/train.py --mode hybrid --mask-aware --no-calibration `
+  --output-dir experiments/run1
+python scripts/evaluate.py --checkpoint experiments/run1/best_model.pt
+python scripts/evaluate_real.py --checkpoint experiments/run1/best_model.pt
+```
+
+The complete experiment matrix is resumable:
+
+```powershell
+python scripts/run_experiments.py
+python scripts/aggregate_results.py
+python scripts/generate_figures.py
+```
+
+## License
+
+MIT

stegaqr-0.1.0/README.md

@@ -0,0 +1,114 @@
+# StegaQR
+
+StegaQR embeds a small private payload inside a QR code while preserving the public
+payload for ordinary QR readers. A trained neural decoder recovers the private data.
+
+The package includes a trained hybrid model, repetition and Hamming error correction,
+a command line interface, and a Python API. The bundled model carries 100 coded bits.
+With the default repetition code, it carries up to 4 hidden bytes.
+
+## Install
+
+```powershell
+pip install stegaQR
+```
+
+StegaQR supports Python 3.10 through 3.12. PyTorch is installed as a required
+dependency. Public QR decoding uses `pyzbar`. Some Linux and macOS environments also
+need the native ZBar library supplied by the operating system.
+
+## Command line
+
+Inspect the bundled model:
+
+```powershell
+stegaqr info
+```
+
+Create a QR code with a public URL and a private four byte identifier:
+
+```powershell
+stegaqr encode --public "https://example.com/p" --message "ID42" --out stego.png
+```
+
+Recover both payloads:
+
+```powershell
+stegaqr decode --image stego.png
+```
+
+The generated image includes a quiet zone and nearest neighbor upscaling for reliable
+scanning. Use `--model PATH` to select a different trained checkpoint.
+
+## Python API
+
+```python
+from stegaqr import decode_hidden, encode_hidden
+
+image = encode_hidden("https://example.com", b"ID42", device="cpu")
+public, hidden, metadata = decode_hidden(image, device="cpu")
+
+assert public == "https://example.com"
+assert hidden.rstrip(b"\x00") == b"ID42"
+```
+
+CUDA is used when requested and available. Otherwise the package falls back to CPU.
+
+## Embedding modes
+
+The research implementation supports three trained architectures:
+
+| Mode | Design | Purpose |
+|---|---|---|
+| Segregated | One encoder and decoder per color channel | Channel fault isolation |
+| Cross-channel | Joint RGB encoder and decoder | Flexible signal placement |
+| Hybrid | Joint RGB model with a QR structure mask | Protects finder and control modules |
+
+The bundled model uses the hybrid architecture with a mask-aware spatial bit grid and
+no color calibration branch.
+
+## Reported results
+
+The saved experiment matrix contains five seed comparisons for the three modes,
+capacity studies from 25 to 200 coded bits, error correction comparisons, an
+architecture ablation, and a classical baseline. The physical pilot recovered the
+public and private payloads from all 10 screen to phone photographs after QR detection
+and perspective rectification.
+
+The robust operating point has a visible color tint. It should be described as robust
+data embedding, not invisible steganography. The high PSNR operating point is visually
+subtle but was not validated for physical capture.
+
+See [`experiments/full/RESULTS.md`](experiments/full/RESULTS.md),
+[`LOGBOOK.md`](LOGBOOK.md), and [`paper/main.pdf`](paper/main.pdf) for the recorded
+evidence and limitations.
+
+## Development
+
+```powershell
+git clone https://github.com/jemsbhai/stegaQR.git
+cd stegaQR
+pip install -e ".[dev,analysis]"
+pytest
+```
+
+Train and evaluate a checkpoint:
+
+```powershell
+python scripts/train.py --mode hybrid --mask-aware --no-calibration `
+  --output-dir experiments/run1
+python scripts/evaluate.py --checkpoint experiments/run1/best_model.pt
+python scripts/evaluate_real.py --checkpoint experiments/run1/best_model.pt
+```
+
+The complete experiment matrix is resumable:
+
+```powershell
+python scripts/run_experiments.py
+python scripts/aggregate_results.py
+python scripts/generate_figures.py
+```
+
+## License
+
+MIT

stegaqr-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stegaQR"
+version = "0.1.0"
+description = "Neural steganographic data embedding in QR codes with switchable channel modes"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Muntaser Syed", email = "jemsbhai@gmail.com"}]
+requires-python = ">=3.10,<3.13"
+keywords = ["QR code", "steganography", "watermarking", "error correction", "deep learning"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Security :: Cryptography",
+]
+dependencies = [
+    "numpy>=1.24",
+    "pillow>=9.0",
+    "opencv-python>=4.0",
+    "qrcode[pil]>=7.0",
+    "scipy>=1.11",
+    "torch>=2.0",
+    "pyzbar>=0.1.9",
+]
+
+[project.urls]
+Homepage = "https://github.com/jemsbhai/stegaQR"
+Repository = "https://github.com/jemsbhai/stegaQR"
+Issues = "https://github.com/jemsbhai/stegaQR/issues"
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.2",
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "mypy>=1.0",
+    "twine>=5.0",
+]
+analysis = [
+    "matplotlib>=3.7",
+    "seaborn>=0.12",
+    "pandas>=2.0",
+    "scikit-learn>=1.3",
+]
+
+[project.scripts]
+stegaqr = "stegaqr.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+stegaqr = ["assets/*.pt"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "gpu: marks tests requiring GPU",
+]
+
+[tool.coverage.run]
+source = ["src/stegaqr"]
+branch = true
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true

stegaqr-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stegaqr-0.1.0/src/stegaQR.egg-info/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: stegaQR
+Version: 0.1.0
+Summary: Neural steganographic data embedding in QR codes with switchable channel modes
+Author-email: Muntaser Syed <jemsbhai@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jemsbhai/stegaQR
+Project-URL: Repository, https://github.com/jemsbhai/stegaQR
+Project-URL: Issues, https://github.com/jemsbhai/stegaQR/issues
+Keywords: QR code,steganography,watermarking,error correction,deep learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pillow>=9.0
+Requires-Dist: opencv-python>=4.0
+Requires-Dist: qrcode[pil]>=7.0
+Requires-Dist: scipy>=1.11
+Requires-Dist: torch>=2.0
+Requires-Dist: pyzbar>=0.1.9
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Provides-Extra: analysis
+Requires-Dist: matplotlib>=3.7; extra == "analysis"
+Requires-Dist: seaborn>=0.12; extra == "analysis"
+Requires-Dist: pandas>=2.0; extra == "analysis"
+Requires-Dist: scikit-learn>=1.3; extra == "analysis"
+Dynamic: license-file
+
+# StegaQR
+
+StegaQR embeds a small private payload inside a QR code while preserving the public
+payload for ordinary QR readers. A trained neural decoder recovers the private data.
+
+The package includes a trained hybrid model, repetition and Hamming error correction,
+a command line interface, and a Python API. The bundled model carries 100 coded bits.
+With the default repetition code, it carries up to 4 hidden bytes.
+
+## Install
+
+```powershell
+pip install stegaQR
+```
+
+StegaQR supports Python 3.10 through 3.12. PyTorch is installed as a required
+dependency. Public QR decoding uses `pyzbar`. Some Linux and macOS environments also
+need the native ZBar library supplied by the operating system.
+
+## Command line
+
+Inspect the bundled model:
+
+```powershell
+stegaqr info
+```
+
+Create a QR code with a public URL and a private four byte identifier:
+
+```powershell
+stegaqr encode --public "https://example.com/p" --message "ID42" --out stego.png
+```
+
+Recover both payloads:
+
+```powershell
+stegaqr decode --image stego.png
+```
+
+The generated image includes a quiet zone and nearest neighbor upscaling for reliable
+scanning. Use `--model PATH` to select a different trained checkpoint.
+
+## Python API
+
+```python
+from stegaqr import decode_hidden, encode_hidden
+
+image = encode_hidden("https://example.com", b"ID42", device="cpu")
+public, hidden, metadata = decode_hidden(image, device="cpu")
+
+assert public == "https://example.com"
+assert hidden.rstrip(b"\x00") == b"ID42"
+```
+
+CUDA is used when requested and available. Otherwise the package falls back to CPU.
+
+## Embedding modes
+
+The research implementation supports three trained architectures:
+
+| Mode | Design | Purpose |
+|---|---|---|
+| Segregated | One encoder and decoder per color channel | Channel fault isolation |
+| Cross-channel | Joint RGB encoder and decoder | Flexible signal placement |
+| Hybrid | Joint RGB model with a QR structure mask | Protects finder and control modules |
+
+The bundled model uses the hybrid architecture with a mask-aware spatial bit grid and
+no color calibration branch.
+
+## Reported results
+
+The saved experiment matrix contains five seed comparisons for the three modes,
+capacity studies from 25 to 200 coded bits, error correction comparisons, an
+architecture ablation, and a classical baseline. The physical pilot recovered the
+public and private payloads from all 10 screen to phone photographs after QR detection
+and perspective rectification.
+
+The robust operating point has a visible color tint. It should be described as robust
+data embedding, not invisible steganography. The high PSNR operating point is visually
+subtle but was not validated for physical capture.
+
+See [`experiments/full/RESULTS.md`](experiments/full/RESULTS.md),
+[`LOGBOOK.md`](LOGBOOK.md), and [`paper/main.pdf`](paper/main.pdf) for the recorded
+evidence and limitations.
+
+## Development
+
+```powershell
+git clone https://github.com/jemsbhai/stegaQR.git
+cd stegaQR
+pip install -e ".[dev,analysis]"
+pytest
+```
+
+Train and evaluate a checkpoint:
+
+```powershell
+python scripts/train.py --mode hybrid --mask-aware --no-calibration `
+  --output-dir experiments/run1
+python scripts/evaluate.py --checkpoint experiments/run1/best_model.pt
+python scripts/evaluate_real.py --checkpoint experiments/run1/best_model.pt
+```
+
+The complete experiment matrix is resumable:
+
+```powershell
+python scripts/run_experiments.py
+python scripts/aggregate_results.py
+python scripts/generate_figures.py
+```
+
+## License
+
+MIT

stegaqr-0.1.0/src/stegaQR.egg-info/SOURCES.txt

@@ -0,0 +1,41 @@
+LICENSE
+README.md
+pyproject.toml
+src/stegaQR.egg-info/PKG-INFO
+src/stegaQR.egg-info/SOURCES.txt
+src/stegaQR.egg-info/dependency_links.txt
+src/stegaQR.egg-info/entry_points.txt
+src/stegaQR.egg-info/requires.txt
+src/stegaQR.egg-info/top_level.txt
+src/stegaqr/__init__.py
+src/stegaqr/cli.py
+src/stegaqr/coding.py
+src/stegaqr/core.py
+src/stegaqr/evaluation.py
+src/stegaqr/realistic_distortion.py
+src/stegaqr/training.py
+src/stegaqr/analysis/__init__.py
+src/stegaqr/assets/stegaqr_default.pt
+src/stegaqr/data/__init__.py
+src/stegaqr/data/synthetic.py
+src/stegaqr/models/__init__.py
+src/stegaqr/models/classical.py
+src/stegaqr/models/decoder.py
+src/stegaqr/models/distortion.py
+src/stegaqr/models/encoder.py
+src/stegaqr/models/losses.py
+src/stegaqr/utils/__init__.py
+src/stegaqr/utils/metrics.py
+src/stegaqr/utils/qr_utils.py
+src/stegaqr/utils/seed.py
+tests/test_classical.py
+tests/test_coding.py
+tests/test_core.py
+tests/test_data.py
+tests/test_losses.py
+tests/test_mask_aware_hybrid.py
+tests/test_metrics.py
+tests/test_models.py
+tests/test_qr_utils.py
+tests/test_realistic_distortion.py
+tests/test_training.py

stegaqr-0.1.0/src/stegaQR.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

stegaqr-0.1.0/src/stegaQR.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+stegaqr = stegaqr.cli:main

stegaqr-0.1.0/src/stegaQR.egg-info/requires.txt

@@ -0,0 +1,20 @@
+numpy>=1.24
+pillow>=9.0
+opencv-python>=4.0
+qrcode[pil]>=7.0
+scipy>=1.11
+torch>=2.0
+pyzbar>=0.1.9
+
+[analysis]
+matplotlib>=3.7
+seaborn>=0.12
+pandas>=2.0
+scikit-learn>=1.3
+
+[dev]
+build>=1.2
+pytest>=7.0
+pytest-cov>=4.0
+mypy>=1.0
+twine>=5.0

stegaqr-0.1.0/src/stegaQR.egg-info/top_level.txt

@@ -0,0 +1 @@
+stegaqr

stegaqr-0.1.0/src/stegaqr/__init__.py

@@ -0,0 +1,22 @@
+"""StegaQR: Neural steganographic data embedding in QR codes."""
+
+__version__ = "0.1.0"
+
+from stegaqr.core import (
+    StegaQREncoder,
+    StegaQRDecoder,
+    encode_hidden,
+    decode_hidden,
+    default_model_path,
+    StegoMode,
+)
+
+__all__ = [
+    "StegaQREncoder",
+    "StegaQRDecoder",
+    "encode_hidden",
+    "decode_hidden",
+    "default_model_path",
+    "StegoMode",
+    "__version__",
+]

stegaqr-0.1.0/src/stegaqr/analysis/__init__.py

@@ -0,0 +1 @@
+"""Statistical analysis scripts for experiment results."""