Initial: DitherForge API endpoints

README.md

@@ -0,0 +1,21 @@
+---
+title: DitherForge API
+emoji: ⬛
+colorFrom: green
+colorTo: gray
+sdk: gradio
+sdk_version: "5.6.0"
+app_file: app.py
+pinned: false
+license: mit
+---
+
+# DitherForge API
+
+API endpoints for generating ASCII/binary/braille art as SVG — designed for GitHub README embeds.
+
+## Endpoints
+
+- `/api/text` — Convert text to styled SVG
+- `/api/avatar` — Convert image URL to ASCII art SVG
+- `/api/banner` — Generate banner from preset parameters

app.py

@@ -0,0 +1,198 @@
+"""DitherForge API — Gradio app with text, avatar, and banner endpoints."""
+
+from __future__ import annotations
+import gradio as gr
+import requests
+from io import BytesIO
+from PIL import Image
+import numpy as np
+
+from effects import binary_effect, ascii_effect, braille_effect, image_to_gray
+from svg_builder import text_to_svg
+
+STYLES = {"binary": binary_effect, "ascii": ascii_effect, "braille": braille_effect}
+ANIMATIONS = ["none", "reveal", "scanline", "flicker", "matrix"]
+
+
+def text_endpoint(
+    text: str,
+    style: str = "ascii",
+    color: str = "#00ff41",
+    bg_color: str = "#0d1117",
+    animation: str = "none",
+    duration: float = 2.0,
+    font_size: int = 14,
+) -> tuple[str, str]:
+    """Convert text string to styled SVG. Returns (html_preview, svg_source)."""
+    effect_fn = STYLES.get(style, ascii_effect)
+
+    lines = text.split("\n") if "\n" in text else [text]
+    max_len = max(len(line) for line in lines)
+    h_pixels = len(lines) * 16
+    w_pixels = max_len * 10
+
+    gray = np.zeros((h_pixels, w_pixels), dtype=np.uint8)
+    for row_idx, line in enumerate(lines):
+        for col_idx, char in enumerate(line):
+            brightness = (ord(char) * 37) % 256
+            y0, y1 = row_idx * 16, (row_idx + 1) * 16
+            x0, x1 = col_idx * 10, (col_idx + 1) * 10
+            if y1 <= h_pixels and x1 <= w_pixels:
+                gray[y0:y1, x0:x1] = brightness
+
+    art_text = effect_fn(gray, cols=max_len)
+    svg = text_to_svg(art_text, font_size, color, bg_color, animation, duration)
+    return svg, svg
+
+
+def avatar_endpoint(
+    image: Image.Image | None = None,
+    image_url: str = "",
+    style: str = "ascii",
+    cols: int = 60,
+    color: str = "#00ff41",
+    bg_color: str = "#0d1117",
+    animation: str = "none",
+    duration: float = 2.0,
+) -> tuple[str, str]:
+    """Convert uploaded image or image URL to ASCII art SVG."""
+    if image is None and image_url:
+        resp = requests.get(image_url, timeout=10)
+        resp.raise_for_status()
+        image = Image.open(BytesIO(resp.content))
+
+    if image is None:
+        svg = text_to_svg("No image provided", 14, color, bg_color)
+        return svg, svg
+
+    gray = image_to_gray(image)
+    effect_fn = STYLES.get(style, ascii_effect)
+    art_text = effect_fn(gray, cols=cols)
+    svg = text_to_svg(art_text, 14, color, bg_color, animation, duration)
+    return svg, svg
+
+
+def banner_endpoint(
+    text: str = "DitherForge",
+    style: str = "binary",
+    cols: int = 40,
+    color: str = "#00ff41",
+    bg_color: str = "#0d1117",
+    animation: str = "reveal",
+    duration: float = 2.0,
+) -> tuple[str, str]:
+    """Generate a banner SVG from parameters."""
+    from PIL import ImageDraw, ImageFont
+
+    font_size = 40
+    char_w = font_size * 0.6
+    img_w = max(int(len(text) * char_w) + 20, 200)
+    img_h = font_size + 20
+
+    img = Image.new("L", (img_w, img_h), 255)
+    draw = ImageDraw.Draw(img)
+    try:
+        font = ImageFont.truetype(
+            "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf", font_size
+        )
+    except (OSError, IOError):
+        font = ImageFont.load_default()
+
+    draw.text((10, 10), text, fill=0, font=font)
+    gray = np.array(img, dtype=np.uint8)
+
+    effect_fn = STYLES.get(style, binary_effect)
+    art_text = effect_fn(gray, cols=cols)
+    svg = text_to_svg(art_text, 12, color, bg_color, animation, duration)
+    return svg, svg
+
+
+# --- Gradio UI ---
+
+with gr.Blocks(title="DitherForge API") as demo:
+    gr.Markdown(
+        "# DitherForge API\n"
+        "Generate ASCII/binary/braille art as SVG for GitHub README embeds."
+    )
+
+    with gr.Tab("Text to SVG"):
+        with gr.Row():
+            with gr.Column():
+                txt_input = gr.Textbox(label="Text", value="Hello World")
+                txt_style = gr.Dropdown(
+                    list(STYLES.keys()), value="ascii", label="Style"
+                )
+                txt_color = gr.ColorPicker(label="Text Color", value="#00ff41")
+                txt_bg = gr.ColorPicker(label="Background", value="#0d1117")
+                txt_anim = gr.Dropdown(ANIMATIONS, value="none", label="Animation")
+                txt_dur = gr.Slider(
+                    0.5, 5.0, value=2.0, step=0.1, label="Duration (s)"
+                )
+                txt_btn = gr.Button("Generate", variant="primary")
+            with gr.Column():
+                txt_out = gr.HTML(label="Preview")
+                txt_svg = gr.Code(label="SVG Source", language="xml")
+
+        txt_btn.click(
+            text_endpoint,
+            [txt_input, txt_style, txt_color, txt_bg, txt_anim, txt_dur],
+            [txt_out, txt_svg],
+            api_name="text",
+        )
+
+    with gr.Tab("Image to ASCII SVG"):
+        with gr.Row():
+            with gr.Column():
+                img_input = gr.Image(type="pil", label="Upload Image")
+                img_url = gr.Textbox(
+                    label="Or paste image URL", placeholder="https://..."
+                )
+                img_style = gr.Dropdown(
+                    list(STYLES.keys()), value="ascii", label="Style"
+                )
+                img_cols = gr.Slider(20, 120, value=60, step=1, label="Columns")
+                img_color = gr.ColorPicker(label="Text Color", value="#00ff41")
+                img_bg = gr.ColorPicker(label="Background", value="#0d1117")
+                img_anim = gr.Dropdown(ANIMATIONS, value="none", label="Animation")
+                img_btn = gr.Button("Generate", variant="primary")
+            with gr.Column():
+                img_out = gr.HTML(label="Preview")
+                img_svg = gr.Code(label="SVG Source", language="xml")
+
+        img_btn.click(
+            avatar_endpoint,
+            [img_input, img_url, img_style, img_cols, img_color, img_bg, img_anim],
+            [img_out, img_svg],
+            api_name="avatar",
+        )
+
+    with gr.Tab("Banner"):
+        with gr.Row():
+            with gr.Column():
+                ban_text = gr.Textbox(label="Banner Text", value="DitherForge")
+                ban_style = gr.Dropdown(
+                    list(STYLES.keys()), value="binary", label="Style"
+                )
+                ban_cols = gr.Slider(20, 100, value=40, step=1, label="Columns")
+                ban_color = gr.ColorPicker(label="Color", value="#00ff41")
+                ban_bg = gr.ColorPicker(label="Background", value="#0d1117")
+                ban_anim = gr.Dropdown(
+                    ANIMATIONS, value="reveal", label="Animation"
+                )
+                ban_dur = gr.Slider(
+                    0.5, 5.0, value=2.0, step=0.1, label="Duration (s)"
+                )
+                ban_btn = gr.Button("Generate", variant="primary")
+            with gr.Column():
+                ban_out = gr.HTML(label="Preview")
+                ban_svg = gr.Code(label="SVG Source", language="xml")
+
+        ban_btn.click(
+            banner_endpoint,
+            [ban_text, ban_style, ban_cols, ban_color, ban_bg, ban_anim, ban_dur],
+            [ban_out, ban_svg],
+            api_name="banner",
+        )
+
+if __name__ == "__main__":
+    demo.launch()

