RasterLab

RasterLab is a web-based educational playground for pixel-level image processing. All image operations are implemented from scratch in Python, utilizing NumPy for fast vectorized matrix operations, and served via a FastAPI backend. The frontend is built with vanilla HTML, JavaScript, and CSS using Vite.

How It Works

1. The frontend client uploads an image (PNG or JPEG) and sends it alongside selected operation parameters to the FastAPI backend.
2. The backend opens the image using Pillow and splits the RGB channels into three separate NumPy arrays (representing the color values of each pixel).
3. The selected algorithm runs on the NumPy matrices, performing vector operations to modify colors, change geometry, or apply visual filters.
4. The modified matrices are merged back into an RGB image and returned as a PNG stream to the frontend.
5. The frontend displays the result next to the original image and loads the exact Python source code responsible for the transformation.

Directory Structure

RasterLab/
├── README.md
├── backend/
│   ├── main.py                     # FastAPI server and routing
│   ├── requirements.txt            # Python dependencies
│   ├── pipeline/
│   │   └── executor.py             # Maps operations to raster engine functions
│   └── raster_engine/
│       ├── __init__.py
│       ├── color.py                # Color algorithms (grayscale, negative, brightness, etc.)
│       ├── geometry.py             # Geometry algorithms (resizing, rotation, mirroring)
│       ├── helpers.py              # Array-image conversions and matrices utilities
│       └── visual.py               # Visual algorithms (box blur, Sobel edge detection)
└── frontend/
    ├── index.html                  # Core page structure
    ├── package.json                # Frontend package configuration
    ├── src/
    │   ├── main.js                 # Frontend state and API interactions
    │   └── style.css               # Design system and layout styling
    └── public/
        └── calypso-logo.png

Setup and Running Instructions

Backend (Python FastAPI)

The backend runs on Python 3.8+ and requires standard packages (fastapi, uvicorn, numpy, pillow, python-multipart).

1. Navigate to the backend directory:

   cd backend

2. (Optional but recommended) Create and activate a virtual environment:

   • On Windows:

     python -m venv .venv
     .venv\Scripts\activate

   • On macOS/Linux:

     python3 -m venv .venv
     source .venv/bin/activate

3. Install required packages:

   pip install fastapi uvicorn numpy pillow python-multipart typing-inspection

4. Start the FastAPI development server:

   uvicorn main:app --reload --port 8000

   The backend server will run on http://127.0.0.1:8000.

Frontend (Vite)

The frontend requires Node.js 18+ and npm.

1. Navigate to the frontend directory:

   cd frontend

2. Install dependencies:

   npm install

3. Start the Vite development server:

   npm run dev

   The frontend server will run on http://localhost:5173. Open this URL in your web browser.