Deploy crack detection app

.dockerignore

@@ -0,0 +1,6 @@
+venv/
+__pycache__/
+*.pyc
+.git/
+.DS_Store
+*.output

.gitattributes

@@ -1,35 +1 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
 *.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,4 @@
+venv/
+__pycache__/
+*.pyc
+.DS_Store

Dockerfile

@@ -0,0 +1,26 @@
+# Crack Detection & Measurement — container image for Hugging Face Spaces.
+FROM python:3.12-slim
+
+# Runtime library opencv-python-headless needs.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install the CPU-only PyTorch build first — far smaller than the default
+# CUDA wheel, and Hugging Face's free hardware is CPU anyway. Pinning the
+# same versions means the torch lines in requirements.txt are then no-ops.
+RUN pip install --no-cache-dir \
+        torch==2.12.0 torchvision==0.27.0 \
+        --index-url https://download.pytorch.org/whl/cpu
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+# Hugging Face Spaces routes external traffic to this port.
+EXPOSE 7860
+CMD ["gunicorn", "--workers", "1", "--threads", "4", "--worker-class", "gthread", \
+     "--timeout", "180", "--bind", "0.0.0.0:7860", "app:app"]

README.md

@@ -1,10 +1,84 @@
 ---
-title: Crack Detection
-emoji: 🐠
-colorFrom: blue
-colorTo: pink
+title: Crack Detection And Measurement
+emoji: 🧱
+colorFrom: gray
+colorTo: red
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Crack Detection & Measurement
+
+Upload a photo of a wall; the app detects the crack, measures its width and
+length in real centimetres, and shows the segmented result.
+
+> The block above is Hugging Face Spaces configuration. It is ignored when
+> running locally and tells the Space to build from the `Dockerfile`.
+
+## Pipeline
+
+1. **Scale & rectification (ArUco)** — a printed ArUco marker in the photo
+   gives four points with known real-world coordinates. The wall plane's
+   homography is recovered and the image is warped to a fronto-parallel view
+   where **1 pixel = a fixed known mm**. This corrects camera angle and fixes
+   scale. See `aruco_scale.py`.
+2. **Segmentation (ML)** — `best_crack_model.pth`, a ResNet34-Unet, *locates*
+   the crack and produces a binary mask. See `crack_pipeline.py`.
+3. **Measurement (computer vision)** — within the ML-detected region, a
+   black-tophat operator (local intensity contrast) plus Otsu thresholding
+   re-segments the crack tightly on its actual dark pixels, not the model's
+   wider "crack zone". Width is then sampled along the crack centreline.
+   See `cv_crack.py`.
+
+Reported: **max width**, **min width** (both excluding the crack's tapering
+tips), and **total length**. The refined crack mask is shown as the
+segmented image.
+
+## Print the marker
+
+```bash
+./venv/bin/python make_marker.py     # -> aruco_marker_60mm_A4.pdf
+```
+
+Print at **100% / Actual Size** (no scaling); verify the black square is
+exactly **6.0 cm**. Tape it flat on the wall next to the crack and photograph
+wall + marker together. The app serves the PDF at `/marker`.
+
+## Run
+
+```bash
+./run.sh
+```
+
+Creates the virtualenv on first run, then serves at
+<http://127.0.0.1:5001> (port 5000 is taken by macOS AirPlay). Override with
+`PORT=8080 ./venv/bin/python app.py`.
+
+## Files
+
+| File                   | Purpose                                          |
+|------------------------|--------------------------------------------------|
+| `aruco_scale.py`       | ArUco detection, plane rectification, mm scaling |
+| `crack_pipeline.py`    | Model loading, ML segmentation, pipeline, overlay|
+| `cv_crack.py`          | Intensity-profile crack-width measurement        |
+| `make_marker.py`       | Generates the printable marker PDF               |
+| `app.py`               | Flask server (`/`, `/analyze`, `/marker`, `/health`) |
+| `templates/index.html` | Upload UI and results view                       |
+| `best_crack_model.pth` | Trained segmentation weights                     |
+
+## API
+
+`POST /analyze` — multipart form, field `image`. Returns JSON: base64 PNG
+`overlay`, a `measurements` object (`summary` / `summary_mm` with max width,
+min width, total length), and an `aruco` object describing marker detection.
+
+## Deploying
+
+The app is Flask + PyTorch (CPU). For a public deployment:
+
+- Replace the Flask dev server with a production server (`gunicorn`).
+- Pin dependency versions in `requirements.txt`.
+- It needs ~1.5–2 GB RAM (PyTorch + the 98 MB model).
+- Good hosts: **Hugging Face Spaces** (free, built for ML demos), or a Docker
+  container on Fly.io / Render / Railway.

app.py