effects.py

@@ -0,0 +1,94 @@
+"""Pure-Python ports of DitherForge core text effects."""
+
+from __future__ import annotations
+import numpy as np
+from PIL import Image
+
+DEFAULT_ASCII_CHARSET = " .:-=+*#%@"
+
+BRAILLE_BASE = 0x2800
+DOT_BITS = [
+    [0x01, 0x08],
+    [0x02, 0x10],
+    [0x04, 0x20],
+    [0x40, 0x80],
+]
+
+
+def image_to_gray(img: Image.Image) -> np.ndarray:
+    """Convert PIL Image to 2D grayscale numpy array (0-255)."""
+    return np.array(img.convert("L"), dtype=np.uint8)
+
+
+def binary_effect(gray: np.ndarray, cols: int = 80, threshold: int = 128) -> str:
+    """Convert grayscale image to binary (0/1) text."""
+    h, w = gray.shape
+    cols = max(1, min(cols, w))
+    block_w = w / cols
+    block_h = block_w * 2
+    rows = max(1, int(h / block_h))
+
+    lines = []
+    for row in range(rows):
+        line = ""
+        for col in range(cols):
+            x0 = int(col * block_w)
+            x1 = int((col + 1) * block_w)
+            y0 = int(row * block_h)
+            y1 = min(int((row + 1) * block_h), h)
+            avg = gray[y0:y1, x0:x1].mean()
+            line += "1" if avg >= threshold else "0"
+        lines.append(line)
+    return "\n".join(lines)
+
+
+def ascii_effect(
+    gray: np.ndarray, cols: int = 80, charset: str = DEFAULT_ASCII_CHARSET
+) -> str:
+    """Convert grayscale image to ASCII art."""
+    h, w = gray.shape
+    cols = max(1, min(cols, w))
+    block_w = w / cols
+    block_h = block_w * 2
+    rows = max(1, int(h / block_h))
+
+    lines = []
+    for row in range(rows):
+        line = ""
+        for col in range(cols):
+            x0 = int(col * block_w)
+            x1 = int((col + 1) * block_w)
+            y0 = int(row * block_h)
+            y1 = min(int((row + 1) * block_h), h)
+            avg = gray[y0:y1, x0:x1].mean()
+            idx = min(int((avg / 255) * len(charset)), len(charset) - 1)
+            line += charset[idx]
+        lines.append(line)
+    return "\n".join(lines)
+
+
+def braille_effect(
+    gray: np.ndarray, cols: int = 40, threshold: int = 128
+) -> str:
+    """Convert grayscale image to Unicode braille art."""
+    h, w = gray.shape
+    cols = max(1, min(cols, w // 2))
+    pix_w = cols * 2
+    scale = w / pix_w
+    pix_h = int(h / scale)
+    rows = max(1, pix_h // 4)
+
+    lines = []
+    for row in range(rows):
+        line = ""
+        for col in range(cols):
+            cp = 0
+            for dy in range(4):
+                for dx in range(2):
+                    sx = min(int((col * 2 + dx) * scale), w - 1)
+                    sy = min(int((row * 4 + dy) * scale), h - 1)
+                    if gray[sy, sx] < threshold:
+                        cp |= DOT_BITS[dy][dx]
+            line += chr(BRAILLE_BASE + cp)
+        lines.append(line)
+    return "\n".join(lines)

palettes.py

@@ -0,0 +1,10 @@
+PALETTES = {
+    "mono": ["#000000", "#ffffff"],
+    "gameboy": ["#0f380f", "#306230", "#8bac0f", "#9bbc0f"],
+    "cga": [
+        "#000000", "#0000aa", "#00aa00", "#00aaaa",
+        "#aa0000", "#aa00aa", "#aa5500", "#aaaaaa",
+        "#555555", "#5555ff", "#55ff55", "#55ffff",
+        "#ff5555", "#ff55ff", "#ffff55", "#ffffff",
+    ],
+}

requirements.txt

@@ -0,0 +1,4 @@
+gradio>=5.0.0
+Pillow>=10.0.0
+requests>=2.31.0
+numpy>=1.24.0

svg_builder.py

@@ -0,0 +1,96 @@
+"""SVG generation with optional CSS animations."""
+
+from __future__ import annotations
+from html import escape
+
+
+def text_to_svg(
+    text: str,
+    font_size: int = 14,
+    color: str = "#00ff41",
+    bg_color: str = "#0d1117",
+    animation: str = "none",
+    duration: float = 2.0,
+) -> str:
+    lines = text.split("\n")
+    cols = max((len(line) for line in lines), default=0)
+    char_w = font_size * 0.6
+    line_h = font_size * 1.2
+    svg_w = int(cols * char_w)
+    svg_h = int(len(lines) * line_h)
+
+    parts = [
+        f'<svg xmlns="http://www.w3.org/2000/svg" width="{svg_w}" height="{svg_h}" '
+        f'viewBox="0 0 {svg_w} {svg_h}">',
+        f'<rect width="100%" height="100%" fill="{bg_color}"/>',
+    ]
+
+    css = _animation_css(animation, duration, len(lines))
+    if css:
+        parts.append(f"<style>{css}</style>")
+
+    use_row_class = animation in ("reveal", "matrix")
+
+    parts.append(
+        f'<text font-family="monospace" font-size="{font_size}" fill="{color}">'
+    )
+
+    for i, line in enumerate(lines):
+        y = (i + 1) * line_h - (line_h - font_size) / 2
+        cls = f' class="row row-{i}"' if use_row_class else ""
+        parts.append(f'<tspan x="0" y="{y:.1f}"{cls}>{escape(line)}</tspan>')
+
+    parts.append("</text>")
+
+    if animation == "scanline":
+        parts.append(
+            f'<rect class="scanline" x="0" y="0" width="100%" '
+            f'height="{line_h}" fill="{color}" opacity="0.15"/>'
+        )
+
+    parts.append("</svg>")
+    return "".join(parts)
+
+
+def _animation_css(animation: str, duration: float, rows: int) -> str:
+    if animation == "reveal":
+        delays = "\n".join(
+            f".row-{i} {{ animation-delay: {i * duration / rows:.2f}s; }}"
+            for i in range(rows)
+        )
+        return (
+            ".row { opacity: 0; animation: reveal 0.15s ease-out forwards; }\n"
+            "@keyframes reveal { from { opacity: 0; } to { opacity: 1; } }\n"
+            + delays
+        )
+
+    if animation == "scanline":
+        return (
+            f"@keyframes scan {{ 0% {{ transform: translateY(-5%); }} "
+            f"100% {{ transform: translateY(105%); }} }}\n"
+            f".scanline {{ animation: scan {duration}s linear infinite; }}"
+        )
+
+    if animation == "flicker":
+        return (
+            "@keyframes flicker { 0%,100% { opacity:1; } "
+            "92% { opacity:1; } 93% { opacity:0.3; } "
+            "94% { opacity:1; } 96% { opacity:0.5; } 97% { opacity:1; } }\n"
+            f"text {{ animation: flicker {duration}s ease-in-out infinite; }}"
+        )
+
+    if animation == "matrix":
+        delays = "\n".join(
+            f".row-{i} {{ animation-delay: {i * duration / rows:.2f}s; }}"
+            for i in range(rows)
+        )
+        return (
+            f".row {{ opacity: 0; animation: matrix {duration * 0.3:.2f}s ease-out forwards; }}\n"
+            "@keyframes matrix { "
+            "0% { opacity:0; transform:translateY(-20px); } "
+            "60% { opacity:1; } "
+            "100% { opacity:1; transform:translateY(0); } }\n"
+            + delays
+        )
+
+    return ""