Metadata-Version: 2.4
Name: stegofractal
Version: 0.1.0
Summary: StegoFractal Python package
Author: Vijay S. Yepuri
License: MIT
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: pillow>=10.0
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# StegoFractal

StegoFractal is a Python package and desktop app that combines:

- Julia-set fractal image generation
- LSB steganography (hiding text in image pixel bits)
- A Tkinter GUI for encode/decode workflows

Given an input message, the app generates a deterministic fractal, embeds the message into the image, and lets you save the result as a PNG. The same app can load a PNG and attempt to recover the hidden text.

## Sample Output

![Sample StegoFractal output](docs/images/Aruna%20Yepuri.png)

## Features

- Deterministic fractal generation seeded from SHA-256 of input text
- Message embedding in the least-significant bit of RGB channels
- Message extraction with delimiter-based termination
- GUI actions for generate, save, load, and decode
- Installable script entry point: `stegofractal`

## How It Works

1. The input text is hashed with SHA-256.
2. Hash bytes are mapped to a complex parameter `c` for a Julia set.
3. A fractal array is generated and colorized with Matplotlib's `magma` colormap.
4. The text plus delimiter is converted to bits and embedded into pixel LSBs.
5. During decode, bits are read back and converted to text until the delimiter is found.

## Requirements

- Python 3.10+
- Runtime dependencies:
	- `numpy`
	- `matplotlib`
	- `pillow`

## Installation

### Option 1: Using uv (recommended)

```bash
uv sync
```

For development tools (pytest, ruff, mypy):

```bash
uv sync --extra dev
```

### Option 2: Using pip

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

For development dependencies:

```bash
pip install -e .[dev]
```

## Usage

### Run as an installed script

```bash
stegofractal
```

### Run as a module

```bash
python -m stegofractal
```

### Run with uv

```bash
uv run stegofractal
```

## GUI Workflow Example

1. Launch the app with `stegofractal`.
2. Enter text (for example: `Vijay`).
3. Click `Generate & Hide`.
4. Click `Save Image` and store the PNG.
5. Later, click `Load & Decode Image` and select that PNG.
6. The app shows the recovered hidden message.

## Python API Examples

### Encode text into a generated fractal image

```python
from stegofractal.cryptal_app import generate_fractal_array, encode_text

message = "Top secret"
fractal = generate_fractal_array(message, width=400, height=400, max_iter=80)
encoded_image = encode_text(message, fractal)
encoded_image.save("secret_fractal.png")
```

### Decode text from an encoded image

```python
from stegofractal.cryptal_app import decode_text

decoded = decode_text("secret_fractal.png")
print(decoded)
```

## Running Tests

```bash
uv run pytest -q
```

## Development Checks

```bash
uv run ruff check .
uv run mypy src
```

## Notes and Limitations

- Hidden message capacity is limited by image size: one bit per channel value.
- Output should be saved as PNG to avoid lossy compression artifacts.
- Decoder returns `None` if no valid delimiter is found.
- This project is for educational/demo steganography and is not cryptographic security.