@@ -0,0 +1,92 @@
+"""Flask web app for crack detection and measurement."""
+
+from __future__ import annotations
+
+import base64
+import io
+import os
+
+import cv2
+import numpy as np
+from flask import Flask, jsonify, render_template, request, send_file
+from PIL import Image
+
+import aruco_scale
+import crack_pipeline
+
+app = Flask(__name__)
+app.config["MAX_CONTENT_LENGTH"] = 25 * 1024 * 1024  # 25 MB upload cap
+
+
+def _read_image(file_storage) -> np.ndarray:
+    """Decode an uploaded file into an RGB numpy array."""
+    image = Image.open(io.BytesIO(file_storage.read())).convert("RGB")
+    return np.array(image)
+
+
+def _encode_png(image_rgb: np.ndarray) -> str:
+    """Encode an RGB array as a base64 PNG data URI."""
+    bgr = cv2.cvtColor(image_rgb, cv2.COLOR_RGB2BGR)
+    ok, buf = cv2.imencode(".png", bgr)
+    if not ok:
+        raise RuntimeError("PNG encoding failed")
+    return "data:image/png;base64," + base64.b64encode(buf).decode("ascii")
+
+
+@app.route("/")
+def index():
+    return render_template("index.html")
+
+
+@app.route("/health")
+def health():
+    return jsonify(status="ok")
+
+
+@app.route("/marker")
+def marker():
+    """Serve the printable ArUco marker PDF (generated by make_marker.py)."""
+    size = int(aruco_scale.DEFAULT_MARKER_LENGTH_MM)
+    pdf = os.path.join(os.path.dirname(__file__), f"aruco_marker_{size}mm_A4.pdf")
+    if not os.path.exists(pdf):
+        return jsonify(error="Marker PDF missing - run: python make_marker.py"), 404
+    return send_file(pdf, mimetype="application/pdf")
+
+
+@app.route("/analyze", methods=["POST"])
+def analyze():
+    """Analyse an upload and return only the computer-vision result.
+
+    Scale always comes from the ArUco marker (no manual options); the model
+    threshold is fixed. The response carries the CV overlay and the CV
+    measurement (intensity-based, refined within the ML-detected region).
+    """
+    if "image" not in request.files or request.files["image"].filename == "":
+        return jsonify(error="No image uploaded"), 400
+
+    try:
+        image_rgb = _read_image(request.files["image"])
+    except Exception:
+        return jsonify(error="Could not read the uploaded image"), 400
+
+    result = crack_pipeline.analyze(
+        image_rgb, use_aruco=True,
+        marker_length_mm=aruco_scale.DEFAULT_MARKER_LENGTH_MM,
+    )
+    overlay = result["overlay"]
+
+    return jsonify(
+        overlay=_encode_png(overlay),
+        measurements=result["measurements"],
+        aruco=result["aruco"],
+        image_size={"width": overlay.shape[1], "height": overlay.shape[0]},
+    )
+
+
+if __name__ == "__main__":
+    # Port 5000 is taken by macOS AirPlay Receiver, so default to 5001.
+    port = int(os.environ.get("PORT", 5001))
+    print("Loading crack segmentation model...")
+    crack_pipeline.get_model()
+    print(f"Model ready. Open http://127.0.0.1:{port}")
+    app.run(host="127.0.0.1", port=port, debug=False)

aruco_scale.py

@@ -0,0 +1,142 @@
+"""ArUco-based planar rectification and metric scaling.
+
+A single ArUco marker lying flat on the wall provides four image points
+whose real-world coordinates are known (a square of side `marker_length_mm`).
+That is enough to recover the homography of the wall plane, so the image can
+be warped to a fronto-parallel ("top-down") view in which **one pixel equals
+a fixed, known number of millimetres** everywhere.
+
+Crack measurements taken on that rectified image are therefore correct in
+real-world units regardless of the camera angle.
+
+Marker convention (must match the printed tag from `make_marker.py`):
+    dictionary = DICT_4X4_50, any marker ID is accepted.
+"""
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+
+# Printed tag and detector must agree on the dictionary.
+ARUCO_DICT = cv2.aruco.DICT_4X4_50
+DEFAULT_MARKER_ID = 0
+DEFAULT_MARKER_LENGTH_MM = 60.0
+
+# Upper bound on the rectified canvas; px_per_mm is reduced to respect it.
+MAX_CANVAS_PX = 2600
+
+
+def get_dictionary():
+    return cv2.aruco.getPredefinedDictionary(ARUCO_DICT)
+
+
+def _detector() -> "cv2.aruco.ArucoDetector":
+    params = cv2.aruco.DetectorParameters()
+    # Sub-pixel corner refinement — critical for measurement accuracy.
+    params.cornerRefinementMethod = cv2.aruco.CORNER_REFINE_SUBPIX
+    return cv2.aruco.ArucoDetector(get_dictionary(), params)
+
+
+def detect_markers(image_rgb: np.ndarray) -> list[dict]:
+    """Detect every ArUco marker. Returns [{id, corners(4x2 float32)}, ...].
+
+    Corner order per marker: top-left, top-right, bottom-right, bottom-left.
+    """
+    gray = cv2.cvtColor(image_rgb, cv2.COLOR_RGB2GRAY)
+    corners, ids, _ = _detector().detectMarkers(gray)
+    if ids is None:
+        return []
+    return [{"id": int(i), "corners": c.reshape(4, 2).astype(np.float32)}
+            for c, i in zip(corners, ids.flatten())]
+
+
+def _marker_side_pixels(corners: np.ndarray) -> float:
+    """Average side length (px) of the marker quad in the image."""
+    edges = [np.linalg.norm(corners[i] - corners[(i + 1) % 4]) for i in range(4)]
+    return float(np.mean(edges))
+
+
+def rectify_to_metric(image_rgb: np.ndarray,
+                      marker_length_mm: float = DEFAULT_MARKER_LENGTH_MM,
+                      marker_id: int | None = None) -> dict | None:
+    """Warp the image to a fronto-parallel, metric-scaled view.
+
+    Parameters
+    ----------
+    image_rgb        : input RGB image.
+    marker_length_mm : printed side length of the marker's black square.
+    marker_id        : which marker to use; None -> first one detected.
+
+    Returns
+    -------
+    dict with:
+        image        : rectified RGB image (uniform scale).
+        mm_per_pixel : millimetres represented by one pixel of `image`.
+        marker_id    : the marker that was used.
+        homography   : 3x3 image -> rectified transform.
+    or None if no usable marker was found.
+    """
+    markers = detect_markers(image_rgb)
+    if not markers:
+        return None
+
+    if marker_id is not None:
+        markers = [m for m in markers if m["id"] == marker_id]
+        if not markers:
+            return None
+    marker = markers[0]
+    src = marker["corners"]
+
+    # Native resolution: keep the marker roughly its original pixel size so
+    # rectification neither over- nor under-samples the wall.
+    side_px = _marker_side_pixels(src)
+    if side_px < 8:  # marker too small to scale from reliably
+        return None
+    px_per_mm = side_px / marker_length_mm
+
+    # The marker maps to a square of `side_px` pixels at the canvas origin.
+    s = marker_length_mm * px_per_mm
+    dst = np.array([[0, 0], [s, 0], [s, s], [0, s]], dtype=np.float32)
+    homography = cv2.getPerspectiveTransform(src, dst)
+
+    # Where do the four image corners land? -> canvas size + translation.
+    h, w = image_rgb.shape[:2]
+    img_corners = np.array([[[0, 0], [w, 0], [w, h], [0, h]]], dtype=np.float32)
+    warped = cv2.perspectiveTransform(img_corners, homography)[0]
+    min_xy = warped.min(axis=0)
+    max_xy = warped.max(axis=0)
+    out_w = max_xy[0] - min_xy[0]
+    out_h = max_xy[1] - min_xy[1]
+
+    if not np.isfinite([out_w, out_h]).all() or out_w < 1 or out_h < 1:
+        return None  # near-degenerate (extreme viewing angle)
+
+    # Shift the warped content fully into positive coordinates.
+    translate = np.array([[1, 0, -min_xy[0]],
+                          [0, 1, -min_xy[1]],
+                          [0, 0, 1]], dtype=np.float64)
+    homography = translate @ homography
+
+    # Clamp the canvas size; shrink px_per_mm to match if needed.
+    longest = max(out_w, out_h)
+    if longest > MAX_CANVAS_PX:
+        shrink = MAX_CANVAS_PX / longest
+        scale = np.array([[shrink, 0, 0], [0, shrink, 0], [0, 0, 1]])
+        homography = scale @ homography
+        out_w *= shrink
+        out_h *= shrink
+        px_per_mm *= shrink
+
+    out_size = (int(np.ceil(out_w)), int(np.ceil(out_h)))
+    rectified = cv2.warpPerspective(image_rgb, homography, out_size,
+                                    flags=cv2.INTER_CUBIC,
+                                    borderMode=cv2.BORDER_CONSTANT,
+                                    borderValue=(127, 127, 127))
+
+    return {
+        "image": rectified,
+        "mm_per_pixel": 1.0 / px_per_mm,
+        "marker_id": marker["id"],
+        "homography": homography,
+    }

