Deploy Canny pipeline demo

README.md

@@ -1,10 +1,24 @@
 ---
-title: README
-emoji: 🌖
-colorFrom: purple
-colorTo: purple
+title: Canny Edge Detection Pipeline
+emoji: 🔍
+colorFrom: gray
+colorTo: indigo
 sdk: gradio
+sdk_version: 5.49.0
+app_file: app.py
 pinned: false
+license: mit
 ---
 
-Edit this `README.md` markdown file to author your organization card.
+# Canny Edge Detection — Step by Step
+
+Upload any image to see all seven stages of the Canny edge detector — grayscale,
+Gaussian blur, Sobel gradients (magnitude + direction), non-maximum suppression,
+double threshold, and hysteresis.
+
+This Space runs the **NumPy reference implementation**. The full project also
+includes a **custom CUDA pipeline (6 kernels) that runs 5–11× faster** than
+NumPy on the same workloads, validated to a pixel-for-pixel match (IoU = 1.0000).
+
+Source, benchmarks, and the CUDA implementation:
+**https://github.com/AneeshB20/canny-edge-detection-cuda**

app.py

@@ -0,0 +1,121 @@
+"""Gradio app for the Canny pipeline walkthrough.
+
+Live demo of the NumPy implementation. The CUDA version (5-11x faster
+depending on image size) lives in the GitHub repo:
+    https://github.com/AneeshB20/canny-edge-detection-cuda
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import gradio as gr
+import numpy as np
+
+from canny_stages import canny_pipeline_with_stages
+
+
+GITHUB_URL  = "https://github.com/AneeshB20/canny-edge-detection-cuda"
+EXAMPLES_DIR = Path(__file__).parent / "examples"
+
+EXAMPLE_IMAGES = [
+    str(EXAMPLES_DIR / "fruits.jpg"),
+    str(EXAMPLES_DIR / "shapes.png"),
+    str(EXAMPLES_DIR / "coins.png"),
+]
+
+
+# Captions for the 8 panels we display. Keep in sync with canny_stages keys.
+STAGE_CAPTIONS = {
+    "original":  "Original image (input).",
+    "grayscale": "Step 1: Convert to grayscale. Canny operates on single-channel intensity values.",
+    "gaussian":  "Step 2: Gaussian blur. Removes noise that would create false edges.",
+    "magnitude": "Step 3: Sobel gradient magnitude. Bright = strong intensity change = potential edge.",
+    "direction": "Step 4: Gradient direction. Color shows edge orientation - needed for thinning.",
+    "nms":       "Step 5: Non-maximum suppression. Thick edges thinned to 1-pixel width by keeping only local maxima along the gradient direction.",
+    "threshold": "Step 6: Double threshold. White = strong edges, gray = weak edges, black = suppressed.",
+    "edges":     "Step 7: Hysteresis edge tracking. Weak edges kept only if connected to strong edges. Final result.",
+}
+
+STAGE_ORDER = ["original", "grayscale", "gaussian", "magnitude",
+               "direction", "nms", "threshold", "edges"]
+
+
+def run_pipeline(image, sigma, low_thresh, high_thresh):
+    """Gradio callback. Returns (gallery items, info markdown)."""
+    if image is None:
+        return [], "**Upload an image first.**"
+    if high_thresh < low_thresh:
+        return [], "**`high_thresh` must be >= `low_thresh`.**"
+
+    t0 = time.perf_counter()
+    stages = canny_pipeline_with_stages(
+        image, sigma=float(sigma),
+        low_thresh=float(low_thresh), high_thresh=float(high_thresh),
+    )
+    elapsed_ms = (time.perf_counter() - t0) * 1000.0
+
+    # Substitute sigma into the blur caption so the user sees what they picked.
+    captions = dict(STAGE_CAPTIONS)
+    captions["gaussian"] = (
+        f"Step 2: Gaussian blur (sigma = {float(sigma):.2f}). "
+        "Removes noise that would create false edges."
+    )
+
+    gallery = [(stages[k], captions[k]) for k in STAGE_ORDER]
+
+    h, w = stages["edges"].shape[:2]
+    note = (
+        f"**Processing time:** {elapsed_ms:.1f} ms on {h}×{w} pixels (NumPy implementation).\n\n"
+        f"The CUDA version of this same pipeline runs **5-11x faster** than NumPy "
+        f"depending on image size - see the benchmark plots in the "
+        f"[GitHub repo]({GITHUB_URL})."
+    )
+    return gallery, note
+
+
+with gr.Blocks(theme=gr.themes.Soft(), title="Canny Edge Detection - Step by Step") as demo:
+    gr.Markdown("# Canny Edge Detection - Step by Step")
+    gr.Markdown(
+        "Upload an image to see every stage of the Canny pipeline. "
+        "Built from scratch - no `cv2.Canny()`. "
+        f"[View the source on GitHub]({GITHUB_URL})."
+    )
+
+    with gr.Row():
+        with gr.Column(scale=1):
+            input_image = gr.Image(label="Input image", type="numpy", height=300)
+            sigma       = gr.Slider(0.5, 5.0, value=1.4, step=0.1,
+                                    label="Gaussian sigma (blur strength)")
+            low_thresh  = gr.Slider(5, 100, value=25, step=1,
+                                    label="Low threshold")
+            high_thresh = gr.Slider(10, 200, value=70, step=1,
+                                    label="High threshold")
+            run_btn     = gr.Button("Run Canny pipeline", variant="primary")
+
+            gr.Examples(
+                examples=[[p] for p in EXAMPLE_IMAGES if Path(p).exists()],
+                inputs=[input_image],
+                label="Try an example",
+            )
+
+        with gr.Column(scale=2):
+            output_gallery = gr.Gallery(
+                label="Pipeline stages",
+                columns=2,
+                rows=4,
+                object_fit="contain",
+                height="auto",
+            )
+            output_info = gr.Markdown()
+
+    run_btn.click(
+        run_pipeline,
+        inputs=[input_image, sigma, low_thresh, high_thresh],
+        outputs=[output_gallery, output_info],
+    )
+
+
+if __name__ == "__main__":
+    demo.launch()

canny_stages.py

@@ -0,0 +1,190 @@
+"""Self-contained NumPy Canny implementation exposing every intermediate stage.
+
+This is a port of the project's canny_numpy.py for the Hugging Face Spaces
+demo. The math is identical to the version shipping in the GitHub repo
+(github.com/AneeshB20/canny-edge-detection-cuda) - only the wrapper changes
+so we can display the seven intermediate images instead of just the final
+binary edge map.
+"""
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+
+
+# ----------------------------------------------------------------------------
+# Pipeline primitives (vectorized NumPy).
+# ----------------------------------------------------------------------------
+
+def convolve2d(image: np.ndarray, kernel: np.ndarray) -> np.ndarray:
+    """Zero-padded 2D cross-correlation. Output shape = input shape."""
+    image = image.astype(np.float32)
+    kh, kw = kernel.shape
+    pad_h, pad_w = kh // 2, kw // 2
+    padded = np.pad(image, ((pad_h, pad_h), (pad_w, pad_w)), mode="constant")
+    H, W = image.shape
+    out = np.zeros((H, W), dtype=np.float32)
+    for i in range(kh):
+        for j in range(kw):
+            out += kernel[i, j] * padded[i:i + H, j:j + W]
+    return out
+
+
+def gaussian_kernel(size: int = 5, sigma: float = 1.0) -> np.ndarray:
+    ax = np.arange(size, dtype=np.float32) - (size // 2)
+    xx, yy = np.meshgrid(ax, ax)
+    k = np.exp(-(xx ** 2 + yy ** 2) / (2.0 * sigma ** 2))
+    k /= k.sum()
+    return k.astype(np.float32)
+
+
+def gaussian_blur(image: np.ndarray, size: int = 5, sigma: float = 1.0) -> np.ndarray:
+    return convolve2d(image, gaussian_kernel(size, sigma))
+
+
+def sobel_gradients(image: np.ndarray):
+    Kx = np.array([[-1, 0, 1], [-2, 0, 2], [-1, 0, 1]], dtype=np.float32)
+    Ky = np.array([[-1, -2, -1], [0, 0, 0], [1, 2, 1]], dtype=np.float32)
+    gx = convolve2d(image, Kx)
+    gy = convolve2d(image, Ky)
+    magnitude = np.sqrt(gx ** 2 + gy ** 2)
+    angle = np.arctan2(gy, gx)
+    return gx, gy, magnitude, angle
+
+
+def non_max_suppression(magnitude: np.ndarray, angle: np.ndarray) -> np.ndarray:
+    angle_deg = (np.rad2deg(angle) + 180.0) % 180.0
+    out = np.zeros_like(magnitude, dtype=np.float32)
+
+    center = magnitude[1:-1, 1:-1]
+    a = angle_deg[1:-1, 1:-1]
+
+    nw = magnitude[0:-2, 0:-2]; n = magnitude[0:-2, 1:-1]; ne = magnitude[0:-2, 2:]
+    w  = magnitude[1:-1, 0:-2];                            e  = magnitude[1:-1, 2:]
+    sw = magnitude[2:,   0:-2]; s = magnitude[2:,   1:-1]; se = magnitude[2:,   2:]
+
+    horiz  = (a < 22.5) | (a >= 157.5)
+    diag_a = (a >= 22.5)  & (a < 67.5)
+    vert   = (a >= 67.5)  & (a < 112.5)
+    diag_b = (a >= 112.5) & (a < 157.5)
+
+    keep = np.zeros_like(center, dtype=bool)
+    keep |= horiz  & (center >= w ) & (center >= e )
+    keep |= diag_a & (center >= nw) & (center >= se)
+    keep |= vert   & (center >= n ) & (center >= s )
+    keep |= diag_b & (center >= ne) & (center >= sw)
+
+    out[1:-1, 1:-1] = np.where(keep, center, 0.0)
+    return out
+
+
+WEAK = np.float32(75.0)
+STRONG = np.float32(255.0)
+
+
+def double_threshold(nms: np.ndarray, low_thresh: float, high_thresh: float) -> np.ndarray:
+    out = np.zeros_like(nms, dtype=np.float32)
+    out[nms >= high_thresh] = STRONG
+    out[(nms >= low_thresh) & (nms < high_thresh)] = WEAK
+    return out
+
+
+def hysteresis(classified: np.ndarray) -> np.ndarray:
+    out = classified.copy()
+    H, W = out.shape
+    padded = np.zeros((H + 2, W + 2), dtype=bool)
+    while True:
+        weak_mask = (out == WEAK)
+        if not weak_mask.any():
+            break
+        padded[1:-1, 1:-1] = (out == STRONG)
+        any_strong_neighbor = (
+            padded[0:-2, 0:-2] | padded[0:-2, 1:-1] | padded[0:-2, 2:  ] |
+            padded[1:-1, 0:-2] |                       padded[1:-1, 2:  ] |
+            padded[2:,   0:-2] | padded[2:,   1:-1] | padded[2:,   2:  ]
+        )
+        promote = weak_mask & any_strong_neighbor
+        if not promote.any():
+            break
+        out[promote] = STRONG
+    out[out == WEAK] = 0.0
+    return out
+
+
+# ----------------------------------------------------------------------------
+# Display helpers.
+# ----------------------------------------------------------------------------
+
+def _to_u8(arr: np.ndarray) -> np.ndarray:
+    """Min-max stretch to [0, 255] uint8 for display."""
+    a = arr.astype(np.float32)
+    lo, hi = float(a.min()), float(a.max())
+    if hi > lo:
+        a = (a - lo) / (hi - lo) * 255.0
+    return np.clip(a, 0, 255).astype(np.uint8)
+
+
+def _direction_to_rgb(angle: np.ndarray, magnitude: np.ndarray) -> np.ndarray:
+    """Color-map gradient direction. Hue = angle, Value = magnitude so flat
+    regions stay dark (their direction is meaningless noise)."""
+    # Angle in (-pi, pi] -> [0, 180] for OpenCV HSV (which uses H in 0..179).
+    hue = ((np.rad2deg(angle) + 180.0) % 180.0).astype(np.uint8)
+    sat = np.full_like(hue, 255)
+    val = _to_u8(magnitude)
+    hsv = np.stack([hue, sat, val], axis=-1)
+    return cv2.cvtColor(hsv, cv2.COLOR_HSV2RGB)
+
+
+# ----------------------------------------------------------------------------
+# Public entry point used by app.py.
+# ----------------------------------------------------------------------------
+
+def canny_pipeline_with_stages(
+    image_rgb: np.ndarray,
+    sigma: float = 1.4,
+    low_thresh: float = 25.0,
+    high_thresh: float = 70.0,
+    gaussian_size: int = 5,
+) -> dict[str, np.ndarray]:
+    """Run the full Canny pipeline and return every intermediate stage as a
+    display-ready uint8 image.
+
+    Args:
+        image_rgb: (H, W, 3) RGB uint8 (what Gradio hands us) OR (H, W) grayscale.
+        sigma:        std dev of the Gaussian blur.
+        low_thresh:   lower magnitude threshold.
+        high_thresh:  upper magnitude threshold.
+        gaussian_size: Gaussian kernel side (odd, default 5).
+
+    Returns:
+        dict with keys: original, grayscale, gaussian, magnitude, direction,
+        nms, threshold, edges. All values are uint8 arrays directly viewable.
+    """
+    if image_rgb.ndim == 3 and image_rgb.shape[2] == 3:
+        gray = (0.299 * image_rgb[..., 0]
+              + 0.587 * image_rgb[..., 1]
+              + 0.114 * image_rgb[..., 2]).astype(np.float32)
+        original_disp = image_rgb
+    elif image_rgb.ndim == 2:
+        gray = image_rgb.astype(np.float32)
+        original_disp = np.stack([image_rgb] * 3, axis=-1)
+    else:
+        raise ValueError(f"unexpected image shape {image_rgb.shape}")
+
+    blurred              = gaussian_blur(gray, gaussian_size, sigma)
+    gx, gy, magnitude, angle = sobel_gradients(blurred)
+    thin                 = non_max_suppression(magnitude, angle)
+    classified           = double_threshold(thin, low_thresh, high_thresh)
+    edges                = hysteresis(classified)
+
+    return {
+        "original":  original_disp,
+        "grayscale": _to_u8(gray),
+        "gaussian":  _to_u8(blurred),
+        "magnitude": _to_u8(magnitude),
+        "direction": _direction_to_rgb(angle, magnitude),
+        "nms":       _to_u8(thin),
+        "threshold": classified.astype(np.uint8),  # already 0/75/255 -> directly displayable
+        "edges":     edges.astype(np.uint8),       # already 0/255
+    }

requirements.txt

@@ -0,0 +1,3 @@
+numpy
+opencv-python-headless
+matplotlib