Refactor to Python Gradio app

.gitignore

@@ -7,3 +7,6 @@ node_modules/
 *.png
 *.webp
 !app/icon.svg
+__pycache__/
+*.pyc
+.gradio/

README.md

@@ -0,0 +1,29 @@
+# Grid2Frame
+
+Extract individual images from a grid or contact-sheet style image.
+
+Grid2Frame is now a Python-only Gradio app, which makes it easy to run on free Python-friendly hosts such as Hugging Face Spaces. It uses OpenCV to detect full grid separator lines, previews the detected frame boxes, shows the extracted frames, and creates a ZIP download.
+
+## Run Locally
+
+```bash
+python3 -m venv .venv
+.venv/bin/python3 -m pip install -r requirements.txt
+.venv/bin/python3 app.py
+```
+
+Then open the local URL printed by Gradio.
+
+## Deploy Free
+
+Recommended target: Hugging Face Spaces.
+
+1. Create a new Space.
+2. Select `Gradio` as the SDK.
+3. Push this repo.
+
+Hugging Face Spaces will install `requirements.txt` and run `app.py`.
+
+## Next.js Version
+
+The previous Next.js implementation is preserved on the `nextjs` branch.

app.py

@@ -0,0 +1,312 @@
+from __future__ import annotations
+
+import shutil
+import tempfile
+import zipfile
+from pathlib import Path
+
+import cv2
+import gradio as gr
+
+from grid2frame.extractor import annotate_regions, detect_grid, extract_frames, read_image
+
+WORK_ROOT = Path(tempfile.gettempdir()) / "grid2frame"
+WORK_ROOT.mkdir(parents=True, exist_ok=True)
+
+
+def process_image(
+    image_path: str | None,
+    sensitivity: int,
+    min_frame_size: int,
+    separator_mode: str,
+    output_format: str,
+):
+    if not image_path:
+        return None, "<span>No image loaded</span>", [], None
+
+    run_dir = Path(tempfile.mkdtemp(prefix="run-", dir=WORK_ROOT))
+    image = read_image(image_path)
+    result = detect_grid(
+        image,
+        min_frame_size=min_frame_size,
+        sensitivity=sensitivity,
+        separator_mode=separator_mode.lower(),
+    )
+
+    if not result.regions:
+        return None, "<span>No frames detected</span>", [], None
+
+    annotated = annotate_regions(image, result.regions)
+    annotated_path = run_dir / "detected-grid.jpg"
+    cv2.imwrite(str(annotated_path), annotated, [cv2.IMWRITE_JPEG_QUALITY, 92])
+
+    extension = extension_for_format(output_format)
+    image_params = encoding_params(extension)
+    frame_paths: list[str] = []
+    zip_path = run_dir / "grid2frame-frames.zip"
+
+    with zipfile.ZipFile(zip_path, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+        for index, (region, frame) in enumerate(
+            zip(result.regions, extract_frames(image, result.regions)),
+            start=1,
+        ):
+            frame_name = (
+                f"frame-{index:03d}-r{region.row + 1:02d}-c{region.col + 1:02d}"
+                f".{extension}"
+            )
+            frame_path = run_dir / frame_name
+            cv2.imwrite(str(frame_path), frame, image_params)
+            frame_paths.append(str(frame_path))
+            archive.write(frame_path, arcname=frame_name)
+
+    status = (
+        f"<span>{len(result.regions)} frames extracted from "
+        f"{result.columns} columns x {result.rows} rows</span>"
+    )
+    return str(annotated_path), status, frame_paths, str(zip_path)
+
+
+def clear_outputs():
+    return None, "<span>No image loaded</span>", [], None
+
+
+def extension_for_format(output_format: str) -> str:
+    if output_format == "PNG":
+        return "png"
+    if output_format == "WebP":
+        return "webp"
+    return "jpg"
+
+
+def encoding_params(extension: str) -> list[int]:
+    if extension == "jpg":
+        return [cv2.IMWRITE_JPEG_QUALITY, 94]
+    if extension == "webp":
+        return [cv2.IMWRITE_WEBP_QUALITY, 94]
+    return []
+
+
+def build_app() -> gr.Blocks:
+    with gr.Blocks(
+        title="Grid2Frame",
+    ) as demo:
+        gr.HTML(
+            """
+            <section class="hero-band">
+              <div>
+                <p class="eyebrow">Grid2Frame</p>
+                <h1>Extract every frame from a grid image.</h1>
+              </div>
+            </section>
+            """
+        )
+
+        with gr.Row(elem_classes="workspace"):
+            with gr.Column(scale=8, elem_classes="preview-panel"):
+                input_image = gr.Image(
+                    label="Upload grid",
+                    sources=["upload"],
+                    type="filepath",
+                    height=420,
+                    elem_classes="upload-box",
+                )
+                annotated_image = gr.Image(
+                    label="Detected frames",
+                    type="filepath",
+                    height=420,
+                    elem_classes="detected-box",
+                )
+
+            with gr.Column(scale=3, elem_classes="control-panel"):
+                status = gr.HTML("<span>No image loaded</span>", elem_classes="status-line")
+                sensitivity = gr.Slider(
+                    minimum=0,
+                    maximum=100,
+                    value=58,
+                    step=1,
+                    label="Sensitivity",
+                )
+                min_frame_size = gr.Slider(
+                    minimum=16,
+                    maximum=600,
+                    value=80,
+                    step=4,
+                    label="Minimum frame",
+                )
+                separator_mode = gr.Radio(
+                    ["Auto", "Dark", "Light"],
+                    value="Auto",
+                    label="Separator",
+                )
+                output_format = gr.Radio(
+                    ["JPG", "PNG", "WebP"],
+                    value="JPG",
+                    label="Output",
+                )
+                extract_button = gr.Button("Extract", variant="primary")
+                zip_file = gr.File(label="Download ZIP", elem_classes="zip-download")
+
+        with gr.Column(elem_classes="frames-section"):
+            gr.HTML("<div class='section-head'><h2>Extracted frames</h2></div>")
+            gallery = gr.Gallery(
+                label="",
+                columns=6,
+                rows=2,
+                height=520,
+                object_fit="cover",
+                elem_classes="frame-gallery",
+            )
+
+        extract_inputs = [
+            input_image,
+            sensitivity,
+            min_frame_size,
+            separator_mode,
+            output_format,
+        ]
+        extract_outputs = [annotated_image, status, gallery, zip_file]
+
+        input_image.upload(process_image, extract_inputs, extract_outputs)
+        extract_button.click(process_image, extract_inputs, extract_outputs)
+        input_image.clear(clear_outputs, None, extract_outputs)
+
+    return demo
+
+
+def launch_app() -> None:
+    build_app().launch(
+        css=APP_CSS,
+        theme=gr.themes.Base(
+            primary_hue="teal",
+            neutral_hue="slate",
+            font=["Arial", "Helvetica", "sans-serif"],
+        ),
+    )
+
+
+APP_CSS = """
+:root {
+  --background: #f6f3ec;
+  --surface: #ffffff;
+  --surface-muted: #e9edf0;
+  --ink: #171c1f;
+  --muted: #66727a;
+  --line: #c8d0d4;
+  --accent: #0f766e;
+  --accent-strong: #0b4f49;
+}
+
+body,
+.gradio-container {
+  background: linear-gradient(180deg, #f6f3ec 0, #eef3f1 42%, #f6f3ec 100%) !important;
+  color: var(--ink) !important;
+}
+
+.gradio-container {
+  max-width: none !important;
+  padding: 28px !important;
+}
+
+.hero-band {
+  align-items: end;
+  display: flex;
+  justify-content: space-between;
+  margin: 0 auto 24px;
+  max-width: 1440px;
+}
+
+.eyebrow {
+  color: var(--accent-strong);
+  font-size: 0.76rem;
+  font-weight: 800;
+  letter-spacing: 0.12em;
+  margin: 0 0 8px;
+  text-transform: uppercase;
+}
+
+h1 {
+  color: var(--ink);
+  font-size: clamp(2rem, 4vw, 4.6rem);
+  line-height: 0.98;
+  margin: 0;
+  max-width: 820px;
+}
+
+.workspace {
+  gap: 18px !important;
+  margin: 0 auto !important;
+  max-width: 1440px !important;
+}
+
+.preview-panel {
+  background: #111619;
+  border: 1px solid rgba(23, 28, 31, 0.18);
+  border-radius: 8px;
+  box-shadow: 0 22px 50px rgba(23, 28, 31, 0.12);
+  min-height: 58vh;
+  overflow: hidden;
+  padding: 18px;
+}
+
+.preview-panel .block,
+.control-panel .block {
+  border-radius: 8px !important;
+}
+
+.upload-box,
+.detected-box {
+  background: #111619 !important;
+  border-color: rgba(255, 255, 255, 0.08) !important;
+}
+
+.control-panel {
+  background: var(--surface);
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  box-shadow: 0 22px 50px rgba(23, 28, 31, 0.12);
+  gap: 16px;
+  padding: 18px;
+}
+
+.status-line {
+  color: var(--muted);
+  font-weight: 700;
+}
+
+button.primary,
+.primary {
+  background: var(--accent) !important;
+  border-color: var(--accent) !important;
+  color: #ffffff !important;
+}
+
+.zip-download {
+  background: #d7efea !important;
+}
+
+.frames-section {
+  margin: 28px auto 0 !important;
+  max-width: 1440px !important;
+}
+
+.section-head h2 {
+  color: var(--ink);
+  font-size: 1.35rem;
+  margin: 0 0 14px;
+}
+
+.frame-gallery {
+  background: transparent !important;
+  border: 0 !important;
+}
+
+@media (max-width: 980px) {
+  .gradio-container {
+    padding: 18px !important;
+  }
+}
+"""
+
+
+if __name__ == "__main__":
+    launch_app()

app/api/extract/route.ts

@@ -1,123 +0,0 @@
-import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { mkdir, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import path from "node:path";
-
-export const runtime = "nodejs";
-
-type PythonResult = {
-  regions: Array<{
-    id: string;
-    row: number;
-    col: number;
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-  }>;
-  rows: number;
-  columns: number;
-  width: number;
-  height: number;
-};
-
-export async function POST(request: Request) {
-  const formData = await request.formData();
-  const file = formData.get("image");
-
-  if (!(file instanceof File)) {
-    return Response.json({ error: "Missing image file." }, { status: 400 });
-  }
-
-  const tempDirectory = path.join(
-    tmpdir(),
-    `grid2frame-${Date.now()}-${Math.random().toString(16).slice(2)}`,
-  );
-  const tempFile = path.join(tempDirectory, sanitizeFileName(file.name));
-
-  try {
-    await mkdir(tempDirectory, { recursive: true });
-    await writeFile(tempFile, Buffer.from(await file.arrayBuffer()));
-
-    const result = await runPythonDetector(tempFile, {
-      minFrameSize: String(formData.get("minFrameSize") ?? "80"),
-      separatorMode: String(formData.get("separatorMode") ?? "auto"),
-      sensitivity: String(formData.get("sensitivity") ?? "58"),
-    });
-
-    return Response.json({ ...result, engine: "python-opencv" });
-  } catch (error) {
-    return Response.json(
-      { error: error instanceof Error ? error.message : "Extraction failed." },
-      { status: 500 },
-    );
-  } finally {
-    await rm(tempDirectory, { recursive: true, force: true });
-  }
-}
-
-function runPythonDetector(
-  imagePath: string,
-  options: {
-    minFrameSize: string;
-    separatorMode: string;
-    sensitivity: string;
-  },
-) {
-  return new Promise<PythonResult>((resolve, reject) => {
-    const projectRoot = process.cwd();
-    const virtualEnvPython = [
-      projectRoot,
-      ".venv",
-      "bin",
-      "python3",
-    ].join(path.sep);
-    const pythonPath =
-      process.env.PYTHON_BIN ??
-      (existsSync(virtualEnvPython) ? virtualEnvPython : "python3");
-    const scriptPath = path.join(projectRoot, "scripts", "extract_grid.py");
-    const child = spawn(
-      pythonPath,
-      [
-        scriptPath,
-        imagePath,
-        "--min-frame-size",
-        options.minFrameSize,
-        "--separator-mode",
-        options.separatorMode,
-        "--sensitivity",
-        options.sensitivity,
-      ],
-      { cwd: projectRoot },
-    );
-
-    let stdout = "";
-    let stderr = "";
-
-    child.stdout.on("data", (chunk) => {
-      stdout += chunk.toString();
-    });
-    child.stderr.on("data", (chunk) => {
-      stderr += chunk.toString();
-    });
-    child.on("error", (error) => reject(error));
-    child.on("close", (code) => {
-      if (code !== 0) {
-        reject(new Error(stderr.trim() || `Python exited with code ${code}.`));
-        return;
-      }
-
-      try {
-        resolve(JSON.parse(stdout) as PythonResult);
-      } catch {
-        reject(new Error("Python returned invalid JSON."));
-      }
-    });
-  });
-}
-
-function sanitizeFileName(fileName: string) {
-  const normalized = fileName.replace(/[^\w.-]+/g, "-");
-  return normalized || "upload";
-}

app/globals.css

@@ -1,500 +0,0 @@
-:root {
-  --background: #f6f3ec;
-  --surface: #ffffff;
-  --surface-muted: #e9edf0;
-  --ink: #171c1f;
-  --muted: #66727a;
-  --line: #c8d0d4;
-  --accent: #0f766e;
-  --accent-strong: #0b4f49;
-  --accent-soft: #d7efea;
-  --warning: #9b2c2c;
-  --shadow: 0 22px 50px rgba(23, 28, 31, 0.12);
-}
-
-* {
-  box-sizing: border-box;
-}
-
-html {
-  background: var(--background);
-}
-
-body {
-  margin: 0;
-  color: var(--ink);
-  background:
-    linear-gradient(180deg, #f6f3ec 0, #eef3f1 42%, #f6f3ec 100%);
-  font-family:
-    Arial,
-    Helvetica,
-    sans-serif;
-  letter-spacing: 0;
-}
-
-button,
-input {
-  font: inherit;
-}
-
-button {
-  cursor: pointer;
-}
-
-button:disabled {
-  cursor: not-allowed;
-  opacity: 0.55;
-}
-
-svg {
-  display: block;
-  height: 1.1rem;
-  width: 1.1rem;
-  fill: currentColor;
-}
-
-.app-shell {
-  min-height: 100vh;
-  padding: 28px;
-}
-
-.hero-band {
-  align-items: end;
-  display: flex;
-  gap: 24px;
-  justify-content: space-between;
-  margin: 0 auto 24px;
-  max-width: 1440px;
-}
-
-.eyebrow {
-  color: var(--accent-strong);
-  font-size: 0.76rem;
-  font-weight: 800;
-  letter-spacing: 0.12em;
-  margin: 0 0 8px;
-  text-transform: uppercase;
-}
-
-h1,
-h2,
-p {
-  margin: 0;
-}
-
-h1 {
-  font-size: clamp(2rem, 4vw, 4.6rem);
-  line-height: 0.98;
-  max-width: 820px;
-}
-
-h2 {
-  font-size: 1.35rem;
-}
-
-.actions {
-  align-items: center;
-  display: flex;
-  flex-wrap: wrap;
-  gap: 10px;
-  justify-content: flex-end;
-}
-
-.button,
-.icon-button,
-.empty-state,
-.segmented button {
-  border: 1px solid var(--line);
-  border-radius: 8px;
-  color: var(--ink);
-  transition:
-    background 160ms ease,
-    border-color 160ms ease,
-    color 160ms ease,
-    transform 160ms ease;
-}
-
-.button:hover:not(:disabled),
-.icon-button:hover:not(:disabled),
-.empty-state:hover,
-.segmented button:hover {
-  transform: translateY(-1px);
-}
-
-.button {
-  align-items: center;
-  background: var(--surface);
-  display: inline-flex;
-  font-weight: 800;
-  gap: 9px;
-  min-height: 44px;
-  padding: 0 16px;
-}
-
-.button-primary {
-  background: var(--accent);
-  border-color: var(--accent);
-  color: #ffffff;
-}
-
-.button-wide {
-  justify-content: center;
-  margin-top: 8px;
-  width: 100%;
-}
-
-.workspace {
-  align-items: stretch;
-  display: grid;
-  gap: 18px;
-  grid-template-columns: minmax(0, 1fr) 340px;
-  margin: 0 auto;
-  max-width: 1440px;
-}
-
-.drop-zone {
-  align-items: center;
-  background: #111619;
-  border: 1px solid rgba(23, 28, 31, 0.18);
-  border-radius: 8px;
-  box-shadow: var(--shadow);
-  display: flex;
-  justify-content: center;
-  min-height: 58vh;
-  overflow: hidden;
-  position: relative;
-}
-
-.empty-state {
-  align-items: center;
-  background: #182024;
-  color: #f5f7f4;
-  display: grid;
-  gap: 10px;
-  justify-items: center;
-  min-height: 210px;
-  min-width: min(360px, calc(100vw - 72px));
-  padding: 34px;
-}
-
-.empty-state svg {
-  height: 42px;
-  width: 42px;
-}
-
-.empty-state span {
-  font-size: 1.2rem;
-  font-weight: 800;
-}
-
-.empty-state small {
-  color: #bac5c7;
-}
-
-.preview-wrap {
-  align-items: center;
-  display: flex;
-  height: 100%;
-  justify-content: center;
-  min-height: 58vh;
-  position: relative;
-  width: 100%;
-}
-
-.image-stage {
-  aspect-ratio: var(--ratio);
-  max-height: 76vh;
-  position: relative;
-  width: min(100%, calc(76vh * var(--ratio)));
-}
-
-.source-preview {
-  display: block;
-  height: 100%;
-  object-fit: contain;
-  width: 100%;
-}
-
-.region-layer {
-  inset: 0;
-  margin: auto;
-  pointer-events: none;
-  position: absolute;
-}
-
-.region-box {
-  border: 1px solid rgba(38, 255, 201, 0.78);
-  box-shadow: inset 0 0 0 1px rgba(10, 32, 31, 0.58);
-  position: absolute;
-}
-
-.control-panel {
-  align-self: stretch;
-  background: var(--surface);
-  border: 1px solid var(--line);
-  border-radius: 8px;
-  box-shadow: var(--shadow);
-  display: flex;
-  flex-direction: column;
-  gap: 18px;
-  padding: 18px;
-}
-
-.status-line {
-  align-items: center;
-  color: var(--muted);
-  display: flex;
-  font-size: 0.92rem;
-  gap: 9px;
-  min-height: 26px;
-}
-
-.dot,
-.pulse-dot {
-  background: var(--accent);
-  border-radius: 50%;
-  display: inline-block;
-  flex: 0 0 auto;
-  height: 9px;
-  width: 9px;
-}
-
-.pulse-dot {
-  animation: pulse 1.1s infinite;
-}
-
-.meta-grid {
-  display: grid;
-  gap: 10px;
-  grid-template-columns: 1fr 1fr;
-  margin: 0;
-}
-
-.meta-grid div {
-  background: var(--surface-muted);
-  border-radius: 8px;
-  padding: 12px;
-}
-
-.meta-grid dt {
-  color: var(--muted);
-  font-size: 0.75rem;
-  font-weight: 800;
-  margin-bottom: 4px;
-  text-transform: uppercase;
-}
-
-.meta-grid dd {
-  font-weight: 800;
-  margin: 0;
-}
-
-.error-text {
-  background: #fff1f1;
-  border: 1px solid #e0aaa8;
-  border-radius: 8px;
-  color: var(--warning);
-  font-weight: 700;
-  padding: 10px 12px;
-}
-
-.field {
-  display: grid;
-  gap: 9px;
-}
-
-.field > span {
-  color: var(--muted);
-  font-size: 0.82rem;
-  font-weight: 800;
-  text-transform: uppercase;
-}
-
-.field output {
-  color: var(--ink);
-  font-size: 0.9rem;
-  font-weight: 800;
-}
-
-input[type="range"] {
-  accent-color: var(--accent);
-  width: 100%;
-}
-
-.segmented {
-  background: var(--surface-muted);
-  border-radius: 8px;
-  display: grid;
-  gap: 4px;
-  grid-auto-columns: 1fr;
-  grid-auto-flow: column;
-  padding: 4px;
-}
-
-.segmented button {
-  background: transparent;
-  border-color: transparent;
-  min-height: 36px;
-  padding: 0 10px;
-  text-transform: capitalize;
-}
-
-.segmented button[aria-pressed="true"] {
-  background: var(--surface);
-  border-color: var(--line);
-  color: var(--accent-strong);
-  font-weight: 800;
-}
-
-.frames-section {
-  margin: 28px auto 0;
-  max-width: 1440px;
-}
-
-.section-head {
-  align-items: center;
-  display: flex;
-  justify-content: space-between;
-  margin-bottom: 14px;
-}
-
-.section-head span {
-  color: var(--muted);
-  font-weight: 800;
-}
-
-.frame-grid {
-  display: grid;
-  gap: 14px;
-  grid-template-columns: repeat(auto-fill, minmax(180px, 1fr));
-}
-
-.frame-card {
-  background: var(--surface);
-  border: 1px solid var(--line);
-  border-radius: 8px;
-  overflow: hidden;
-}
-
-.frame-card img {
-  aspect-ratio: 16 / 10;
-  background: #101517;
-  display: block;
-  object-fit: cover;
-  width: 100%;
-}
-
-.frame-info {
-  align-items: center;
-  display: flex;
-  gap: 12px;
-  justify-content: space-between;
-  padding: 10px;
-}
-
-.frame-info div {
-  display: grid;
-  gap: 2px;
-  min-width: 0;
-}
-
-.frame-info strong {
-  font-size: 0.9rem;
-}
-
-.frame-info span {
-  color: var(--muted);
-  font-size: 0.78rem;
-  font-weight: 700;
-}
-
-.icon-button {
-  align-items: center;
-  background: var(--accent-soft);
-  color: var(--accent-strong);
-  display: inline-flex;
-  flex: 0 0 auto;
-  height: 36px;
-  justify-content: center;
-  padding: 0;
-  width: 36px;
-}
-
-.sr-only {
-  height: 1px;
-  margin: -1px;
-  overflow: hidden;
-  position: absolute;
-  width: 1px;
-}
-
-@keyframes pulse {
-  0%,
-  100% {
-    opacity: 0.36;
-    transform: scale(0.82);
-  }
-
-  50% {
-    opacity: 1;
-    transform: scale(1);
-  }
-}
-
-@media (max-width: 980px) {
-  .app-shell {
-    padding: 18px;
-  }
-
-  .hero-band {
-    align-items: start;
-    flex-direction: column;
-  }
-
-  .actions {
-    justify-content: flex-start;
-  }
-
-  .workspace {
-    grid-template-columns: 1fr;
-  }
-
-  .drop-zone {
-    min-height: 46vh;
-  }
-
-  .control-panel {
-    min-height: auto;
-  }
-}
-
-@media (max-width: 560px) {
-  .app-shell {
-    padding: 12px;
-  }
-
-  h1 {
-    font-size: 2rem;
-  }
-
-  .button {
-    justify-content: center;
-    width: 100%;
-  }
-
-  .actions {
-    width: 100%;
-  }
-
-  .meta-grid {
-    grid-template-columns: 1fr;
-  }
-
-  .segmented {
-    grid-auto-flow: row;
-  }
-
-  .frame-grid {
-    grid-template-columns: repeat(auto-fill, minmax(142px, 1fr));
-  }
-}

app/layout.tsx

@@ -1,20 +0,0 @@
-import type { Metadata } from "next";
-import type { ReactNode } from "react";
-import "./globals.css";
-
-export const metadata: Metadata = {
-  title: "Grid2Frame",
-  description: "Extract individual frames from image grids.",
-};
-
-export default function RootLayout({
-  children,
-}: Readonly<{
-  children: ReactNode;
-}>) {
-  return (
-    <html lang="en">
-      <body>{children}</body>
-    </html>
-  );
-}

app/page.tsx

@@ -1,5 +0,0 @@
-import { GridExtractor } from "@/components/grid-extractor";
-
-export default function Home() {
-  return <GridExtractor />;
-}

components/grid-extractor.tsx

@@ -1,620 +0,0 @@
-"use client";
-
-/* eslint-disable @next/next/no-img-element */
-
-import JSZip from "jszip";
-import { type CSSProperties, useEffect, useMemo, useRef, useState } from "react";
-import {
-  detectGridRegions,
-  type DetectionSettings,
-  type FrameRegion,
-  type SeparatorMode,
-} from "@/lib/grid-detection";
-
-type OutputFormat = "image/jpeg" | "image/png" | "image/webp";
-
-type ExtractedFrame = FrameRegion & {
-  blob: Blob;
-  url: string;
-  fileName: string;
-};
-
-type SourceImage = {
-  file: File;
-  url: string;
-  width: number;
-  height: number;
-};
-
-const defaultSettings: DetectionSettings = {
-  minFrameSize: 80,
-  separatorMode: "auto",
-  sensitivity: 58,
-};
-
-const maxAnalysisSide = 1800;
-
-export function GridExtractor() {
-  const inputRef = useRef<HTMLInputElement>(null);
-  const sourceUrlRef = useRef<string | null>(null);
-  const framesRef = useRef<ExtractedFrame[]>([]);
-  const [source, setSource] = useState<SourceImage | null>(null);
-  const [settings, setSettings] = useState<DetectionSettings>(defaultSettings);
-  const [format, setFormat] = useState<OutputFormat>("image/jpeg");
-  const [regions, setRegions] = useState<FrameRegion[]>([]);
-  const [frames, setFramesState] = useState<ExtractedFrame[]>([]);
-  const [engine, setEngine] = useState("Idle");
-  const [status, setStatus] = useState("No image loaded");
-  const [error, setError] = useState<string | null>(null);
-  const [isExtracting, setIsExtracting] = useState(false);
-  const [isZipping, setIsZipping] = useState(false);
-  const [zipProgress, setZipProgress] = useState(0);
-
-  useEffect(() => {
-    return () => {
-      if (sourceUrlRef.current) URL.revokeObjectURL(sourceUrlRef.current);
-      revokeFrames(framesRef.current);
-    };
-  }, []);
-
-  const baseName = useMemo(() => {
-    if (!source?.file.name) return "grid";
-    return source.file.name.replace(/\.[^/.]+$/, "").replace(/[^\w-]+/g, "-");
-  }, [source]);
-
-  async function handleFile(file: File) {
-    if (!file.type.startsWith("image/")) {
-      setError("Select an image file.");
-      return;
-    }
-
-    setError(null);
-    setStatus("Loading image");
-    setEngine("Loading");
-    setRegions([]);
-    replaceFrames([]);
-
-    if (sourceUrlRef.current) URL.revokeObjectURL(sourceUrlRef.current);
-    const url = URL.createObjectURL(file);
-    sourceUrlRef.current = url;
-
-    try {
-      const bitmap = await createImageBitmap(file, {
-        imageOrientation: "from-image",
-      });
-      setSource({ file, url, width: bitmap.width, height: bitmap.height });
-      bitmap.close();
-      await extractFrames(file, url);
-    } catch (loadError) {
-      URL.revokeObjectURL(url);
-      sourceUrlRef.current = null;
-      setSource(null);
-      setError(toErrorMessage(loadError));
-      setEngine("Idle");
-      setStatus("Image could not be loaded");
-    }
-  }
-
-  async function extractFrames(file = source?.file, fallbackUrl = source?.url) {
-    if (!file) return;
-
-    setError(null);
-    setIsExtracting(true);
-    setZipProgress(0);
-    setEngine("Python/OpenCV");
-    setStatus("Detecting grid with Python");
-    replaceFrames([]);
-
-    let bitmap: ImageBitmap | null = null;
-
-    try {
-      bitmap = await createImageBitmap(file, {
-        imageOrientation: "from-image",
-      });
-      const result = await detectRegions(file, bitmap, settings);
-      setEngine(result.engine === "python-opencv" ? "Python/OpenCV" : "Browser fallback");
-
-      setRegions(result.regions);
-
-      if (result.regions.length === 0) {
-        setStatus("No frames detected");
-        setError("No frames were detected. Raise sensitivity or lower minimum size.");
-        return;
-      }
-
-      setStatus(`Cropping ${result.regions.length} frames`);
-      const nextFrames = await cropRegions(
-        bitmap,
-        result.regions,
-        fileBaseName(file),
-        format,
-      );
-      replaceFrames(nextFrames);
-      setStatus(
-        `${nextFrames.length} frames extracted from ${result.columns} columns x ${result.rows} rows`,
-      );
-    } catch (extractError) {
-      setError(toErrorMessage(extractError));
-      setEngine("Failed");
-      setStatus("Extraction failed");
-      if (fallbackUrl) setSource((current) => current && { ...current, url: fallbackUrl });
-    } finally {
-      bitmap?.close();
-      setIsExtracting(false);
-    }
-  }
-
-  async function downloadAll() {
-    if (frames.length === 0) return;
-
-    setIsZipping(true);
-    setZipProgress(0);
-    setStatus("Building ZIP");
-
-    try {
-      const zip = new JSZip();
-      for (const frame of frames) {
-        zip.file(frame.fileName, frame.blob);
-      }
-
-      const blob = await zip.generateAsync({ type: "blob" }, (metadata) => {
-        setZipProgress(Math.round(metadata.percent));
-      });
-
-      downloadBlob(blob, `${baseName || "grid"}-frames.zip`);
-      setStatus(`ZIP ready with ${frames.length} frames`);
-    } catch (zipError) {
-      setError(toErrorMessage(zipError));
-      setStatus("ZIP failed");
-    } finally {
-      setIsZipping(false);
-    }
-  }
-
-  function replaceFrames(nextFrames: ExtractedFrame[]) {
-    revokeFrames(framesRef.current);
-    framesRef.current = nextFrames;
-    setFramesState(nextFrames);
-  }
-
-  return (
-    <main className="app-shell">
-      <section className="hero-band">
-        <div>
-          <p className="eyebrow">Grid2Frame</p>
-          <h1>Extract every frame from a grid image.</h1>
-        </div>
-        <div className="actions">
-          <button
-            className="button button-primary"
-            onClick={() => inputRef.current?.click()}
-            type="button"
-          >
-            <UploadIcon />
-            Upload grid
-          </button>
-          <button
-            className="button"
-            disabled={!source || isExtracting}
-            onClick={() => void extractFrames()}
-            type="button"
-          >
-            <ScanIcon />
-            Extract
-          </button>
-        </div>
-      </section>
-
-      <section className="workspace">
-        <div
-          className="drop-zone"
-          onDragOver={(event) => event.preventDefault()}
-          onDrop={(event) => {
-            event.preventDefault();
-            const file = event.dataTransfer.files[0];
-            if (file) void handleFile(file);
-          }}
-        >
-          <input
-            ref={inputRef}
-            accept="image/*"
-            className="sr-only"
-            onChange={(event) => {
-              const file = event.target.files?.[0];
-              if (file) void handleFile(file);
-              event.currentTarget.value = "";
-            }}
-            type="file"
-          />
-
-          {source ? (
-            <div className="preview-wrap">
-              <div
-                className="image-stage"
-                style={{ "--ratio": source.width / source.height } as CSSProperties}
-              >
-                <img alt="Uploaded grid preview" className="source-preview" src={source.url} />
-                <div aria-hidden="true" className="region-layer">
-                  {regions.map((region) => (
-                    <span
-                      className="region-box"
-                      key={region.id}
-                      style={{
-                        height: `${(region.height / source.height) * 100}%`,
-                        left: `${(region.x / source.width) * 100}%`,
-                        top: `${(region.y / source.height) * 100}%`,
-                        width: `${(region.width / source.width) * 100}%`,
-                      }}
-                    />
-                  ))}
-                </div>
-              </div>
-            </div>
-          ) : (
-            <button
-              className="empty-state"
-              onClick={() => inputRef.current?.click()}
-              type="button"
-            >
-              <ImageIcon />
-              <span>Drop image or browse</span>
-              <small>JPG, PNG, WebP</small>
-            </button>
-          )}
-        </div>
-
-        <aside className="control-panel">
-          <div className="status-line">
-            <span className={isExtracting || isZipping ? "pulse-dot" : "dot"} />
-            <span>{isZipping ? `${status} ${zipProgress}%` : status}</span>
-          </div>
-
-          {source && (
-            <dl className="meta-grid">
-              <div>
-                <dt>Source</dt>
-                <dd>{source.width.toLocaleString()} x {source.height.toLocaleString()}</dd>
-              </div>
-              <div>
-                <dt>Frames</dt>
-                <dd>{frames.length}</dd>
-              </div>
-              <div>
-                <dt>Engine</dt>
-                <dd>{engine}</dd>
-              </div>
-            </dl>
-          )}
-
-          {error && <p className="error-text">{error}</p>}
-
-          <label className="field">
-            <span>Sensitivity</span>
-            <input
-              max="100"
-              min="0"
-              onChange={(event) =>
-                setSettings((current) => ({
-                  ...current,
-                  sensitivity: Number(event.target.value),
-                }))
-              }
-              type="range"
-              value={settings.sensitivity}
-            />
-            <output>{settings.sensitivity}</output>
-          </label>
-
-          <label className="field">
-            <span>Minimum frame</span>
-            <input
-              max="600"
-              min="16"
-              onChange={(event) =>
-                setSettings((current) => ({
-                  ...current,
-                  minFrameSize: Number(event.target.value),
-                }))
-              }
-              step="4"
-              type="range"
-              value={settings.minFrameSize}
-            />
-            <output>{settings.minFrameSize}px</output>
-          </label>
-
-          <div className="field">
-            <span>Separator</span>
-            <div className="segmented" role="group">
-              {(["auto", "dark", "light"] as SeparatorMode[]).map((mode) => (
-                <button
-                  aria-pressed={settings.separatorMode === mode}
-                  key={mode}
-                  onClick={() =>
-                    setSettings((current) => ({
-                      ...current,
-                      separatorMode: mode,
-                    }))
-                  }
-                  type="button"
-                >
-                  {mode}
-                </button>
-              ))}
-            </div>
-          </div>
-
-          <div className="field">
-            <span>Output</span>
-            <div className="segmented" role="group">
-              {(["image/jpeg", "image/png", "image/webp"] as OutputFormat[]).map(
-                (mimeType) => (
-                  <button
-                    aria-pressed={format === mimeType}
-                    key={mimeType}
-                    onClick={() => setFormat(mimeType)}
-                    type="button"
-                  >
-                    {formatLabel(mimeType)}
-                  </button>
-                ),
-              )}
-            </div>
-          </div>
-
-          <button
-            className="button button-primary button-wide"
-            disabled={frames.length === 0 || isZipping}
-            onClick={() => void downloadAll()}
-            type="button"
-          >
-            <ArchiveIcon />
-            Download ZIP
-          </button>
-        </aside>
-      </section>
-
-      {frames.length > 0 && (
-        <section className="frames-section">
-          <div className="section-head">
-            <h2>Extracted frames</h2>
-            <span>{frames.length} files</span>
-          </div>
-          <div className="frame-grid">
-            {frames.map((frame, index) => (
-              <article className="frame-card" key={frame.url}>
-                <img alt={`Extracted frame ${index + 1}`} src={frame.url} />
-                <div className="frame-info">
-                  <div>
-                    <strong>{String(index + 1).padStart(2, "0")}</strong>
-                    <span>{frame.width} x {frame.height}</span>
-                  </div>
-                  <button
-                    aria-label={`Download ${frame.fileName}`}
-                    className="icon-button"
-                    onClick={() => downloadBlob(frame.blob, frame.fileName)}
-                    title="Download frame"
-                    type="button"
-                  >
-                    <DownloadIcon />
-                  </button>
-                </div>
-              </article>
-            ))}
-          </div>
-        </section>
-      )}
-    </main>
-  );
-}
-
-async function detectRegions(
-  file: File,
-  bitmap: ImageBitmap,
-  settings: DetectionSettings,
-) {
-  try {
-    const formData = new FormData();
-    formData.append("image", file);
-    formData.append("minFrameSize", String(settings.minFrameSize));
-    formData.append("separatorMode", settings.separatorMode);
-    formData.append("sensitivity", String(settings.sensitivity));
-
-    const response = await fetch("/api/extract", {
-      method: "POST",
-      body: formData,
-    });
-
-    const payload = (await response.json()) as
-      | {
-          regions: FrameRegion[];
-          rows: number;
-          columns: number;
-          engine: string;
-        }
-      | { error: string };
-
-    if (!response.ok || "error" in payload) {
-      throw new Error("error" in payload ? payload.error : "Python extraction failed.");
-    }
-
-    return payload;
-  } catch {
-    const analysis = buildAnalysisImageData(bitmap);
-    return {
-      ...detectGridRegions({
-        imageData: analysis.imageData,
-        originalWidth: bitmap.width,
-        originalHeight: bitmap.height,
-        settings,
-      }),
-      engine: "browser-fallback",
-    };
-  }
-}
-
-function buildAnalysisImageData(bitmap: ImageBitmap) {
-  const scale = Math.min(1, maxAnalysisSide / Math.max(bitmap.width, bitmap.height));
-  const width = Math.max(1, Math.round(bitmap.width * scale));
-  const height = Math.max(1, Math.round(bitmap.height * scale));
-  const canvas = document.createElement("canvas");
-  canvas.width = width;
-  canvas.height = height;
-  const context = getCanvasContext(canvas);
-  context.drawImage(bitmap, 0, 0, width, height);
-
-  return {
-    imageData: context.getImageData(0, 0, width, height),
-    scale,
-  };
-}
-
-async function cropRegions(
-  bitmap: ImageBitmap,
-  regions: FrameRegion[],
-  baseName: string,
-  format: OutputFormat,
-) {
-  const canvas = document.createElement("canvas");
-  const context = getCanvasContext(canvas);
-  const extension = extensionForFormat(format);
-  const frames: ExtractedFrame[] = [];
-
-  for (const region of regions) {
-    canvas.width = region.width;
-    canvas.height = region.height;
-    context.clearRect(0, 0, region.width, region.height);
-    context.drawImage(
-      bitmap,
-      region.x,
-      region.y,
-      region.width,
-      region.height,
-      0,
-      0,
-      region.width,
-      region.height,
-    );
-
-    const blob = await canvasToBlob(canvas, format, format === "image/jpeg" ? 0.94 : 0.98);
-    const fileName = `${baseName || "grid"}-r${String(region.row + 1).padStart(2, "0")}-c${String(region.col + 1).padStart(2, "0")}.${extension}`;
-    frames.push({
-      ...region,
-      blob,
-      fileName,
-      url: URL.createObjectURL(blob),
-    });
-  }
-
-  return frames;
-}
-
-function getCanvasContext(canvas: HTMLCanvasElement) {
-  const context = canvas.getContext("2d", {
-    alpha: false,
-    willReadFrequently: true,
-  });
-
-  if (!context) {
-    throw new Error("Canvas is unavailable in this browser.");
-  }
-
-  return context;
-}
-
-function canvasToBlob(
-  canvas: HTMLCanvasElement,
-  type: OutputFormat,
-  quality: number,
-) {
-  return new Promise<Blob>((resolve, reject) => {
-    canvas.toBlob(
-      (blob) => {
-        if (blob) resolve(blob);
-        else reject(new Error("Could not render extracted frame."));
-      },
-      type,
-      quality,
-    );
-  });
-}
-
-function revokeFrames(frames: ExtractedFrame[]) {
-  for (const frame of frames) {
-    URL.revokeObjectURL(frame.url);
-  }
-}
-
-function downloadBlob(blob: Blob, fileName: string) {
-  const url = URL.createObjectURL(blob);
-  const anchor = document.createElement("a");
-  anchor.href = url;
-  anchor.download = fileName;
-  document.body.appendChild(anchor);
-  anchor.click();
-  anchor.remove();
-  window.setTimeout(() => URL.revokeObjectURL(url), 500);
-}
-
-function toErrorMessage(error: unknown) {
-  if (error instanceof Error) return error.message;
-  return "Something went wrong.";
-}
-
-function fileBaseName(file: File) {
-  return file.name.replace(/\.[^/.]+$/, "").replace(/[^\w-]+/g, "-");
-}
-
-function formatLabel(type: OutputFormat) {
-  if (type === "image/png") return "PNG";
-  if (type === "image/webp") return "WebP";
-  return "JPG";
-}
-
-function extensionForFormat(type: OutputFormat) {
-  if (type === "image/png") return "png";
-  if (type === "image/webp") return "webp";
-  return "jpg";
-}
-
-function UploadIcon() {
-  return (
-    <svg aria-hidden="true" viewBox="0 0 24 24">
-      <path d="M12 3 7.5 7.5l1.4 1.4 2.1-2.08V16h2V6.82l2.1 2.08 1.4-1.4L12 3Z" />
-      <path d="M5 15h2v3h10v-3h2v5H5v-5Z" />
-    </svg>
-  );
-}
-
-function ScanIcon() {
-  return (
-    <svg aria-hidden="true" viewBox="0 0 24 24">
-      <path d="M5 4h5v2H7v3H5V4Zm9 0h5v5h-2V6h-3V4ZM5 15h2v3h3v2H5v-5Zm12 3v-3h2v5h-5v-2h3ZM8 9h8v6H8V9Zm2 2v2h4v-2h-4Z" />
-    </svg>
-  );
-}
-
-function ImageIcon() {
-  return (
-    <svg aria-hidden="true" viewBox="0 0 24 24">
-      <path d="M4 5h16v14H4V5Zm2 2v8.6l3.5-3.5 2.5 2.5 4-4 2 2V7H6Zm0 10h12.6L16 14.4l-4 4-2.5-2.5L6 19.4V17Z" />
-    </svg>
-  );
-}
-
-function ArchiveIcon() {
-  return (
-    <svg aria-hidden="true" viewBox="0 0 24 24">
-      <path d="M4 4h16v5H4V4Zm2 2v1h12V6H6Zm0 5h12v9H6v-9Zm5 2v2h2v-2h-2Z" />
-    </svg>
-  );
-}
-
-function DownloadIcon() {
-  return (
-    <svg aria-hidden="true" viewBox="0 0 24 24">
-      <path d="M11 4h2v8.18l2.1-2.08 1.4 1.4L12 16l-4.5-4.5 1.4-1.4 2.1 2.08V4Z" />
-      <path d="M5 18h14v2H5v-2Z" />
-    </svg>
-  );
-}

eslint.config.mjs

@@ -1,12 +0,0 @@
-import nextVitals from "eslint-config-next/core-web-vitals";
-import nextTypescript from "eslint-config-next/typescript";
-
-const eslintConfig = [
-  ...nextVitals,
-  ...nextTypescript,
-  {
-    ignores: [".next/**", "node_modules/**", "out/**"],
-  },
-];
-
-export default eslintConfig;

grid2frame/__init__.py

@@ -0,0 +1,3 @@
+from .extractor import DetectionResult, FrameRegion, detect_grid, extract_frames
+
+__all__ = ["DetectionResult", "FrameRegion", "detect_grid", "extract_frames"]

grid2frame/extractor.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+
+@dataclass(frozen=True)
+class FrameRegion:
+    id: str
+    row: int
+    col: int
+    x: int
+    y: int
+    width: int
+    height: int
+
+
+@dataclass(frozen=True)
+class DetectionResult:
+    regions: list[FrameRegion]
+    rows: int
+    columns: int
+    width: int
+    height: int
+
+
+@dataclass
+class Band:
+    start: int
+    end: int
+
+
+@dataclass(frozen=True)
+class Segment:
+    start: int
+    end: int
+
+
+def read_image(path: str | Path) -> np.ndarray:
+    image = cv2.imdecode(np.fromfile(Path(path), dtype=np.uint8), cv2.IMREAD_COLOR)
+    if image is None:
+        raise ValueError(f"Could not read image: {path}")
+    return image
+
+
+def detect_grid(
+    image: np.ndarray,
+    min_frame_size: int = 80,
+    sensitivity: int = 58,
+    separator_mode: str = "auto",
+) -> DetectionResult:
+    height, width = image.shape[:2]
+    gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+
+    vertical_bands = find_separator_bands(
+        gray=gray,
+        axis="vertical",
+        min_frame_size=min_frame_size,
+        sensitivity=sensitivity,
+        separator_mode=separator_mode,
+    )
+    horizontal_bands = find_separator_bands(
+        gray=gray,
+        axis="horizontal",
+        min_frame_size=min_frame_size,
+        sensitivity=sensitivity,
+        separator_mode=separator_mode,
+    )
+
+    x_segments = bands_to_segments(vertical_bands, width, min_frame_size)
+    y_segments = bands_to_segments(horizontal_bands, height, min_frame_size)
+    regions: list[FrameRegion] = []
+
+    for row, y_segment in enumerate(y_segments):
+        for col, x_segment in enumerate(x_segments):
+            regions.append(
+                FrameRegion(
+                    id=f"{row + 1}-{col + 1}",
+                    row=row,
+                    col=col,
+                    x=x_segment.start,
+                    y=y_segment.start,
+                    width=x_segment.end - x_segment.start,
+                    height=y_segment.end - y_segment.start,
+                )
+            )
+
+    return DetectionResult(
+        regions=regions,
+        rows=len(y_segments),
+        columns=len(x_segments),
+        width=width,
+        height=height,
+    )
+
+
+def extract_frames(image: np.ndarray, regions: list[FrameRegion]) -> list[np.ndarray]:
+    frames = []
+    for region in regions:
+        frames.append(
+            image[
+                region.y : region.y + region.height,
+                region.x : region.x + region.width,
+            ].copy()
+        )
+    return frames
+
+
+def annotate_regions(image: np.ndarray, regions: list[FrameRegion]) -> np.ndarray:
+    annotated = image.copy()
+    color = (190, 255, 55)
+
+    for region in regions:
+        cv2.rectangle(
+            annotated,
+            (region.x, region.y),
+            (region.x + region.width, region.y + region.height),
+            color,
+            max(1, round(max(image.shape[:2]) / 700)),
+        )
+
+    return annotated
+
+
+def find_separator_bands(
+    gray: np.ndarray,
+    axis: str,
+    min_frame_size: int,
+    sensitivity: int,
+    separator_mode: str,
+) -> list[Band]:
+    sensitivity = max(0, min(100, sensitivity))
+    dark_threshold = 10 + round(sensitivity * 0.24)
+    light_threshold = 246 - round(sensitivity * 0.16)
+    line_ratio_threshold = 0.972 - sensitivity * 0.00035
+
+    if separator_mode == "dark":
+        separator_mask = gray <= dark_threshold
+    elif separator_mode == "light":
+        separator_mask = gray >= light_threshold
+    else:
+        separator_mask = (gray <= dark_threshold) | (gray >= light_threshold)
+
+    if axis == "vertical":
+        profile = separator_mask.mean(axis=0)
+        axis_size = gray.shape[1]
+    else:
+        profile = separator_mask.mean(axis=1)
+        axis_size = gray.shape[0]
+
+    candidate_indexes = np.flatnonzero(profile >= line_ratio_threshold)
+    bands = group_indexes(candidate_indexes)
+    max_thickness = max(2, min(round(axis_size * 0.018), round(min_frame_size * 0.35)))
+    bands = [band for band in bands if band.end - band.start + 1 <= max_thickness]
+
+    return merge_close_bands(bands, min_gap=max(2, round(min_frame_size * 0.08)))
+
+
+def group_indexes(indexes: np.ndarray) -> list[Band]:
+    if indexes.size == 0:
+        return []
+
+    bands: list[Band] = []
+    start = int(indexes[0])
+    previous = int(indexes[0])
+
+    for raw_index in indexes[1:]:
+        index = int(raw_index)
+        if index <= previous + 2:
+            previous = index
+            continue
+
+        bands.append(Band(start=start, end=previous))
+        start = index
+        previous = index
+
+    bands.append(Band(start=start, end=previous))
+    return bands
+
+
+def merge_close_bands(bands: list[Band], min_gap: int) -> list[Band]:
+    if not bands:
+        return []
+
+    merged = [bands[0]]
+    for band in bands[1:]:
+        current = merged[-1]
+        if band.start - current.end <= min_gap:
+            current.end = band.end
+        else:
+            merged.append(band)
+
+    return merged
+
+
+def bands_to_segments(bands: list[Band], axis_size: int, min_frame_size: int) -> list[Segment]:
+    if not bands:
+        return [Segment(start=0, end=axis_size)]
+
+    edge_tolerance = max(3, round(axis_size * 0.008))
+    first_pixel = 0
+    last_pixel = axis_size
+    internal_bands: list[Band] = []
+
+    for band in bands:
+        if band.start <= edge_tolerance:
+            first_pixel = max(first_pixel, band.end + 1)
+        elif band.end >= axis_size - edge_tolerance - 1:
+            last_pixel = min(last_pixel, band.start)
+        else:
+            internal_bands.append(band)
+
+    segments: list[Segment] = []
+    segment_start = first_pixel
+
+    for band in internal_bands:
+        push_segment(segments, segment_start, band.start, min_frame_size)
+        segment_start = band.end + 1
+
+    push_segment(segments, segment_start, last_pixel, min_frame_size)
+    return segments
+
+
+def push_segment(segments: list[Segment], start: int, end: int, min_frame_size: int) -> None:
+    start = max(0, int(round(start)))
+    end = max(start, int(round(end)))
+
+    if end - start >= min_frame_size:
+        segments.append(Segment(start=start, end=end))

lib/grid-detection.ts

@@ -1,290 +0,0 @@
-export type SeparatorMode = "auto" | "dark" | "light";
-
-export type DetectionSettings = {
-  minFrameSize: number;
-  separatorMode: SeparatorMode;
-  sensitivity: number;
-};
-
-export type Segment = {
-  start: number;
-  end: number;
-};
-
-export type FrameRegion = {
-  id: string;
-  row: number;
-  col: number;
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-};
-
-type AxisSample = {
-  candidate: boolean;
-  score: number;
-};
-
-type Band = {
-  start: number;
-  end: number;
-};
-
-type DetectGridInput = {
-  imageData: ImageData;
-  originalWidth: number;
-  originalHeight: number;
-  settings: DetectionSettings;
-};
-
-export function detectGridRegions({
-  imageData,
-  originalWidth,
-  originalHeight,
-  settings,
-}: DetectGridInput) {
-  const analysisWidth = imageData.width;
-  const analysisHeight = imageData.height;
-  const scaleX = analysisWidth / originalWidth;
-  const scaleY = analysisHeight / originalHeight;
-
-  const verticalBands = selectSeparatorBands(
-    buildAxisProfile(imageData, "vertical", settings),
-    analysisWidth,
-    Math.max(3, Math.round(settings.minFrameSize * scaleX)),
-  );
-  const horizontalBands = selectSeparatorBands(
-    buildAxisProfile(imageData, "horizontal", settings),
-    analysisHeight,
-    Math.max(3, Math.round(settings.minFrameSize * scaleY)),
-  );
-
-  const xSegments = bandsToSegments({
-    bands: verticalBands,
-    analysisSize: analysisWidth,
-    originalSize: originalWidth,
-    scale: scaleX,
-    minFrameSize: settings.minFrameSize,
-  });
-  const ySegments = bandsToSegments({
-    bands: horizontalBands,
-    analysisSize: analysisHeight,
-    originalSize: originalHeight,
-    scale: scaleY,
-    minFrameSize: settings.minFrameSize,
-  });
-
-  const regions = ySegments.flatMap((ySegment, row) =>
-    xSegments.map((xSegment, col) => ({
-      id: `${row + 1}-${col + 1}`,
-      row,
-      col,
-      x: xSegment.start,
-      y: ySegment.start,
-      width: xSegment.end - xSegment.start,
-      height: ySegment.end - ySegment.start,
-    })),
-  );
-
-  return {
-    regions,
-    rows: ySegments.length,
-    columns: xSegments.length,
-    xSegments,
-    ySegments,
-  };
-}
-
-function buildAxisProfile(
-  imageData: ImageData,
-  axis: "vertical" | "horizontal",
-  settings: DetectionSettings,
-): AxisSample[] {
-  const { data, width, height } = imageData;
-  const axisSize = axis === "vertical" ? width : height;
-  const crossSize = axis === "vertical" ? height : width;
-  const crossStep = Math.max(1, Math.floor(crossSize / 900));
-  const threshold = sensitivityToThreshold(settings.sensitivity);
-  const edgeThreshold = Math.max(0.28, threshold * 0.74);
-
-  return Array.from({ length: axisSize }, (_, axisIndex) => {
-    let count = 0;
-    let darkCount = 0;
-    let lightCount = 0;
-    let luminanceSum = 0;
-    let luminanceSquareSum = 0;
-    let edgeDiffSum = 0;
-
-    for (let crossIndex = 0; crossIndex < crossSize; crossIndex += crossStep) {
-      const x = axis === "vertical" ? axisIndex : crossIndex;
-      const y = axis === "vertical" ? crossIndex : axisIndex;
-      const offset = (y * width + x) * 4;
-      const luminance =
-        data[offset] * 0.2126 +
-        data[offset + 1] * 0.7152 +
-        data[offset + 2] * 0.0722;
-
-      luminanceSum += luminance;
-      luminanceSquareSum += luminance * luminance;
-      if (luminance <= 42) darkCount += 1;
-      if (luminance >= 218) lightCount += 1;
-
-      if (axisIndex < axisSize - 1) {
-        const nextX = axis === "vertical" ? axisIndex + 1 : crossIndex;
-        const nextY = axis === "vertical" ? crossIndex : axisIndex + 1;
-        const nextOffset = (nextY * width + nextX) * 4;
-        const nextLuminance =
-          data[nextOffset] * 0.2126 +
-          data[nextOffset + 1] * 0.7152 +
-          data[nextOffset + 2] * 0.0722;
-        edgeDiffSum += Math.abs(luminance - nextLuminance);
-      }
-
-      count += 1;
-    }
-
-    const mean = luminanceSum / count;
-    const variance = Math.max(0, luminanceSquareSum / count - mean * mean);
-    const standardDeviation = Math.sqrt(variance);
-    const uniformity = 1 - Math.min(standardDeviation / 64, 1);
-    const darkRatio = darkCount / count;
-    const lightRatio = lightCount / count;
-    const extremeRatio =
-      settings.separatorMode === "dark"
-        ? darkRatio
-        : settings.separatorMode === "light"
-          ? lightRatio
-          : Math.max(darkRatio, lightRatio);
-    const separatorScore = uniformity * extremeRatio;
-    const edgeScore =
-      Math.min(edgeDiffSum / count / 34, 1) *
-      Math.min(extremeRatio / 0.72, 1);
-    const score = Math.max(
-      edgeScore * 1.2,
-      separatorScore * 0.68 + edgeScore * 0.38,
-    );
-
-    return {
-      candidate:
-        (separatorScore >= threshold &&
-          uniformity >= 0.46 &&
-          extremeRatio >= 0.5) ||
-        (edgeScore >= edgeThreshold && extremeRatio >= 0.48),
-      score,
-    };
-  });
-}
-
-function sensitivityToThreshold(sensitivity: number) {
-  const normalized = clamp(sensitivity, 0, 100) / 100;
-  return 0.68 - normalized * 0.34;
-}
-
-function selectSeparatorBands(
-  profile: AxisSample[],
-  axisSize: number,
-  minFrameAnalysisSize: number,
-) {
-  const edgeZone = Math.max(2, Math.round(axisSize * 0.006));
-  const candidates = profile
-    .map((sample, index) => ({ index, ...sample }))
-    .filter(({ candidate, index, score }) => {
-      if (!candidate) return false;
-      if (index <= edgeZone || index >= axisSize - edgeZone - 1) return true;
-
-      const previous = profile[index - 1]?.score ?? 0;
-      const next = profile[index + 1]?.score ?? 0;
-      return score >= previous && score >= next;
-    })
-    .sort((a, b) => b.score - a.score);
-
-  const selected: Array<{ index: number; score: number }> = [];
-  const minGap = Math.max(4, Math.round(minFrameAnalysisSize * 0.84));
-
-  for (const candidate of candidates) {
-    const isEdge =
-      candidate.index <= edgeZone || candidate.index >= axisSize - edgeZone - 1;
-    const hasNearby = selected.some(
-      (current) => Math.abs(current.index - candidate.index) < minGap,
-    );
-
-    if (isEdge || !hasNearby) {
-      selected.push({ index: candidate.index, score: candidate.score });
-    }
-  }
-
-  return selected
-    .sort((a, b) => a.index - b.index)
-    .map(({ index }) => ({
-      start: Math.max(0, index - 1),
-      end: Math.min(axisSize - 1, index + 1),
-    }));
-}
-
-function bandsToSegments({
-  bands,
-  analysisSize,
-  originalSize,
-  scale,
-  minFrameSize,
-}: {
-  bands: Band[];
-  analysisSize: number;
-  originalSize: number;
-  scale: number;
-  minFrameSize: number;
-}) {
-  const edgeTolerance = Math.max(2, Math.round(analysisSize * 0.006));
-  let firstPixel = 0;
-  let lastPixel = originalSize;
-  const internalBands: Band[] = [];
-
-  for (const band of bands) {
-    if (band.start <= edgeTolerance) {
-      firstPixel = Math.max(firstPixel, Math.ceil((band.end + 1) / scale));
-      continue;
-    }
-
-    if (band.end >= analysisSize - edgeTolerance - 1) {
-      lastPixel = Math.min(lastPixel, Math.floor(band.start / scale));
-      continue;
-    }
-
-    internalBands.push(band);
-  }
-
-  const segments: Segment[] = [];
-  let segmentStart = firstPixel;
-
-  for (const band of internalBands) {
-    const segmentEnd = Math.floor(band.start / scale);
-    pushSegment(segments, segmentStart, segmentEnd, minFrameSize);
-    segmentStart = Math.ceil((band.end + 1) / scale);
-  }
-
-  pushSegment(segments, segmentStart, lastPixel, minFrameSize);
-
-  return segments;
-}
-
-function pushSegment(
-  segments: Segment[],
-  start: number,
-  end: number,
-  minFrameSize: number,
-) {
-  const normalizedStart = Math.max(0, Math.round(start));
-  const normalizedEnd = Math.max(normalizedStart, Math.round(end));
-
-  if (normalizedEnd - normalizedStart >= minFrameSize) {
-    segments.push({
-      start: normalizedStart,
-      end: normalizedEnd,
-    });
-  }
-}
-
-function clamp(value: number, min: number, max: number) {
-  return Math.min(max, Math.max(min, value));
-}

next-env.d.ts

@@ -1,6 +0,0 @@
-/// <reference types="next" />
-/// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts";
-
-// NOTE: This file should not be edited
-// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

next.config.ts

@@ -1,5 +0,0 @@
-import type { NextConfig } from "next";
-
-const nextConfig: NextConfig = {};
-
-export default nextConfig;

package.json

@@ -1,27 +0,0 @@
-{
-  "name": "gride2frame",
-  "version": "0.1.0",
-  "private": true,
-  "scripts": {
-    "dev": "next dev",
-    "build": "next build",
-    "start": "next start",
-    "lint": "eslint .",
-    "setup:python": "python3 -m venv .venv && .venv/bin/python3 -m pip install -r requirements.txt"
-  },
-  "dependencies": {
-    "jszip": "^3.10.1",
-    "next": "latest",
-    "react": "latest",
-    "react-dom": "latest"
-  },
-  "devDependencies": {
-    "@playwright/test": "^1.59.1",
-    "@types/node": "latest",
-    "@types/react": "latest",
-    "@types/react-dom": "latest",
-    "eslint": "latest",
-    "eslint-config-next": "latest",
-    "typescript": "latest"
-  }
-}

requirements.txt

@@ -1 +1,2 @@
 opencv-python-headless==4.13.0.92
+gradio==6.1.0

scripts/extract_grid.py

@@ -1,24 +1,13 @@
 #!/usr/bin/env python3
 import argparse
+from dataclasses import asdict
 import json
 import sys
-from dataclasses import dataclass
 from pathlib import Path
 
-import cv2
-import numpy as np
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
 
-
-@dataclass
-class Band:
-    start: int
-    end: int
-
-
-@dataclass
-class Segment:
-    start: int
-    end: int
+from grid2frame.extractor import detect_grid, read_image
 
 
 def parse_args() -> argparse.Namespace:
@@ -32,172 +21,17 @@ def parse_args() -> argparse.Namespace:
 
 def main() -> int:
     args = parse_args()
-    image = cv2.imdecode(np.fromfile(args.image, dtype=np.uint8), cv2.IMREAD_COLOR)
-
-    if image is None:
-        raise ValueError(f"Could not read image: {args.image}")
-
-    height, width = image.shape[:2]
-    gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
-
-    vertical_bands = find_separator_bands(
-        gray=gray,
-        axis="vertical",
+    image = read_image(args.image)
+    result = detect_grid(
+        image,
         min_frame_size=args.min_frame_size,
-        sensitivity=args.sensitivity,
         separator_mode=args.separator_mode,
-    )
-    horizontal_bands = find_separator_bands(
-        gray=gray,
-        axis="horizontal",
-        min_frame_size=args.min_frame_size,
         sensitivity=args.sensitivity,
-        separator_mode=args.separator_mode,
-    )
-
-    x_segments = bands_to_segments(vertical_bands, width, args.min_frame_size)
-    y_segments = bands_to_segments(horizontal_bands, height, args.min_frame_size)
-
-    regions = []
-    for row, y_segment in enumerate(y_segments):
-        for col, x_segment in enumerate(x_segments):
-            regions.append(
-                {
-                    "id": f"{row + 1}-{col + 1}",
-                    "row": row,
-                    "col": col,
-                    "x": x_segment.start,
-                    "y": y_segment.start,
-                    "width": x_segment.end - x_segment.start,
-                    "height": y_segment.end - y_segment.start,
-                }
-            )
-
-    print(
-        json.dumps(
-            {
-                "regions": regions,
-                "rows": len(y_segments),
-                "columns": len(x_segments),
-                "width": width,
-                "height": height,
-            }
-        )
     )
+    print(json.dumps(asdict(result)))
     return 0
 
 
-def find_separator_bands(
-    gray: np.ndarray,
-    axis: str,
-    min_frame_size: int,
-    sensitivity: int,
-    separator_mode: str,
-) -> list[Band]:
-    sensitivity = max(0, min(100, sensitivity))
-    dark_threshold = 10 + round(sensitivity * 0.24)
-    light_threshold = 246 - round(sensitivity * 0.16)
-    line_ratio_threshold = 0.972 - sensitivity * 0.00035
-
-    if separator_mode == "dark":
-        separator_mask = gray <= dark_threshold
-    elif separator_mode == "light":
-        separator_mask = gray >= light_threshold
-    else:
-        separator_mask = (gray <= dark_threshold) | (gray >= light_threshold)
-
-    if axis == "vertical":
-        profile = separator_mask.mean(axis=0)
-        axis_size = gray.shape[1]
-    else:
-        profile = separator_mask.mean(axis=1)
-        axis_size = gray.shape[0]
-
-    candidate_indexes = np.flatnonzero(profile >= line_ratio_threshold)
-    bands = group_indexes(candidate_indexes)
-
-    max_thickness = max(
-        2,
-        min(round(axis_size * 0.018), round(min_frame_size * 0.35)),
-    )
-    bands = [band for band in bands if band.end - band.start + 1 <= max_thickness]
-
-    return merge_close_bands(bands, min_gap=max(2, round(min_frame_size * 0.08)))
-
-
-def group_indexes(indexes: np.ndarray) -> list[Band]:
-    if indexes.size == 0:
-        return []
-
-    bands: list[Band] = []
-    start = int(indexes[0])
-    previous = int(indexes[0])
-
-    for raw_index in indexes[1:]:
-        index = int(raw_index)
-        if index <= previous + 2:
-            previous = index
-            continue
-
-        bands.append(Band(start=start, end=previous))
-        start = index
-        previous = index
-
-    bands.append(Band(start=start, end=previous))
-    return bands
-
-
-def merge_close_bands(bands: list[Band], min_gap: int) -> list[Band]:
-    if not bands:
-        return []
-
-    merged = [bands[0]]
-    for band in bands[1:]:
-        current = merged[-1]
-        if band.start - current.end <= min_gap:
-            current.end = band.end
-        else:
-            merged.append(band)
-
-    return merged
-
-
-def bands_to_segments(bands: list[Band], axis_size: int, min_frame_size: int) -> list[Segment]:
-    if not bands:
-        return [Segment(start=0, end=axis_size)]
-
-    edge_tolerance = max(3, round(axis_size * 0.008))
-    first_pixel = 0
-    last_pixel = axis_size
-    internal_bands: list[Band] = []
-
-    for band in bands:
-        if band.start <= edge_tolerance:
-            first_pixel = max(first_pixel, band.end + 1)
-        elif band.end >= axis_size - edge_tolerance - 1:
-            last_pixel = min(last_pixel, band.start)
-        else:
-            internal_bands.append(band)
-
-    segments: list[Segment] = []
-    segment_start = first_pixel
-
-    for band in internal_bands:
-        push_segment(segments, segment_start, band.start, min_frame_size)
-        segment_start = band.end + 1
-
-    push_segment(segments, segment_start, last_pixel, min_frame_size)
-    return segments
-
-
-def push_segment(segments: list[Segment], start: int, end: int, min_frame_size: int) -> None:
-    start = max(0, int(round(start)))
-    end = max(start, int(round(end)))
-
-    if end - start >= min_frame_size:
-        segments.append(Segment(start=start, end=end))
-
-
 if __name__ == "__main__":
     try:
         raise SystemExit(main())

tsconfig.json

@@ -1,41 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2017",
-    "lib": [
-      "dom",
-      "dom.iterable",
-      "esnext"
-    ],
-    "allowJs": false,
-    "skipLibCheck": true,
-    "strict": true,
-    "noEmit": true,
-    "esModuleInterop": true,
-    "module": "esnext",
-    "moduleResolution": "bundler",
-    "resolveJsonModule": true,
-    "isolatedModules": true,
-    "jsx": "react-jsx",
-    "incremental": true,
-    "plugins": [
-      {
-        "name": "next"
-      }
-    ],
-    "paths": {
-      "@/*": [
-        "./*"
-      ]
-    }
-  },
-  "include": [
-    "next-env.d.ts",
-    "**/*.ts",
-    "**/*.tsx",
-    ".next/types/**/*.ts",
-    ".next/dev/types/**/*.ts"
-  ],
-  "exclude": [
-    "node_modules"
-  ]
-}