best_crack_model.pth

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7edb53b12afa4bd3cfb8febcbe2c93270c2ff7b4c9bbd54079eb101d4a44ef70
+size 97921935

crack_pipeline.py

@@ -0,0 +1,352 @@
+"""Crack detection + measurement pipeline.
+
+Stages
+------
+0. Scale         : an ArUco marker (see aruco_scale.py) rectifies the wall
+                   plane and fixes a known mm-per-pixel scale.
+1. Segmentation  : ResNet34-Unet (segmentation_models_pytorch) locates the
+                   crack -> binary mask.
+2. Measurement   : computer vision (see cv_crack.py) refines the crack from
+                   intensity contrast within the ML region; width is sampled
+                   along the ML centreline, length is the centreline length.
+
+Widths are in *pixels* until multiplied by the ArUco `mm_per_pixel` scale.
+"""
+
+from __future__ import annotations
+
+import threading
+
+import cv2
+import numpy as np
+import torch
+import segmentation_models_pytorch as smp
+from skimage.morphology import skeletonize
+
+import aruco_scale
+import cv_crack
+
+MODEL_PATH = "best_crack_model.pth"
+
+# Encoder was pretrained on ImageNet, so inference uses ImageNet stats.
+_IMAGENET_MEAN = np.array([0.485, 0.456, 0.406], dtype=np.float32)
+_IMAGENET_STD = np.array([0.229, 0.224, 0.225], dtype=np.float32)
+
+# Longest image side fed to the network. Larger -> finer cracks, more memory.
+MAX_SIDE = 1024
+# Encoder downsamples by 32, so network input dims must be multiples of 32.
+_STRIDE = 32
+
+_model: torch.nn.Module | None = None
+_model_lock = threading.Lock()
+
+
+def get_model() -> torch.nn.Module:
+    """Load the segmentation model once and cache it (thread-safe)."""
+    global _model
+    if _model is None:
+        with _model_lock:
+            if _model is None:
+                model = smp.Unet(
+                    encoder_name="resnet34",
+                    encoder_weights=None,
+                    in_channels=3,
+                    classes=1,
+                    activation=None,
+                )
+                state = torch.load(MODEL_PATH, map_location="cpu")
+                if isinstance(state, dict) and "state_dict" in state:
+                    state = state["state_dict"]
+                model.load_state_dict(state)
+                model.eval()
+                _model = model
+    return _model
+
+
+# --------------------------------------------------------------------------
+# Stage 1 - segmentation
+# --------------------------------------------------------------------------
+def _preprocess(image_rgb: np.ndarray):
+    """Resize within MAX_SIDE and pad to a multiple of the encoder stride."""
+    h, w = image_rgb.shape[:2]
+    scale = min(1.0, MAX_SIDE / max(h, w))
+    nh, nw = max(1, round(h * scale)), max(1, round(w * scale))
+    resized = cv2.resize(image_rgb, (nw, nh), interpolation=cv2.INTER_AREA)
+
+    pad_h = (-nh) % _STRIDE
+    pad_w = (-nw) % _STRIDE
+    padded = cv2.copyMakeBorder(resized, 0, pad_h, 0, pad_w, cv2.BORDER_REFLECT)
+
+    tensor = (padded.astype(np.float32) / 255.0 - _IMAGENET_MEAN) / _IMAGENET_STD
+    tensor = torch.from_numpy(tensor).permute(2, 0, 1).unsqueeze(0)
+    return tensor, (nh, nw)
+
+
+def segment(image_rgb: np.ndarray, threshold: float = 0.5) -> tuple[np.ndarray, np.ndarray]:
+    """Run the network on an RGB image.
+
+    Returns
+    -------
+    mask  : uint8 array (0/255) at the original image resolution.
+    proba : float32 crack-probability map at the original resolution.
+    """
+    h, w = image_rgb.shape[:2]
+    tensor, (nh, nw) = _preprocess(image_rgb)
+
+    model = get_model()
+    with torch.no_grad():
+        logits = model(tensor)
+        proba = torch.sigmoid(logits)[0, 0].cpu().numpy()
+
+    proba = proba[:nh, :nw]  # drop padding
+    proba = cv2.resize(proba, (w, h), interpolation=cv2.INTER_LINEAR)
+    mask = (proba >= threshold).astype(np.uint8) * 255
+    return mask, proba
+
+
+# --------------------------------------------------------------------------
+# Stage 2 - measurement
+# --------------------------------------------------------------------------
+def _skeleton_length_px(skeleton: np.ndarray) -> float:
+    """Length of a 1-px skeleton, counting diagonal steps as sqrt(2).
+
+    Each pair of 8-connected skeleton pixels contributes one step; the sum of
+    step lengths is halved because every step is counted from both ends.
+    """
+    ys, xs = np.nonzero(skeleton)
+    if len(ys) == 0:
+        return 0.0
+    if len(ys) == 1:
+        return 1.0
+
+    total = 0.0
+    sk = skeleton.astype(bool)
+    h, w = sk.shape
+    for y, x in zip(ys, xs):
+        for dy, dx in ((-1, -1), (-1, 0), (-1, 1), (0, -1),
+                       (0, 1), (1, -1), (1, 0), (1, 1)):
+            ny, nx = y + dy, x + dx
+            if 0 <= ny < h and 0 <= nx < w and sk[ny, nx]:
+                total += 1.4142135623730951 if (dy and dx) else 1.0
+    return total / 2.0
+
+
+def measure_crack(ml_mask: np.ndarray, cv_mask: np.ndarray,
+                  mm_per_pixel: float | None = None) -> dict:
+    """Final crack measurement combining the ML and CV masks.
+
+    Length comes from the *ML* mask's skeleton — it is continuous and
+    captures the crack's full extent. Width is sampled from the *CV* mask
+    (intensity-based, tight on the true dark crack) along that same
+    centreline, so widths reflect the real crack rather than the model's
+    wider "crack zone". The crack's tapering tips are excluded from the
+    width statistics.
+    """
+    ml = ml_mask > 0
+    skeleton = skeletonize(ml)
+    length_px = _skeleton_length_px(skeleton)
+    n_cracks = int(cv2.connectedComponents(ml.astype(np.uint8))[0]) - 1
+
+    cv_dist = cv2.distanceTransform((cv_mask > 0).astype(np.uint8),
+                                    cv2.DIST_L2, 5)
+    ys, xs = np.nonzero(skeleton)
+    max_w = min_w = 0.0
+    max_xy = min_xy = None
+
+    if ys.size:
+        # CV-measured width at every point of the ML centreline.
+        widths = 2.0 * cv_dist[ys, xs]
+        in_cv = widths > 0
+        typical = float(np.median(widths[in_cv])) if in_cv.any() else 0.0
+        margin = max(4.0, 1.5 * typical)
+
+        # Trust a width sample only away from (a) the crack's true tips,
+        # where it tapers to zero, and (b) gaps where the CV mask did not
+        # resolve the crack. Keep centreline samples farther than `margin`
+        # from any such point.
+        neigh = cv2.filter2D(skeleton.astype(np.uint8), -1,
+                             np.ones((3, 3), np.float32),
+                             borderType=cv2.BORDER_CONSTANT)
+        endpoints = skeleton & (neigh <= 2)
+        avoid = np.ones(skeleton.shape, np.uint8)   # 0 marks tips / gaps
+        avoid[endpoints] = 0
+        avoid[ys[~in_cv], xs[~in_cv]] = 0
+        if (avoid == 0).any():
+            d_safe = cv2.distanceTransform(avoid, cv2.DIST_L2, 5)
+            safe = d_safe[ys, xs] > margin
+        else:
+            safe = np.ones(widths.shape, bool)
+
+        valid = in_cv & safe
+        if not valid.any():            # crack too short / fragmented to trim
+            valid = in_cv
+        if valid.any():
+            wv, xv, yv = widths[valid], xs[valid], ys[valid]
+            i_hi, i_lo = int(np.argmax(wv)), int(np.argmin(wv))
+            max_w, min_w = float(wv[i_hi]), float(wv[i_lo])
+            max_xy = [int(xv[i_hi]), int(yv[i_hi])]
+            min_xy = [int(xv[i_lo]), int(yv[i_lo])]
+
+    summary = {
+        "num_cracks": n_cracks,
+        "total_length_px": round(length_px, 1),
+        "max_width_px": round(max_w, 2),
+        "min_width_px": round(min_w, 2),
+    }
+    component = {
+        "id": 1,
+        "max_width_px": round(max_w, 2),
+        "min_width_px": round(min_w, 2),
+        "max_width_xy": max_xy,
+        "min_width_xy": min_xy,
+    }
+    result = {
+        "scale_known": mm_per_pixel is not None,
+        "mm_per_pixel": mm_per_pixel,
+        "summary": summary,
+        "components": [component],
+    }
+    if mm_per_pixel is not None:
+        result["summary_mm"] = {
+            "num_cracks": n_cracks,
+            "total_length_mm": round(length_px * mm_per_pixel, 2),
+            "max_width_mm": round(max_w * mm_per_pixel, 2),
+            "min_width_mm": round(min_w * mm_per_pixel, 2),
+        }
+        component["max_width_mm"] = round(max_w * mm_per_pixel, 2)
+        component["min_width_mm"] = round(min_w * mm_per_pixel, 2)
+    return result
+
+
+# --------------------------------------------------------------------------
+# Visualisation
+# --------------------------------------------------------------------------
+_FONT = cv2.FONT_HERSHEY_SIMPLEX
+_ORANGE = (255, 140, 0)
+_GREEN = (0, 230, 0)     # widest point
+_BLUE = (40, 130, 255)   # narrowest point
+
+
+def _put_label(img: np.ndarray, text: str, org: tuple[int, int],
+               color: tuple, scale: float = 0.6) -> None:
+    """Draw text with a black outline so it stays readable on any background."""
+    cv2.putText(img, text, org, _FONT, scale, (0, 0, 0), 4, cv2.LINE_AA)
+    cv2.putText(img, text, org, _FONT, scale, color, 2, cv2.LINE_AA)
+
+
+def _mark_width(img: np.ndarray, xy: list, width_px: float,
+                width_mm: float | None, color: tuple, prefix: str) -> None:
+    """Mark a width point with its largest-inscribed circle, cross and label."""
+    radius = max(3, int(round(width_px / 2)))
+    cv2.circle(img, tuple(xy), radius, color, 2, cv2.LINE_AA)
+    cv2.drawMarker(img, tuple(xy), color, cv2.MARKER_CROSS, 18, 2)
+    value = f"{width_mm:.1f} mm" if width_mm is not None else f"{width_px:.0f} px"
+    _put_label(img, f"{prefix} {value}", (xy[0] + radius + 6, xy[1] + 5),
+               color, 0.6)
+
+
+def make_overlay(image_rgb: np.ndarray, mask: np.ndarray,
+                 measurements: dict | None = None,
+                 annotate_each: bool = True) -> np.ndarray:
+    """Draw the crack mask, skeleton, tight outline and max-width markers.
+
+    `annotate_each` adds a `#id` label per crack (useful for the ML overlay,
+    which has a matching per-crack table; off for the CV overlay, which can
+    fragment into many pieces and would otherwise be cluttered).
+    """
+    overlay = image_rgb.copy()
+    crack = mask > 0
+
+    red = np.zeros_like(overlay)
+    red[crack] = (255, 40, 40)
+    overlay = cv2.addWeighted(overlay, 1.0, red, 0.5, 0)
+
+    overlay[skeletonize(crack)] = (255, 255, 0)
+
+    # Outline the crack precisely with its contour (hugs every branch) instead
+    # of an axis-aligned box, which for a thin diagonal crack would enclose a
+    # large mostly-empty area.
+    contours, _ = cv2.findContours(crack.astype(np.uint8),
+                                   cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+    cv2.drawContours(overlay, contours, -1, _ORANGE, 2, cv2.LINE_AA)
+
+    if measurements:
+        comps = measurements.get("components", [])
+
+        if annotate_each:
+            for c in comps:
+                if c.get("centroid"):
+                    cx, cy = c["centroid"]
+                    _put_label(overlay, f"#{c['id']}", (cx + 5, cy),
+                               _ORANGE, 0.55)
+
+        # Mark the globally widest and narrowest points. The distance-transform
+        # value at each is the radius of the largest circle fitting inside the
+        # crack there, so the drawn circle's diameter *is* that width.
+        widest = max(comps, key=lambda c: c["max_width_px"], default=None)
+        if widest and widest.get("max_width_xy"):
+            _mark_width(overlay, widest["max_width_xy"], widest["max_width_px"],
+                        widest.get("max_width_mm"), _GREEN, "max W")
+
+        narrowable = [c for c in comps
+                      if c.get("min_width_xy") and c["max_width_px"] > 0]
+        narrowest = min(narrowable, key=lambda c: c["min_width_px"],
+                        default=None)
+        if narrowest:
+            _mark_width(overlay, narrowest["min_width_xy"],
+                        narrowest["min_width_px"],
+                        narrowest.get("min_width_mm"), _BLUE, "min W")
+    return overlay
+
+
+def analyze(image_rgb: np.ndarray, threshold: float = 0.5,
+            mm_per_pixel: float | None = None, use_aruco: bool = False,
+            marker_length_mm: float = aruco_scale.DEFAULT_MARKER_LENGTH_MM) -> dict:
+    """Full pipeline: (optional ArUco rectify) -> segment -> measure -> overlay.
+
+    Parameters
+    ----------
+    image_rgb        : input RGB image.
+    threshold        : crack probability cutoff.
+    mm_per_pixel     : manual scale; ignored when `use_aruco` succeeds.
+    use_aruco        : if True, detect an ArUco marker, rectify the wall plane
+                       and derive the scale automatically.
+    marker_length_mm : printed side length of the marker's black square.
+
+    The returned dict includes an `aruco` field describing what happened with
+    marker detection (None when `use_aruco` is False).
+    """
+    aruco_info = None
+    if use_aruco:
+        rect = aruco_scale.rectify_to_metric(image_rgb, marker_length_mm)
+        if rect is not None:
+            # Work on the rectified, fronto-parallel image: scale is now
+            # uniform and known, so measurements come out in real units.
+            image_rgb = rect["image"]
+            mm_per_pixel = rect["mm_per_pixel"]
+            aruco_info = {
+                "detected": True,
+                "marker_id": rect["marker_id"],
+                "marker_length_mm": marker_length_mm,
+                "mm_per_pixel": round(mm_per_pixel, 5),
+            }
+        else:
+            aruco_info = {
+                "detected": False,
+                "message": "No ArUco marker detected - reporting pixel "
+                           "measurements. Ensure the printed marker is fully "
+                           "visible, flat and in focus.",
+            }
+
+    # ML segmentation locates the crack.
+    mask, proba = segment(image_rgb, threshold=threshold)
+    # Computer vision refines the crack from intensity contrast within the
+    # ML region; width is then measured along the ML centreline.
+    cv_mask = cv_crack.segment_cv(image_rgb, mask)
+    measurements = measure_crack(mask, cv_mask, mm_per_pixel=mm_per_pixel)
+    overlay = make_overlay(image_rgb, cv_mask, measurements,
+                           annotate_each=False)
+
+    return {"mask": mask, "cv_mask": cv_mask, "proba": proba,
+            "overlay": overlay, "measurements": measurements,
+            "aruco": aruco_info}

cv_crack.py

@@ -0,0 +1,96 @@
+"""Computer-vision crack refinement.
+
+The ML segmenter reliably *locates* cracks but tends to over-segment their
+*width* — it marks a generous "crack zone" rather than the exact dark pixels.
+This module re-segments the crack *inside* the ML region using classical
+intensity-contrast cues, producing a mask that is tight on the true crack
+while still covering its whole length.
+
+Method
+------
+1. Restrict work to the ML mask's neighbourhood (ROI). This rejects shadows,
+   stains, the ArUco marker, the hand, etc. — anything dark elsewhere.
+2. CLAHE equalisation flattens uneven lighting inside the ROI.
+3. A black-tophat operator measures, per pixel, how much darker it is than
+   its local surroundings — a local intensity gradient against the
+   background. A real crack scores high; the lighter halo the ML mask
+   included scores low.
+4. Otsu's threshold on that response (over ROI pixels only) separates the
+   true dark crack core from that halo.
+5. Only components overlapping the ML detection are kept.
+"""
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+
+
+def _odd(value: float) -> int:
+    """Nearest odd integer >= 1 (valid structuring-element / kernel size)."""
+    v = max(1, int(round(value)))
+    return v if v % 2 == 1 else v + 1
+
+
+def _keep_overlapping(mask: np.ndarray, reference: np.ndarray) -> np.ndarray:
+    """Keep only `mask` components that overlap the `reference` mask."""
+    n, labels = cv2.connectedComponents((mask > 0).astype(np.uint8))
+    out = np.zeros_like(mask)
+    ref_b = reference > 0
+    for label in range(1, n):
+        comp = labels == label
+        if np.logical_and(comp, ref_b).any():
+            out[comp] = 255
+    return out
+
+
+def segment_cv(image_rgb: np.ndarray, ml_mask: np.ndarray) -> np.ndarray:
+    """Refine the crack inside the ML region with intensity-contrast CV.
+
+    Parameters
+    ----------
+    image_rgb : the (rectified) RGB image the ML mask was produced from.
+    ml_mask   : uint8 ML crack mask (0/255).
+
+    Returns
+    -------
+    uint8 mask (0/255), tighter on the true dark crack than `ml_mask`.
+    """
+    gray = cv2.cvtColor(image_rgb, cv2.COLOR_RGB2GRAY)
+    ml = (ml_mask > 0).astype(np.uint8)
+    if ml.sum() == 0:
+        return np.zeros(gray.shape, np.uint8)
+
+    # Crack scale: half the ML crack width, in pixels.
+    dist = cv2.distanceTransform(ml, cv2.DIST_L2, 5)
+    half_width = max(2.0, float(dist.max()))
+
+    # Search region: the ML mask plus a small safety margin, so the CV step
+    # can settle on the true (narrower) crack even if ML clipped an edge.
+    margin = _odd(max(5.0, half_width * 0.8))
+    roi = cv2.dilate(ml * 255, cv2.getStructuringElement(
+        cv2.MORPH_ELLIPSE, (margin, margin)))
+    roi_b = roi > 0
+
+    # Flatten lighting, then black-tophat = local darkness vs background.
+    gray_eq = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8)).apply(gray)
+    ksize = _odd(max(9.0, half_width * 4.0))
+    kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (ksize, ksize))
+    blackhat = cv2.morphologyEx(gray_eq, cv2.MORPH_BLACKHAT, kernel)
+
+    # Otsu split of the contrast response, over ROI pixels only.
+    vals = blackhat[roi_b]
+    if vals.size < 20:
+        return np.zeros(gray.shape, np.uint8)
+    thr, _ = cv2.threshold(vals.reshape(-1, 1), 0, 255,
+                           cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+    cv_mask = ((blackhat >= max(thr, 1)) & roi_b).astype(np.uint8) * 255
+
+    # Tidy: drop isolated specks, then bridge small gaps along the crack so
+    # it stays continuous over its whole length.
+    cv_mask = cv2.morphologyEx(cv_mask, cv2.MORPH_OPEN,
+        cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3)))
+    cv_mask = cv2.morphologyEx(cv_mask, cv2.MORPH_CLOSE,
+        cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (7, 7)))
+
+    return _keep_overlapping(cv_mask, ml)

