Image2-Web

Web UI to convert images into ASCII or ANSI ("BBS-art") text/grid output. Drop an image, tweak enhancement params, get live-rendered ASCII/ANSI on a canvas, export as PNG or text.

This is a GUI implementation for the image2 CLI tool, built with Next.JS and backed by a FastAPI server.

Examples

Getting Started

Frontend:

pnpm install
pnpm dev

Open http://localhost:3000.

Server (required for actual conversions):

cd server
docker build -t image2-server .
docker run -p 8000:8000 image2-server

Health check: GET http://localhost:8000/health

By default the frontend talks to http://localhost:8000. Set NEXT_PUBLIC_IMAGE2_SERVER_URL to point at a different server (must be in the server's CORS allowlist — see server/main.py).

Build/deploy versions

The footer shows the server's semver and online/offline status. Server version is read from server/VERSION at startup and returned by GET /health as {"status": "ok", "version": "..."}.

Bump server/VERSION on every PR that changes server behavior (see server/CLAUDE.md for semver rules).

Project Structure

app/         Next.js App Router pages (page.tsx, layout.tsx)
components/  React components (DropZone, ControlsBar, OutputCanvas, OutputHeader)
lib/         Conversion logic, canvas rendering, validation, theme, types
server/      FastAPI image-conversion service (Python, separate Docker deploy)
docs/        Deployment notes

Scripts

pnpm dev      # dev server
pnpm build    # production build
pnpm start    # run production build
pnpm lint     # eslint
pnpm test     # vitest

Running Locally via Docker

Image2-Web can run on your own machine via the image2 CLI.

img2 ui          # spin up and open browser
img2 ui --stop   # tear down

When running locally, the server operates in local mode:

• Per-IP rate limiting is disabled
• Output size caps (600×600 / 250,000 cells) are lifted
• The version footer shows local in place of the server origin

Manual Docker Compose

docker compose up -d   # from the image2 repo root

The compose stack uses LOCAL_MODE=true on the server container. The frontend image has http://localhost:8000 baked in as the server URL.

Session Pre-seed URL Params

The --ui flag on img2 ascii/img2 ansi opens the browser with the image pre-loaded via URL params:

http://localhost:3000?session=<id>&mode=ascii&contrast=1.2&brightness=1.1

Supported params: session, mode, contrast, brightness, sharpness, saturate, min_lum, width, palette.

Deployment

Frontend deploys to Vercel. Server deploys separately (Docker, e.g. Fly.io/Railway). See docs/server-deploy.md for full details on env vars and CORS config.