make_marker.py

@@ -0,0 +1,120 @@
+"""Generate a printable ArUco marker for wall measurement.
+
+Run:  ./venv/bin/python make_marker.py
+Output:  aruco_marker_60mm_A4.pdf  (and a .png preview)
+
+Print the PDF at 100% / "Actual size" (no scaling, no "fit to page"). Then
+verify with a ruler that the printed black square is exactly 6.0 cm across.
+If it is off, scaling was applied — reprint, or pass the real measured size
+to the app's "marker size" field.
+"""
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+from PIL import Image, ImageDraw, ImageFont
+
+import aruco_scale
+
+DPI = 300
+MM_PER_INCH = 25.4
+MARKER_MM = aruco_scale.DEFAULT_MARKER_LENGTH_MM   # 120 mm
+MARKER_ID = aruco_scale.DEFAULT_MARKER_ID          # 0
+
+A4_W_MM, A4_H_MM = 210.0, 297.0
+
+
+def mm_to_px(mm: float) -> int:
+    return int(round(mm / MM_PER_INCH * DPI))
+
+
+def _font(size_px: int) -> ImageFont.FreeTypeFont:
+    for path in ("/System/Library/Fonts/Supplemental/Arial.ttf",
+                 "/System/Library/Fonts/Helvetica.ttc",
+                 "/Library/Fonts/Arial.ttf"):
+        try:
+            return ImageFont.truetype(path, size_px)
+        except OSError:
+            continue
+    return ImageFont.load_default()
+
+
+def build_marker_image(side_px: int) -> Image.Image:
+    """Render the ArUco marker (6x6 modules) crisply at `side_px`."""
+    modules = 6  # 4x4 data + 1-module black border each side
+    hires = modules * 200
+    raw = cv2.aruco.generateImageMarker(aruco_scale.get_dictionary(),
+                                        MARKER_ID, hires)
+    return Image.fromarray(raw).resize((side_px, side_px), Image.NEAREST)
+
+
+def main() -> None:
+    page = Image.new("RGB", (mm_to_px(A4_W_MM), mm_to_px(A4_H_MM)), "white")
+    draw = ImageDraw.Draw(page)
+    cx = page.width // 2
+
+    title = _font(mm_to_px(7))
+    body = _font(mm_to_px(4.2))
+    small = _font(mm_to_px(3.4))
+
+    def centered(y, text, font, fill="black"):
+        w = draw.textlength(text, font=font)
+        draw.text((cx - w / 2, y), text, font=font, fill=fill)
+
+    y = mm_to_px(15)
+    centered(y, "Crack Measurement - ArUco Scale Marker", title)
+    y += mm_to_px(11)
+    centered(y, "1. Print this page at 100% / Actual Size (no scaling).", body)
+    y += mm_to_px(6)
+    centered(y, "2. Tape it FLAT on the wall, beside the crack, facing the camera.", body)
+    y += mm_to_px(6)
+    centered(y, "3. Photograph wall + marker together, then upload to the app.", body)
+    y += mm_to_px(10)
+
+    # The marker, with a white quiet zone the printed page already provides.
+    side_px = mm_to_px(MARKER_MM)
+    marker = build_marker_image(side_px)
+    mx, my = cx - side_px // 2, y
+    page.paste(marker, (mx, my))
+
+    # Dimension callout under the marker.
+    yb = my + side_px + mm_to_px(4)
+    draw.line([(mx, yb), (mx + side_px, yb)], fill="black", width=3)
+    for ex in (mx, mx + side_px):
+        draw.line([(ex, yb - mm_to_px(2)), (ex, yb + mm_to_px(2))],
+                  fill="black", width=3)
+    centered(yb + mm_to_px(3),
+             f"Black square = {MARKER_MM:.0f} mm  ({MARKER_MM/10:.1f} cm)", body)
+
+    y = yb + mm_to_px(14)
+    centered(y, f"Dictionary: DICT_4X4_50      Marker ID: {MARKER_ID}", small)
+    y += mm_to_px(10)
+
+    # Independent 100 mm print-scale check ruler.
+    centered(y, "Print check - this line must measure exactly 10.0 cm:", small)
+    y += mm_to_px(6)
+    ruler_px = mm_to_px(100.0)
+    rx = cx - ruler_px // 2
+    draw.line([(rx, y), (rx + ruler_px, y)], fill="black", width=3)
+    for i in range(11):  # cm ticks
+        tx = rx + mm_to_px(10.0 * i)
+        th = mm_to_px(3.5 if i % 5 == 0 else 2.0)
+        draw.line([(tx, y - th), (tx, y + th)], fill="black", width=2)
+    y += mm_to_px(8)
+    centered(y, "If it is not 10.0 cm, your printer rescaled the page - "
+                "reprint without scaling.", small)
+
+    # Save the PDF as a 1-bit (black/white) page: lossless CCITT compression,
+    # crisp marker edges, small file. The page is pure line art so nothing
+    # is lost. dither=NONE keeps text edges clean instead of speckled.
+    stem = f"aruco_marker_{MARKER_MM:.0f}mm_A4"
+    page.save(f"{stem}.png", dpi=(DPI, DPI))
+    page.convert("1", dither=Image.NONE).save(
+        f"{stem}.pdf", resolution=float(DPI))
+    print(f"Wrote {stem}.pdf  and  {stem}.png")
+    print(f"Marker: DICT_4X4_50  id={MARKER_ID}  side={MARKER_MM:.0f} mm")
+
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -0,0 +1,9 @@
+torch==2.12.0
+torchvision==0.27.0
+segmentation-models-pytorch==0.5.0
+opencv-python-headless==4.13.0.92
+numpy==2.4.6
+pillow==12.2.0
+scikit-image==0.26.0
+flask==3.1.3
+gunicorn==23.0.0

run.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Start the crack detection web app.
+set -e
+cd "$(dirname "$0")"
+
+if [ ! -d venv ]; then
+  echo "Creating virtualenv..."
+  python3.12 -m venv venv
+  ./venv/bin/pip install -q -r requirements.txt
+fi
+
+exec ./venv/bin/python app.py

templates/index.html

@@ -0,0 +1,150 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Crack Detection &amp; Measurement</title>
+<style>
+  :root { --bg:#0f1419; --panel:#1a2129; --line:#2c3742; --accent:#ff6b4a;
+          --text:#e6edf3; --muted:#8b98a5; }
+  * { box-sizing:border-box; margin:0; padding:0; }
+  body { background:var(--bg); color:var(--text); font:15px/1.5 system-ui,sans-serif; }
+  header { padding:22px 28px; border-bottom:1px solid var(--line); }
+  header h1 { font-size:20px; font-weight:600; }
+  header p { color:var(--muted); font-size:13px; margin-top:3px; }
+  .wrap { max-width:1000px; margin:0 auto; padding:24px 28px; }
+  .panel { background:var(--panel); border:1px solid var(--line);
+           border-radius:10px; padding:20px; margin-bottom:20px; }
+  #drop { border:2px dashed var(--line); border-radius:10px; padding:42px;
+          text-align:center; cursor:pointer; transition:.15s; }
+  #drop:hover, #drop.over { border-color:var(--accent); background:#202935; }
+  #drop p { color:var(--muted); }
+  a { color:var(--accent); }
+  .note { color:var(--muted); font-size:12px; margin-top:14px; }
+  #status { margin-top:10px; font-size:13px; }
+  #status.err { color:#ff6b4a; }
+  #status.busy { color:var(--accent); }
+  figure { border:1px solid var(--line); border-radius:8px; overflow:hidden; }
+  figcaption { padding:8px 12px; font-size:12px; color:var(--muted);
+               background:var(--bg); }
+  figure img { width:100%; display:block; }
+  .cards { display:grid; grid-template-columns:repeat(3,1fr); gap:12px;
+           margin-top:16px; }
+  .card { background:var(--bg); border:1px solid var(--line); border-radius:8px;
+          padding:16px; text-align:center; }
+  .card .v { font-size:24px; font-weight:700; }
+  .card .k { font-size:12px; color:var(--muted); margin-top:3px;
+             text-transform:uppercase; letter-spacing:.04em; }
+  h2 { font-size:14px; margin-bottom:12px; color:var(--muted);
+       text-transform:uppercase; letter-spacing:.05em; }
+  .hidden { display:none; }
+  .banner { padding:10px 14px; border-radius:8px; font-size:13px;
+            margin-bottom:14px; }
+  .banner.ok { background:#16301d; border:1px solid #2c5c3a; color:#8ce0a4; }
+  .banner.warn { background:#332414; border:1px solid #6b4a1f; color:#e6b873; }
+</style>
+</head>
+<body>
+<header>
+  <h1>Crack Detection &amp; Measurement</h1>
+  <p>Upload a photo of a wall — the crack is segmented and measured in real units.</p>
+</header>
+
+<div class="wrap">
+  <div class="panel">
+    <div id="drop">
+      <p id="dropText">Drop an image here, or click to browse</p>
+      <input type="file" id="file" accept="image/*" class="hidden">
+    </div>
+    <p class="note">Include the printed ArUco marker in the photo so the wall
+      can be scaled to real centimetres.
+      <a href="/marker" target="_blank">Download the printable marker (PDF) →</a></p>
+    <p id="status"></p>
+  </div>
+
+  <div id="results" class="hidden">
+    <div id="arucoStatus"></div>
+    <div class="panel">
+      <h2>Crack measurement</h2>
+      <figure>
+        <img id="overlayImg">
+        <figcaption>Computer-vision segmentation (intensity-based, within the
+          ML-detected region) — green ⊕: widest point · blue ⊕: narrowest point</figcaption>
+      </figure>
+      <div id="cards" class="cards"></div>
+    </div>
+  </div>
+</div>
+
+<script>
+const $ = id => document.getElementById(id);
+const cm = mmVal => (mmVal / 10).toFixed(2);   // mm -> cm
+
+const drop = $("drop"), fileInput = $("file");
+drop.onclick = () => fileInput.click();
+drop.ondragover = e => { e.preventDefault(); drop.classList.add("over"); };
+drop.ondragleave = () => drop.classList.remove("over");
+drop.ondrop = e => {
+  e.preventDefault(); drop.classList.remove("over");
+  if (e.dataTransfer.files.length) analyze(e.dataTransfer.files[0]);
+};
+fileInput.onchange = () => { if (fileInput.files.length) analyze(fileInput.files[0]); };
+
+function setStatus(msg, kind) {
+  $("status").textContent = msg;
+  $("status").className = kind || "";
+}
+
+async function analyze(file) {
+  if (!file.type.startsWith("image/")) { setStatus("Please choose an image file.", "err"); return; }
+  $("dropText").textContent = "Selected: " + file.name;
+  setStatus("Analyzing… segmenting and measuring the crack.", "busy");
+
+  const fd = new FormData();
+  fd.append("image", file);
+  try {
+    const r = await fetch("/analyze", { method:"POST", body:fd });
+    const data = await r.json();
+    if (!r.ok) throw new Error(data.error || "Analysis failed");
+    render(data);
+    setStatus("Done.", "");
+  } catch (err) {
+    setStatus(err.message, "err");
+  }
+}
+
+function renderAruco(a) {
+  const box = $("arucoStatus");
+  if (!a) { box.innerHTML = ""; box.className = ""; return; }
+  if (a.detected) {
+    box.className = "banner ok";
+    box.textContent = `ArUco marker #${a.marker_id} detected — wall rectified, `
+      + `scale ${a.mm_per_pixel.toFixed(4)} mm/px. Measurements are real-world.`;
+  } else {
+    box.className = "banner warn";
+    box.textContent = a.message;
+  }
+}
+
+function render(data) {
+  $("overlayImg").src = data.overlay;
+  $("results").classList.remove("hidden");
+  renderAruco(data.aruco);
+
+  const m = data.measurements;
+  const real = m.scale_known;
+  const s = m.summary, sm = m.summary_mm;
+
+  const cards = real
+    ? [["Max width", sm.max_width_mm + " mm"],
+       ["Min width", sm.min_width_mm + " mm"],
+       ["Total length", cm(sm.total_length_mm) + " cm"]]
+    : [["Max width", s.max_width_px + " px"],
+       ["Min width", s.min_width_px + " px"],
+       ["Total length", s.total_length_px + " px"]];
+  $("cards").innerHTML = cards.map(([k,v]) =>
+    `<div class="card"><div class="v">${v}</div><div class="k">${k}</div></div>`).join("");
+}
+</script>
+</body>
+</html>