add input standardization

_utils/image_io.py

@@ -0,0 +1,358 @@
+"""Image standardization.
+
+Microscopy TIFFs come in many flavors: 16-bit or float pixels, single or
+multi channel, and multi-page Z / time stacks. ``standardize_image`` collapses
+any of those variants to a single canonical 8-bit RGB PNG used for BOTH the
+on-screen preview and the model, so what you see is what gets segmented.
+
+Which axis means what is read from the file's own metadata (``series.axes``
+from tifffile: 'C'=channel, 'S'=RGB samples, 'Z'/'T'=stack, 'Y'/'X'=spatial)
+rather than guessed from the array shape -- guessing cannot tell a 3-channel
+(C, Y, X) image apart from a 3-slice (Z, Y, X) stack. Only when a file names
+no axes at all (tifffile reports 'Q' = unknown) do we fall back to the dominant
+convention: the first unknown axis of size 2-4 is the channel axis.
+
+Reduction policy:
+
+  * multi-page / Z / time stacks -> one frame (default: the first)
+  * more than 3 channels         -> first 3 channels (as R, G, B)
+  * intensity -> 0-255           -> 1st-99th percentile auto-contrast for
+                                    16-bit/float input (outlier-robust: a hot /
+                                    saturated pixel would make plain min/max
+                                    scaling collapse the real signal to black)
+
+Standard 8-bit inputs (PNG/JPG/8-bit TIFF) are passed through unchanged in
+value; only channel layout is normalized.
+"""
+
+import os
+import tempfile
+from typing import NamedTuple
+
+import numpy as np
+from PIL import Image
+
+try:
+    import tifffile
+except ImportError:  # pragma: no cover - tifffile is a project dependency
+    tifffile = None
+
+# Size policy. The model resizes any input to 512x512 (see segmentation.py), so a
+# larger image costs memory/time and *loses* detail rather than adding any.
+RECOMMENDED_SIZE = 512   # cropping to about this preserves the most detail
+WARN_SIZE = 3072         # above this, advise the user to crop
+MAX_SIZE = 4096          # above this, refuse: reading the pixels risks an OOM
+# Refuse files whose full array would not comfortably fit in memory. Measured on
+# the uncompressed array (shape x dtype) rather than the file size on disk, since
+# compression makes disk size a poor proxy for what we actually allocate.
+MAX_READ_BYTES = 300 * 1024 ** 2   # 300 MiB
+
+# Axis roles, per tifffile's `series.axes` naming.
+_SPATIAL = ("Y", "X")
+_CHANNEL = ("C", "S")      # C = separate channel planes, S = interleaved RGB samples
+_UNKNOWN = ("Q", "I")      # file named no axis; only these may be *guessed* as channels
+# Anything else (Z, T, ...) is a stack axis and is indexed by frame.
+
+
+def _read_array(path):
+    """Load an image file into (array, axes) where axes names each dimension.
+
+    axes uses tifffile's convention ('C' channel, 'S' RGB samples, 'Z'/'T'
+    stack, 'Y'/'X' spatial, 'Q' unknown). Indexed / palette images (ImageJ
+    "8-bit Color", palette PNG/GIF) are expanded through their color lookup
+    table so we return true RGB, not bare indices.
+    """
+    ext = os.path.splitext(path)[1].lower()
+    if ext in (".tif", ".tiff") and tifffile is not None:
+        with tifffile.TiffFile(path) as tif:
+            series = tif.series[0]
+            page = tif.pages[0]
+            arr = np.asarray(series.asarray())
+            axes = str(series.axes)
+            is_palette = getattr(page, "photometric", None) == tifffile.PHOTOMETRIC.PALETTE
+            if is_palette and page.colormap is not None:
+                colormap = np.asarray(page.colormap)  # (3, 2**bits), uint16
+                rgb = np.moveaxis(colormap[:, arr], 0, -1)  # (..., H, W, 3)
+                # TIFF colormaps are 16-bit; scale down to 8-bit (65535/255=257).
+                arr = np.round(rgb / 257.0).astype(np.uint8)
+                axes = axes + "S"  # the LUT added an RGB sample axis
+            return arr, axes
+    # Everything else (and if tifffile is unavailable): PIL. Expand palette
+    # images to RGB so the LUT is applied instead of returning bare indices.
+    img = Image.open(path)
+    if img.mode in ("P", "PA"):
+        img = img.convert("RGB")
+    arr = np.asarray(img)
+    return arr, ("YXS" if arr.ndim == 3 else "YX")
+
+
+def _shape_axes(path):
+    """Return (shape, axes) from metadata only - no pixel decode."""
+    ext = os.path.splitext(path)[1].lower()
+    if ext in (".tif", ".tiff") and tifffile is not None:
+        try:
+            with tifffile.TiffFile(path) as tif:
+                series = tif.series[0]
+                return tuple(series.shape), str(series.axes)
+        except Exception:  # noqa: BLE001 - fall through to PIL
+            pass
+    with Image.open(path) as img:
+        w, h = img.size
+        if img.mode in ("P", "PA", "RGB", "RGBA", "CMYK", "YCbCr", "LAB", "HSV"):
+            return (h, w, len(img.getbands())), "YXS"
+        return (h, w), "YX"
+
+
+def _plan_axes(shape, axes):
+    """Drop size-1 axes, infer a channel axis when the file names none, and move
+    it last.
+
+    Returns (shape, axes, guessed) as lists + a flag saying whether the channel
+    axis had to be inferred rather than read from the file.
+    """
+    axes = list(axes)
+    shape = list(shape)
+    if len(axes) != len(shape):  # be defensive; keep the trailing spatial axes
+        axes = ["Q"] * (len(shape) - 2) + ["Y", "X"]
+
+    pairs = [(a, d) for a, d in zip(axes, shape) if d != 1]
+    axes = [a for a, _ in pairs]
+    shape = [d for _, d in pairs]
+
+    guessed = False
+    if not any(a in _CHANNEL for a in axes):
+        # Only guess on axes the file left unnamed. An axis the file explicitly
+        # calls Z/T is a stack even when its length happens to be 3.
+        for i, (a, d) in enumerate(zip(axes, shape)):
+            if a in _UNKNOWN and d in (2, 3, 4):
+                axes[i] = "C"
+                guessed = True
+                break
+
+    ci = next((i for i, a in enumerate(axes) if a in _CHANNEL), None)
+    if ci is not None:
+        axes.append(axes.pop(ci))
+        shape.append(shape.pop(ci))
+    return shape, axes, guessed
+
+
+def _reduce_to_hwc(arr, axes, frame=0):
+    """Collapse a labelled array to 2D (H, W) or 3D (H, W, C).
+
+    The channel axis (named by the file, or inferred by ``_plan_axes`` only when
+    the file names none) is moved last and kept whole. The remaining stack axes
+    (Z / time / page) are indexed: the first by ``frame``, any deeper ones by 0.
+    """
+    axes = list(axes)
+
+    # Drop size-1 axes, keeping arr and axes in sync.
+    for i in range(len(axes) - 1, -1, -1):
+        if arr.shape[i] == 1:
+            arr = arr.reshape(arr.shape[:i] + arr.shape[i + 1:])
+            axes.pop(i)
+
+    _, planned, _ = _plan_axes(arr.shape, axes)
+
+    # Apply the plan to the array: infer the channel axis, then move it last.
+    if "C" in planned and not any(a in _CHANNEL for a in axes):
+        for i, (a, d) in enumerate(zip(axes, arr.shape)):
+            if a in _UNKNOWN and d in (2, 3, 4):
+                axes[i] = "C"
+                break
+    ci = next((i for i, a in enumerate(axes) if a in _CHANNEL), None)
+    if ci is not None:
+        arr = np.moveaxis(arr, ci, -1)
+        axes.append(axes.pop(ci))
+
+    # Index the leading stack axes: first by `frame`, deeper by 0.
+    target = 3 if ci is not None else 2
+    first = True
+    while len(axes) > target:
+        idx = int(frame) if first else 0
+        idx = max(0, min(idx, arr.shape[0] - 1))
+        arr = arr[idx]
+        axes.pop(0)
+        first = False
+
+    return arr
+
+
+class ImageInfo(NamedTuple):
+    """How a file's dimensions were interpreted (read from metadata only).
+
+    frames   - length of the first stack (Z/T) axis, 1 if not a stack
+    channels - length of the channel axis, 1 if single-channel
+    axes     - the file's own axes string, e.g. 'CZYX' ('Q' = unnamed)
+    guessed  - True if the channel axis was inferred rather than read
+    shape    - the file's raw shape as stored, e.g. (1, 4, 1, 1024, 1024)
+    width    - pixels along the X axis (0 if unknown)
+    height   - pixels along the Y axis (0 if unknown)
+    """
+    frames: int
+    channels: int
+    axes: str
+    guessed: bool
+    shape: tuple
+    width: int
+    height: int
+
+
+def inspect_image(path):
+    """Describe a file's structure from metadata only (no pixel decode)."""
+    try:
+        shape, axes = _shape_axes(path)
+        planned_shape, planned_axes, guessed = _plan_axes(shape, axes)
+        has_c = bool(planned_axes) and planned_axes[-1] in _CHANNEL
+        channels = int(planned_shape[-1]) if has_c else 1
+        target = 3 if has_c else 2
+        frames = int(planned_shape[0]) if len(planned_axes) > target else 1
+
+        # Spatial size comes from the named Y/X axes, so it stays correct
+        # whatever order the other axes are in.
+        width = height = 0
+        for a, d in zip(axes, shape):
+            if a == "Y":
+                height = int(d)
+            elif a == "X":
+                width = int(d)
+        if not (width and height):  # no Y/X named; fall back to the header probe
+            width, height = image_size(path)
+
+        return ImageInfo(frames, channels, str(axes), guessed, tuple(shape), width, height)
+    except Exception:  # noqa: BLE001
+        return ImageInfo(1, 1, "", False, (), 0, 0)
+
+
+def count_frames(path):
+    """Return how many frames a file's stack (Z/T) axis has (1 if not a stack)."""
+    return inspect_image(path).frames
+
+
+def array_nbytes(path):
+    """Bytes that opening this file's full array would allocate.
+
+    Computed from shape + dtype in the header - no pixel decode - so it is safe
+    to call on a file that is too large to open. Returns 0 if unknown.
+    """
+    ext = os.path.splitext(path)[1].lower()
+    if ext in (".tif", ".tiff") and tifffile is not None:
+        try:
+            with tifffile.TiffFile(path) as tif:
+                series = tif.series[0]
+                return int(np.prod(series.shape)) * int(np.dtype(series.dtype).itemsize)
+        except Exception:  # noqa: BLE001 - fall through to PIL
+            pass
+    try:
+        with Image.open(path) as img:
+            w, h = img.size
+            return int(w) * int(h) * len(img.getbands())  # 8-bit assumption
+    except Exception:  # noqa: BLE001
+        return 0
+
+
+def image_size(path):
+    """Return an image's (width, height) by reading only its header.
+
+    Never decodes pixel data, so this is safe to call as a size guard on a file
+    that would be too large to load. Returns (0, 0) if the size cannot be
+    determined, so callers treat it as "unknown" and proceed.
+    """
+    ext = os.path.splitext(path)[1].lower()
+    if ext in (".tif", ".tiff") and tifffile is not None:
+        try:
+            with tifffile.TiffFile(path) as tif:
+                page = tif.pages[0]
+                return int(page.imagewidth), int(page.imagelength)
+        except Exception:  # noqa: BLE001 - fall through to PIL
+            pass
+    try:
+        with Image.open(path) as img:  # PIL parses the header lazily
+            return int(img.size[0]), int(img.size[1])
+    except Exception:  # noqa: BLE001
+        return 0, 0
+
+
+def _to_rgb(arr):
+    """Turn a 2D or (H, W, C) array into exactly 3 channels."""
+    if arr.ndim == 2:
+        return np.stack([arr] * 3, axis=-1)
+
+    channels = arr.shape[2]
+    if channels == 1:
+        return np.repeat(arr, 3, axis=2)
+    if channels == 2:
+        # Pad a zero third channel rather than inventing signal.
+        return np.concatenate([arr, np.zeros_like(arr[:, :, :1])], axis=2)
+    return arr[:, :, :3]
+
+
+def _load_rgb(path, frame=0):
+    """Read a file and reduce it to an (H, W, 3) array plus its source dtype."""
+    raw, axes = _read_array(path)
+    arr = _reduce_to_hwc(raw, axes, frame=frame)
+    arr = _to_rgb(arr)
+    return arr, raw.dtype
+
+
+def _to_uint8(arr, stretch):
+    """Map pixel values to uint8.
+
+    When ``stretch`` is True (non-8-bit input) a 1st-99th percentile auto-
+    contrast stretch is applied - outlier-robust, so a hot/saturated pixel does
+    not collapse the visible signal to black. Otherwise values are only clipped,
+    so standard 8-bit images are unchanged.
+    """
+    arr = arr.astype(np.float32)
+
+    if not stretch:
+        return np.clip(arr, 0, 255).astype(np.uint8)
+
+    lo, hi = np.percentile(arr, (1, 99))
+    if hi <= lo:  # near-flat image; fall back to full min/max
+        lo, hi = float(arr.min()), float(arr.max())
+    if hi <= lo:  # truly constant image
+        return np.zeros(arr.shape, dtype=np.uint8)
+
+    arr = np.clip((arr - lo) / (hi - lo), 0.0, 1.0)
+    return (arr * 255.0).astype(np.uint8)
+
+
+def _save_png(arr, out_path=None, out_dir=None, base=None, suffix="_std.png"):
+    """Save an (H, W, 3) uint8 array as a PNG and return the path."""
+    if out_path is None:
+        if out_dir is not None:
+            os.makedirs(out_dir, exist_ok=True)
+            out_path = os.path.join(out_dir, (base or "image") + suffix)
+        else:
+            tmp = tempfile.NamedTemporaryFile(delete=False, suffix=suffix)
+            out_path = tmp.name
+            tmp.close()
+    Image.fromarray(arr, mode="RGB").save(out_path)
+    return out_path
+
+
+def standardize_image(path, frame=0, out_dir=None, out_path=None):
+    """Standardize any image/TIFF to a canonical 8-bit RGB PNG.
+
+    Used for both the preview and the model: one frame, <=3 channels, with a
+    1st-99th percentile auto-contrast stretch for 16-bit/float input (8-bit is
+    passed through unchanged).
+
+    Args:
+        path: path to the input image (TIFF, PNG, JPG, ...).
+        frame: which frame of a stack to use (0-based; ignored for non-stacks).
+        out_dir: optional directory for the output PNG.
+        out_path: optional explicit output file path (overrides out_dir).
+
+    Returns:
+        Path to the standardized PNG. On any failure the original ``path`` is
+        returned unchanged so callers degrade gracefully.
+    """
+    try:
+        arr, dtype = _load_rgb(path, frame=frame)
+        arr = _to_uint8(arr, stretch=(dtype != np.uint8))
+        base = os.path.splitext(os.path.basename(path))[0]
+        return _save_png(arr, out_path=out_path, out_dir=out_dir, base=base, suffix="_std.png")
+    except Exception as e:  # noqa: BLE001 - never let preprocessing crash a run
+        print(f"⚠️ standardize_image failed for {path}: {e}; using original file")
+        return path

app.py

@@ -21,9 +21,13 @@ import spaces
 from inference_seg import load_model as load_seg_model, run as run_seg
 from inference_count import load_model as load_count_model, run as run_count
 from inference_track import load_model as load_track_model, run as run_track
+from _utils.image_io import (
+    standardize_image, inspect_image, image_size, array_nbytes,
+    RECOMMENDED_SIZE, WARN_SIZE, MAX_SIZE, MAX_READ_BYTES,
+)
 
 HF_TOKEN = os.getenv("HF_TOKEN")
-DATASET_REPO = "phoebe777777/celltool_feedback"
+DATASET_REPO = "VisionLanguageGroup/feedback"
 
 
 print("===== clearing cache =====")
@@ -83,24 +87,47 @@ def save_feedback_to_hf(query_id, feedback_type, feedback_text=None, img_path=No
         save_feedback(query_id, feedback_type, feedback_text, img_path, bboxes)
         return
     
-    feedback_data = {
-        "query_id": query_id,
-        "feedback_type": feedback_type,
-        "feedback_text": feedback_text,
-        "image_path": img_path,
-        "bboxes": str(bboxes),  # 转为字符串
-        "datetime": time.strftime("%Y-%m-%d %H:%M:%S"),
-        "timestamp": time.time()
-    }
-    
+    # One stem for the record and its image so the two pair up. query_id alone is
+    # not enough - a single session can submit feedback more than once.
+    stem = f"feedback_{query_id}_{int(time.time())}"
+
     try:
         api = HfApi()
-        
-        filename = f"feedback_{query_id}_{int(time.time())}.json"
-        
+
+        # Upload the standardized PNG: the exact image the model saw (first
+        # frame, <=3 channels, auto-contrasted), not the raw upload.
+        image_in_repo = None
+        if img_path and os.path.exists(img_path):
+            try:
+                image_in_repo = f"images/{stem}.png"
+                api.upload_file(
+                    path_or_fileobj=img_path,
+                    path_in_repo=image_in_repo,
+                    repo_id=DATASET_REPO,
+                    repo_type="dataset",
+                    token=HF_TOKEN
+                )
+            except Exception as e:
+                print(f"⚠️ Failed to upload image: {e}")
+                image_in_repo = None  # still record the rest of the feedback
+
+        feedback_data = {
+            "query_id": query_id,
+            "feedback_type": feedback_type,
+            "feedback_text": feedback_text,
+            # Path inside the dataset repo. This used to be the local temp path,
+            # which was meaningless once the session ended.
+            "image_path": image_in_repo,
+            "bboxes": str(bboxes),  # 转为字符串
+            "datetime": time.strftime("%Y-%m-%d %H:%M:%S"),
+            "timestamp": time.time()
+        }
+
+        filename = f"{stem}.json"
+
         with open(filename, 'w', encoding='utf-8') as f:
             json.dump(feedback_data, f, indent=2, ensure_ascii=False)
-        
+
         api.upload_file(
             path_or_fileobj=filename,
             path_in_repo=f"data/{filename}",
@@ -108,11 +135,11 @@ def save_feedback_to_hf(query_id, feedback_type, feedback_text=None, img_path=No
             repo_type="dataset",
             token=HF_TOKEN
         )
-        
+
         os.remove(filename)
-        
-        print(f"✅ Feedback saved to HF Dataset: {DATASET_REPO}")
-        
+
+        print(f"✅ Feedback saved to HF Dataset: {DATASET_REPO} ({stem})")
+
     except Exception as e:
         print(f"⚠️ Failed to save to HF Dataset: {e}")
         save_feedback(query_id, feedback_type, feedback_text, img_path, bboxes)
@@ -293,6 +320,134 @@ def cleanup_tracking_cache(track_vis_cache):
                 pass
 
 
+def _annot_path(annot_value):
+    """Extract the image path from a BBoxAnnotator value (path or (path, boxes))."""
+    if not annot_value:
+        return None
+    if isinstance(annot_value, (list, tuple)):
+        return annot_value[0] if len(annot_value) > 0 else None
+    return annot_value
+
+
+def _human_bytes(n):
+    """Format a byte count as MB or GB, whichever reads better."""
+    gb = n / 1024 ** 3
+    return f"{gb:.1f} GB" if gb >= 1 else f"{n / 1024 ** 2:.0f} MB"
+
+
+def check_image(img_path):
+    """Check a file from its header only (no pixel decode).
+
+    Returns a rejection message if the file cannot be used, otherwise None:
+      * unreadable / unsupported format
+      * dimensions over MAX_SIZE
+      * full array over MAX_READ_BYTES (a small time-lapse can still be huge)
+    Also emits an advisory warning over WARN_SIZE, since the model resizes every
+    input to RECOMMENDED_SIZE and a larger image only loses detail.
+    """
+    w, h = image_size(img_path)
+    if w <= 0 or h <= 0:
+        # Neither tifffile nor PIL could parse the header, so this is not a
+        # format we can read. Say so instead of failing silently downstream.
+        ext = os.path.splitext(img_path)[1].lower() or "(no extension)"
+        return (f"Could not read {ext} as an image. Supported formats: "
+                f"TIFF / OME-TIFF (8/16/32-bit, stacks, multi-channel), PNG, JPG, and other formats suported by tiffile. "
+                f"please export to TIFF/PNG/JPG (e.g. from ImageJ/Fiji) first.")
+
+    if w > MAX_SIZE or h > MAX_SIZE:
+        return (f"Image is {w}×{h}, larger than the {MAX_SIZE}×{MAX_SIZE} limit. "
+                f"Please crop or downsample it before uploading.")
+
+    nbytes = array_nbytes(img_path)
+    if nbytes > MAX_READ_BYTES:
+        info = inspect_image(img_path)
+        detail = f"{w}×{h}"
+        if info.frames > 1:
+            detail += f" × {info.frames} frames"
+        if info.channels > 1:
+            detail += f" × {info.channels} channels"
+        return (f"This file needs {_human_bytes(nbytes)} of memory to open "
+                f"({detail}), over the {_human_bytes(MAX_READ_BYTES)} limit. "
+                f"Please crop it, or split out the frames you need.")
+
+    if w > WARN_SIZE or h > WARN_SIZE:
+        gr.Warning(f"Image is {w}×{h} and will be resized to "
+                   f"{RECOMMENDED_SIZE}×{RECOMMENDED_SIZE}, so fine detail could be lost. "
+                   f"You can try cropping the image for better results.",
+                #    f"For best results, try cropping the image to focus on the region of interest.",
+                   duration=None, title="⚠️ Large image")
+    return None
+
+
+def _describe_read(info):
+    """Plain-language summary of how a file's dimensions were interpreted.
+
+    Deliberately avoids array jargon ("axis", "size-4"): the reader thinks in
+    channels / z-slices / timepoints, not numpy axes.
+    """
+    # lines = [f"Detected shape: {info.shape}"]
+    if info.frames >1:
+        lines = [f"Detected {info.channels}-channel {info.frames}-frame image stack of size {info.width}×{info.height}."]
+    else:
+        lines = [f"Detected {info.channels}-channel image of size {info.width}×{info.height}."]
+    if info.channels >= 3:
+        lines.append(f"Loaded as 3-channel RGB image.")
+    elif info.channels == 2:
+        lines.append(f"Loaded as 2-channel image (red, green).")
+    else:
+        lines.append(f"Loaded as single-channel grayscale image.")
+
+    if info.frames > 1:
+        lines.append(f"Showing first frame by default (you can use the stack frame slider to pick another).")
+
+    lines.append(
+        "If wrong, please convert your image to a 8-bit RGB/Grayscale image file before uploading (there are available tools such as ImageJ/Fiji)."
+    )
+    return "<br>".join(lines)
+
+
+def prepare_uploaded_image(annot_value):
+    """On annotator upload: standardize frame 0 for preview and configure the
+    stack frame slider.
+
+    Browsers cannot render 16-bit / float / multi-page TIFFs, so we standardize
+    to an 8-bit RGB PNG. If the file is a stack, notify the user and reveal a
+    frame slider (default frame 1); otherwise keep it hidden.
+
+    Returns (annotator_value, raw_path, frame_slider_update).
+    """
+    img_path = _annot_path(annot_value)
+    if not img_path:
+        return annot_value, None, gr.update(visible=False, value=1)
+
+    # Guard before any pixels are read. On refusal clear the annotator so the
+    # oversize file cannot be sent to inference.
+    rejected = check_image(img_path)
+    if rejected:
+        gr.Warning(rejected, duration=None, title="❌ Cannot use this file")
+        return None, None, gr.update(visible=False, value=1)
+
+    info = inspect_image(img_path)
+    display = standardize_image(img_path, frame=0)
+
+    # Only speak up when something non-obvious happened: a dimension had to be
+    # guessed, it is a stack, or channels are being dropped. A plain RGB or
+    # grayscale image needs no explanation.
+    if info.guessed or info.frames > 1 or info.channels > 3:
+        gr.Info(_describe_read(info), duration=None, title="📚 Image Loading Info")
+
+    slider = (gr.update(visible=True, maximum=info.frames, value=1) if info.frames > 1
+              else gr.update(visible=False, value=1))
+    return display, img_path, slider
+
+
+def select_frame(raw_path, frame_num):
+    """Re-render the annotator preview for the chosen stack frame (1-based)."""
+    if not raw_path:
+        return gr.update()
+    return standardize_image(raw_path, frame=int(frame_num) - 1)
+
+
 @spaces.GPU
 def segment_with_choice(use_box_choice, annot_value, overlay_alpha):
     """Segmentation handler - supports bounding box, returns colorized overlay and original mask path"""
@@ -304,6 +459,9 @@ def segment_with_choice(use_box_choice, annot_value, overlay_alpha):
     bboxes = annot_value[1] if len(annot_value) > 1 else []
 
     print(f"🖼️ Image path: {img_path}")
+    # One standardized image for both the model and the overlay (WYSIWYG).
+    img_path = standardize_image(img_path)
+    print(f"🧪 Standardized image: {img_path}")
     box_array = None
     if use_box_choice == "Yes" and bboxes:
         box = parse_bboxes(bboxes)
@@ -359,21 +517,24 @@ def count_cells_handler(use_box_choice, annot_value, overlay_alpha):
     """Counting handler - supports bounding box, returns only density map"""
     if annot_value is None or len(annot_value) < 1:
         return None, None, "⚠️ Please provide an image.", {}
-    
+
     image_path = annot_value[0]
     bboxes = annot_value[1] if len(annot_value) > 1 else []
 
     print(f"🖼️ Image path: {image_path}")
+    # One standardized image for both the model and the overlay (WYSIWYG).
+    image_path = standardize_image(image_path)
+    print(f"🧪 Standardized image: {image_path}")
     box_array = None
     if use_box_choice == "Yes" and bboxes:
         box = parse_bboxes(bboxes)
         if box:
             box_array = box
             print(f"📦 Using bounding boxes: {box_array}")
-    
+
     try:
         print(f"🔢 Counting - Image: {image_path}")
-        
+
         device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
         result = run_count(
             COUNT_MODEL,
@@ -1013,6 +1174,64 @@ button.secondary:hover {
 /* ── Labels ──────────────────────────────────────────── */
 label { font-weight: 500 !important; color: #374151 !important; }
 
+/* File/media title pills use .block-label on a <label>, so the rule above
+   forces their text dark. Restore the theme color/weight so they match the
+   other native labels (e.g. "Overlay Opacity"). */
+.block-label,
+.block-label span {
+    color: var(--block-label-text-color) !important;
+    font-weight: var(--block-label-text-weight) !important;
+}
+
+/* ── Collapsible "Image requirements" accordion ───────── */
+
+/* The label is a <button class="label-wrap"> whose text sits in an inner <span>.
+   Gradio styles that span directly:
+       span.svelte-xxx { font-weight: var(--section-header-text-weight);  // = 400
+                         font-size:   var(--section-header-text-size); }
+   so font-size/weight set on the button is overridden and has no effect - the
+   span itself must be targeted. Colour is not set on the span, so it inherits. */
+.req-accordion .label-wrap {
+    color: var(--block-label-text-color) !important;
+}
+.req-accordion .label-wrap span:not(.icon) {
+    font-size: 0.9rem !important;
+    font-weight: 700 !important;
+    color: inherit !important;
+}
+
+/* ── Frame headings (labels above media frames) ──────── */
+/* Neutralize the Gradio block wrapper so it doesn't clip/round the pill */
+.frame-heading {
+    /* The column has a 16px flex gap; pull the pill back down so it sits
+       close to the frame below instead of floating far above it. */
+    margin-bottom: -8px !important;
+    padding: 0 !important;
+    min-width: 0 !important;
+    min-height: 0 !important;
+    background: transparent !important;
+    border: none !important;
+    box-shadow: none !important;
+    border-radius: 0 !important;
+    overflow: visible !important;
+}
+/* Match the theme's native field labels (e.g. "Overlay Opacity",
+   "Download Original Prediction") exactly: same colors, borderless, fully
+   rounded — driven by theme variables so it adapts to light/dark mode. */
+.frame-heading p {
+    display: inline-block !important;
+    width: fit-content !important;
+    background: var(--block-label-background-fill) !important;
+    color: var(--block-label-text-color) !important;
+    border: none !important;
+    border-radius: var(--block-label-radius) !important;
+    font-weight: var(--block-label-text-weight) !important;
+    font-size: var(--block-label-text-size) !important;
+    line-height: 1.3 !important;
+    padding: 5px 12px !important;
+    margin: 0 !important;
+}
+
 /* ── Image output ────────────────────────────────────── */
 .uniform-height {
     height: 480px !important;
@@ -1125,6 +1344,11 @@ label { font-weight: 500 !important; color: #374151 !important; }
 .dark label {
     color: #cbd5e1 !important;
 }
+.dark .block-label,
+.dark .block-label span {
+    color: var(--block-label-text-color) !important;
+    font-weight: var(--block-label-text-weight) !important;
+}
 
 /* ── Image output area ───────────────────────────────── */
 .dark .uniform-height {
@@ -1155,7 +1379,10 @@ with gr.Blocks(
         primary_hue=gr.themes.colors.sky,
         secondary_hue=gr.themes.colors.slate,
         neutral_hue=gr.themes.colors.slate,
-        font=gr.themes.GoogleFont("Inter"),
+        # Weights must be loaded to be usable: GoogleFont defaults to (400, 600),
+        # so any font-weight above 600 silently falls back. Inter tops out at 900;
+        # anything higher is dropped by Google Fonts without an error.
+        font=gr.themes.GoogleFont("Inter", weights=(400, 600, 700, 800)),
     ),
     css=CSS,
 ) as demo:
@@ -1180,11 +1407,18 @@ with gr.Blocks(
     )
     
     # 全局状态
-    current_query_id = gr.State(str(uuid.uuid4()))
+    # Must be a callable: gr.State deepcopies a plain value, so str(uuid4())
+    # would be evaluated once at construction and every session would share the
+    # same id. A callable is re-run on each app load, giving one id per session.
+    current_query_id = gr.State(lambda: str(uuid.uuid4()))
     user_uploaded_examples = gr.State(example_images_seg.copy())
     seg_vis_state = gr.State({})
     count_vis_state = gr.State({})
     track_vis_state = gr.State({})
+    # Raw uploaded path, kept so a different stack frame can be re-extracted
+    # (the annotator only holds the already-flattened preview PNG).
+    seg_raw_state = gr.State(None)
+    count_raw_state = gr.State(None)
     
     with gr.Tabs():
         # ===== Tab 1: Segmentation =====
@@ -1193,25 +1427,50 @@ with gr.Blocks(
             gr.Markdown(
                         """
                         **Instructions:**
-                        1. Upload an image or select an example image (supports various formats: .png, .jpg, .tif)
+                        1. Select an example image from the Example Image Gallery or upload your own image (**Please see the "Image Upload Requirements" section below before uploading**)
                         2. (Optional) Specify a target object with a bounding box and select "Yes", or click "Run Segmentation" directly
                         3. Click "Run Segmentation"
                         4. View the segmentation results (you can adjust the overlay opacity by sliding the opacity bar below the visualization), download the original predicted mask (.tif format); if needed, click "Clear Selection" to choose a new image
-                        
-                        🤘 Rate and submit feedback to help us improve the model!
+
+                        💡 Want to reuse an image? Upload it under "➕ Upload New Example Image to Gallery" and click "➕ Add to Gallery". The uploaded image will appear at the front of the gallery, and can be loaded by clicking its thumbnail. Gallery additions last for the current session only and are cleared when you reload the page.
+
+                        🤘 Tell us about your experience by rating and submitting feedback, which would greatly help us improve the framework!
                         """
                     )
+            # Reference material - collapsed by default. Must stay AFTER the
+            # instructions markdown: the CSS styles it via .prose:nth-child(2).
+            with gr.Accordion("📋 Image Upload Requirements (click to expand or fold)", open=False, elem_classes="req-accordion"):
+                gr.Markdown(
+                    """
+                    **Please do not upload images or data containing protected health information (PHI) or personally identifiable information (PII).**
+
+                    - **Formats:** Supports TIFF / OME-TIFF (8/16/32-bit, stacks, multi-channel), PNG, JPG, as well as various other microscopy image formats supported by [tifffiles](https://github.com/cgohlke/tifffile)
+                    - **Maximum image size:** 4096 × 4096 pixels
+                    - **Channels:** Accepts RGB (3-channel), Grayscale (single-channel); for images with more than 3 channels, only the first three channels are used as RGB channels.
+                    - **For image stacks:** First frame is loaded by default; you can pick another with the stack frame slider that appears after upload
+                    
+                    **Alternatively, you can use existing tools (e.g., ImageJ/Fiji) to convert your image to a 8-bit RGB/Grayscale PNG/JPG/TIFF file before uploading.**
+                    
+                    """
+                )
             
             with gr.Row():
                 with gr.Column(scale=1):
+                    gr.Markdown("🖼️ Upload Image (Optional: Provide a Bounding Box)", elem_classes="frame-heading")
                     annotator = BBoxAnnotator(
-                        label="🖼️ Upload Image (Optional: Provide a Bounding Box)",
+                        show_label=False,
                         categories=["cell"],
                     )
-                    
+                    seg_frame_slider = gr.Slider(
+                        minimum=1, maximum=1, step=1, value=1,
+                        label="📚 Stack frame (choose frame to use)",
+                        visible=False,
+                    )
+
                     # Example Images Gallery
+                    gr.Markdown("📁 Example Image Gallery", elem_classes="frame-heading")
                     example_gallery = gr.Gallery(
-                        label="📁 Example Image Gallery",
+                        show_label=True,
                         columns=len(example_images_seg),
                         rows=1,
                         height=120,
@@ -1231,16 +1490,21 @@ with gr.Blocks(
                         clear_btn = gr.Button("🔄 Clear Selection", variant="secondary")
 
                     # Upload Example Image
-                    image_uploader = gr.Image(
-                        label="➕ Upload New Example Image to Gallery",
+                    gr.Markdown("➕ Upload New Example Image to Gallery", elem_classes="frame-heading")
+                    image_uploader = gr.File(
+                        show_label=False,
+                        file_types=["image", ".tif", ".tiff"],
                         type="filepath"
                     )
+                    add_to_gallery_btn = gr.Button("➕ Add to Gallery", variant="secondary", size="sm")
+                    add_gallery_status = gr.Markdown(visible=False)
 
 
                 with gr.Column(scale=2):
+                    gr.Markdown("📸 Segmentation Result", elem_classes="frame-heading")
                     seg_output = gr.Image(
                         type="pil",
-                        label="📸 Segmentation Result",
+                        show_label=False,
                         elem_classes="uniform-height"
                     )
                     seg_alpha_slider = gr.Slider(
@@ -1252,8 +1516,9 @@ with gr.Blocks(
                     )
                     
                     # Download Original Prediction
+                    gr.Markdown("📥 Download Original Prediction (.tif format)", elem_classes="frame-heading")
                     download_mask_btn = gr.File(
-                        label="📥 Download Original Prediction (.tif format)",
+                        show_label=False,
                         visible=True,
                         height=40,
                     )
@@ -1283,6 +1548,19 @@ with gr.Blocks(
                         visible=False
                     )
             
+            # standardize on upload (preview) + configure the stack frame slider
+            annotator.upload(
+                fn=prepare_uploaded_image,
+                inputs=annotator,
+                outputs=[annotator, seg_raw_state, seg_frame_slider]
+            )
+            # re-render the preview when the user picks a different stack frame
+            seg_frame_slider.release(
+                fn=select_frame,
+                inputs=[seg_raw_state, seg_frame_slider],
+                outputs=annotator
+            )
+
             # click event for segmentation
             run_seg_btn.click(
                 fn=segment_with_choice,
@@ -1297,9 +1575,9 @@ with gr.Blocks(
 
             # click event for clear button
             clear_btn.click(
-                fn=lambda: (None, {}),
+                fn=lambda: (None, {}, None, gr.update(visible=False, value=1)),
                 inputs=None,
-                outputs=[annotator, seg_vis_state]
+                outputs=[annotator, seg_vis_state, seg_raw_state, seg_frame_slider]
             )
             
             # init Gallery with example images
@@ -1308,37 +1586,41 @@ with gr.Blocks(
                 outputs=example_gallery
             )
             
-            # click event for image uploader
+            # Add the uploaded image to the gallery on button click, confirm with
+            # a status message, and clear the uploader so the upload box returns.
             def add_to_gallery(img_path, current_imgs):
                 if not img_path:
-                    return current_imgs
-                try:
-                    if img_path not in current_imgs:
-                        current_imgs.append(img_path)
-                    return current_imgs
-                except:
-                    return current_imgs
-            
-            image_uploader.change(
+                    return (current_imgs, current_imgs,
+                            gr.update(value="⚠️ Please upload an image first.", visible=True), None)
+                rejected = check_image(img_path)
+                if rejected:
+                    return (current_imgs, current_imgs,
+                            gr.update(value=f"❌ {rejected}", visible=True), None)
+                # Standardize to an 8-bit PNG so TIFFs render as gallery
+                # thumbnails; prepend so it's immediately visible at the front.
+                std_path = standardize_image(img_path)
+                if std_path not in current_imgs:
+                    current_imgs.insert(0, std_path)
+                return (current_imgs, current_imgs,
+                        gr.update(value="✅ Added to the Example Gallery below.", visible=True), None)
+
+            add_to_gallery_btn.click(
                 fn=add_to_gallery,
                 inputs=[image_uploader, user_uploaded_examples],
-                outputs=user_uploaded_examples
-            ).then(
-                fn=lambda imgs: imgs,
-                inputs=user_uploaded_examples,
-                outputs=example_gallery
+                outputs=[user_uploaded_examples, example_gallery, add_gallery_status, image_uploader]
             )
             
-            # click event for Gallery selection
+            # click event for Gallery selection (gallery entries are single-frame)
             def load_from_gallery(evt: gr.SelectData, all_imgs):
                 if evt.index is not None and evt.index < len(all_imgs):
-                    return all_imgs[evt.index]
-                return None
-            
+                    item = all_imgs[evt.index]
+                    return standardize_image(item), item, gr.update(visible=False, value=1)
+                return None, None, gr.update(visible=False, value=1)
+
             example_gallery.select(
                 fn=load_from_gallery,
                 inputs=user_uploaded_examples,
-                outputs=annotator
+                outputs=[annotator, seg_raw_state, seg_frame_slider]
             )
             
             # click event for submitting feedback
@@ -1378,26 +1660,50 @@ with gr.Blocks(
             gr.Markdown(
                 """
                 **Usage Instructions:**
-                1. Upload an image or select an example image (supports multiple formats: .png, .jpg, .tif)
+                1. Select an example image from the Example Image Gallery or upload your own image (**Please see the "Image Upload Requirements" section below before uploading**)
                 2. (Optional) Specify a target object with a bounding box and select "Yes", or click "Run Counting" directly
                 3. Click "Run Counting"
                 4. View the density map (you can adjust the density opacity by sliding the opacity bar below the visualization), download the original prediction (.npy format); if needed, click "Clear Selection" to choose a new image to run
-                
-                🤘 Rate and submit feedback to help us improve the model!
+
+                💡 Want to reuse an image? Upload it under "➕ Upload New Example Image to Gallery" and click "➕ Add to Gallery". The uploaded image will appear at the front of the gallery, and can be loaded by clicking its thumbnail. Gallery additions last for the current session only and are cleared when you reload the page.
+
+                🤘 Tell us about your experience by rating and submitting feedback, which would greatly help us improve the framework!
                 """
             )
+            # Reference material - collapsed by default. Must stay AFTER the
+            # instructions markdown: the CSS styles it via .prose:nth-child(2).
+            with gr.Accordion("📋 Image requirements", open=False, elem_classes="req-accordion"):
+                gr.Markdown(
+                    """
+                    **Please do not upload images or data containing protected health information (PHI) or personally identifiable information (PII).**
+
+                    - **Formats:** Supports TIFF / OME-TIFF (8/16/32-bit, stacks, multi-channel), PNG, JPG, as well as various other microscopy image formats supported by [tifffiles](https://github.com/cgohlke/tifffile)
+                    - **Maximum image size:** 4096 × 4096 pixels
+                    - **Channels:** Accepts RGB (3-channel), Grayscale (single-channel); for images with more than 3 channels, only the first three channels are used as RGB channels.
+                    - **For image stacks:** First frame is loaded by default; you can pick another with the stack frame slider that appears after upload
+                    
+                    **Alternatively, you can use existing tools (e.g., ImageJ/Fiji) to convert your image to a 8-bit RGB/Grayscale PNG/JPG/TIFF file before uploading.**
+                    """
+                )
             
             with gr.Row():
                 with gr.Column(scale=1):
+                    gr.Markdown("🖼️ Upload Image (Optional: Provide a Bounding Box)", elem_classes="frame-heading")
                     count_annotator = BBoxAnnotator(
-                        label="🖼️ Upload Image (Optional: Provide a Bounding Box)",
+                        show_label=False,
                         categories=["cell"],
                     )
-                    
+                    count_frame_slider = gr.Slider(
+                        minimum=1, maximum=1, step=1, value=1,
+                        label="📚 Stack frame (choose frame to use)",
+                        visible=False,
+                    )
+
                     # Example gallery with "add" functionality
+                    gr.Markdown("📁 Example Image Gallery", elem_classes="frame-heading")
                     with gr.Row():
                         count_example_gallery = gr.Gallery(
-                            label="📁 Example Image Gallery",
+                            show_label=False,
                             columns=len(example_images_cnt),
                             rows=1,
                             object_fit="cover",
@@ -1419,20 +1725,23 @@ with gr.Blocks(
                         clear_btn = gr.Button("🔄 Clear Selection", variant="secondary")
                     
                     # Add button to upload new examples
-                    with gr.Row():
-                        count_image_uploader = gr.File(
-                            label="➕ Add Example Image to Gallery",
-                            file_types=["image"],
-                            type="filepath"
-                        )
+                    gr.Markdown("➕ Add Example Image to Gallery", elem_classes="frame-heading")
+                    count_image_uploader = gr.File(
+                        show_label=False,
+                        file_types=["image"],
+                        type="filepath"
+                    )
+                    add_to_count_gallery_btn = gr.Button("➕ Add to Gallery", variant="secondary", size="sm")
+                    count_add_status = gr.Markdown(visible=False)
 
                 
                 with gr.Column(scale=2):
+                    gr.Markdown("📸 Density Map", elem_classes="frame-heading")
                     count_output = gr.Image(
-                        label="📸 Density Map",
+                        show_label=False,
                         type="filepath",
                         elem_id="density_map_output"
-                        
+
                     )
                     count_alpha_slider = gr.Slider(
                         minimum=0.0,
@@ -1445,8 +1754,9 @@ with gr.Blocks(
                         label="📊 Statistics",
                         lines=2
                     )
+                    gr.Markdown("📥 Download Original Prediction (.npy format)", elem_classes="frame-heading")
                     download_density_btn = gr.File(
-                        label="📥 Download Original Prediction (.npy format)",
+                        show_label=False,
                         visible=True
                     )
 
@@ -1478,44 +1788,61 @@ with gr.Blocks(
             # State for managing gallery images
             count_user_examples = gr.State(example_images_cnt.copy())
             
-            # Function to add image to gallery
+            # Add the uploaded image to the gallery on button click, confirm with
+            # a status message, and clear the uploader afterward.
             def add_to_count_gallery(new_img_file, current_imgs):
                 """Add uploaded image to gallery"""
                 if new_img_file is None:
-                    return current_imgs, current_imgs
-                
-                try:
-                    # Add new image path to list
-                    if new_img_file not in current_imgs:
-                        current_imgs.append(new_img_file)
-                        print(f"✅ Added image to gallery: {new_img_file}")
-                except Exception as e:
-                    print(f"⚠️  Failed to add image: {e}")
-                
-                return current_imgs, current_imgs
-            
-            # When user uploads a new image file
-            count_image_uploader.upload(
+                    return (current_imgs, current_imgs,
+                            gr.update(value="⚠️ Please upload an image first.", visible=True), None)
+                rejected = check_image(new_img_file)
+                if rejected:
+                    return (current_imgs, current_imgs,
+                            gr.update(value=f"❌ {rejected}", visible=True), None)
+                # Standardize to an 8-bit PNG so TIFFs render as gallery
+                # thumbnails; prepend so it's immediately visible at the front.
+                std_path = standardize_image(new_img_file)
+                if std_path not in current_imgs:
+                    current_imgs.insert(0, std_path)
+                    print(f"✅ Added image to gallery: {std_path}")
+                return (current_imgs, current_imgs,
+                        gr.update(value="✅ Added to the Example Gallery above.", visible=True), None)
+
+            # When user clicks "Add to Gallery"
+            add_to_count_gallery_btn.click(
                 fn=add_to_count_gallery,
                 inputs=[count_image_uploader, count_user_examples],
-                outputs=[count_user_examples, count_example_gallery]
+                outputs=[count_user_examples, count_example_gallery, count_add_status, count_image_uploader]
             )
             
-            # When user selects from gallery, load into annotator
+            # standardize on upload (preview) + configure the stack frame slider
+            count_annotator.upload(
+                fn=prepare_uploaded_image,
+                inputs=count_annotator,
+                outputs=[count_annotator, count_raw_state, count_frame_slider]
+            )
+            # re-render the preview when the user picks a different stack frame
+            count_frame_slider.release(
+                fn=select_frame,
+                inputs=[count_raw_state, count_frame_slider],
+                outputs=count_annotator
+            )
+
+            # When user selects from gallery, load into annotator (single-frame)
             def load_from_count_gallery(evt: gr.SelectData, all_imgs):
                 """Load selected image from gallery into annotator"""
                 if evt.index is not None and evt.index < len(all_imgs):
                     selected_img = all_imgs[evt.index]
                     print(f"📸 Loading image from gallery: {selected_img}")
-                    return selected_img
-                return None
-            
+                    return standardize_image(selected_img), selected_img, gr.update(visible=False, value=1)
+                return None, None, gr.update(visible=False, value=1)
+
             count_example_gallery.select(
                 fn=load_from_count_gallery,
                 inputs=count_user_examples,
-                outputs=count_annotator
+                outputs=[count_annotator, count_raw_state, count_frame_slider]
             )
-            
+
             # Run counting
             count_btn.click(
                 fn=count_cells_handler,
@@ -1530,9 +1857,9 @@ with gr.Blocks(
 
             # Clear selection
             clear_btn.click(
-                fn=lambda: (None, {}),
+                fn=lambda: (None, {}, None, gr.update(visible=False, value=1)),
                 inputs=None,
-                outputs=[count_annotator, count_vis_state]
+                outputs=[count_annotator, count_vis_state, count_raw_state, count_frame_slider]
             )
 
             # Submit feedback
@@ -1572,33 +1899,39 @@ with gr.Blocks(
             gr.Markdown(
                         """
                         **Instructions:**
-                        1. Upload a ZIP file or select from the example library. The ZIP should contain a sequence of TIF images named in chronological order (e.g., t000.tif, t001.tif...)
+                        1. Select a video from the example library or Upload your own video ZIP file. The ZIP should contain a sequence of TIF images named in chronological order (e.g., t000.tif, t001.tif...)
                         2. (Optional) Specify a target object with a bounding box on the first frame and select "Yes", or click "Run Tracking" directly
                         3. Click "Run Tracking"
                         4. View the tracking results (you can adjust the overlay opacity by sliding the opacity bar below the visualization), download the CTC format results; if needed, click "Clear Selection" to choose a new ZIP file to run
+
+                        💡 Want to reuse a video? Upload the ZIP under "➕ Upload New Example Image to Gallery" and click "➕ Add to Gallery". The uploaded video will appear at the front of the gallery, and can be loaded by clicking its thumbnail. Gallery additions last for the current session only and are cleared when you reload the page.
                         
-                        🤘 Rate and submit feedback to help us improve the model!
+                        🤘 Tell us about your experience by rating and submitting feedback, which would greatly help us improve the framework!
 
                         """
                     )
             
             with gr.Row():
                 with gr.Column(scale=1):
+                    gr.Markdown("📦 Upload Image Sequence in ZIP File", elem_classes="frame-heading")
                     track_zip_upload = gr.File(
-                        label="📦 Upload Image Sequence in ZIP File",
+                        show_label=False,
                         file_types=[".zip"]
                     )
 
-                    # First frame annotation for bounding box
-                    track_first_frame_annotator = BBoxAnnotator(
-                        label="🖼️ (Optional) First Frame Bounding Box Annotation",
-                        categories=["cell"],
-                        visible=False,  # Hidden initially
-                    )
+                    # First frame annotation for bounding box (heading + annotator
+                    # share one column so they show/hide together)
+                    with gr.Column(visible=False) as track_annot_group:
+                        gr.Markdown("🖼️ (Optional) First Frame Bounding Box Annotation", elem_classes="frame-heading")
+                        track_first_frame_annotator = BBoxAnnotator(
+                            show_label=False,
+                            categories=["cell"],
+                        )
 
                     # Example ZIP gallery
+                    gr.Markdown("📁 Example Video Gallery (Click to Select)", elem_classes="frame-heading")
                     track_example_gallery = gr.Gallery(
-                        label="📁 Example Video Gallery (Click to Select)",
+                        show_label=False,
                         columns=10,
                         rows=1,
                         height=120,
@@ -1618,15 +1951,17 @@ with gr.Blocks(
                         clear_btn = gr.Button("🔄 Clear Selection", variant="secondary")
                     
                     # Add to gallery button
+                    gr.Markdown("➕ Add ZIP to Example Gallery", elem_classes="frame-heading")
                     track_gallery_upload = gr.File(
-                        label="➕ Add ZIP to Example Gallery",
+                        show_label=False,
                         file_types=[".zip"],
                         type="filepath"
                     )
                 
                 with gr.Column(scale=2):
+                    gr.Markdown("📸 Tracking Visualization", elem_classes="frame-heading")
                     track_first_frame_preview = gr.Image(
-                        label="📸 Tracking Visualization",
+                        show_label=False,
                         type="filepath",
                         # height=400,
                         elem_classes="uniform-height",
@@ -1646,10 +1981,12 @@ with gr.Blocks(
                         interactive=False
                     )
                     
-                    track_download = gr.File(
-                        label="📥 Download Tracking Results (CTC Format)",
-                        visible=False
-                    )
+                    # heading + download share one column so they show/hide together
+                    with gr.Column(visible=False) as track_dl_group:
+                        gr.Markdown("📥 Download Tracking Results (CTC Format)", elem_classes="frame-heading")
+                        track_download = gr.File(
+                            show_label=False,
+                        )
 
                     # Satisfaction rating
                     score_slider = gr.Slider(
@@ -1847,14 +2184,14 @@ with gr.Blocks(
             track_zip_upload.change(
                 fn=load_first_frame_for_annotation,
                 inputs=track_zip_upload,
-                outputs=[track_first_frame_annotator, track_first_frame_annotator]
+                outputs=[track_first_frame_annotator, track_annot_group]
             )
             
             # Run tracking
             track_btn.click(
                 fn=track_video_handler,
                 inputs=[track_use_box_radio, track_first_frame_annotator, track_zip_upload, track_alpha_slider, track_vis_state],
-                outputs=[track_download, track_output, track_download, track_first_frame_preview, track_vis_state]
+                outputs=[track_download, track_output, track_dl_group, track_first_frame_preview, track_vis_state]
             )
             track_alpha_slider.change(
                 fn=update_tracking_overlay_alpha,
@@ -1909,4 +2246,9 @@ if __name__ == "__main__":
         share=False,
         ssr_mode=False,
         show_error=True,
+        # Deliberately no max_file_size: a transport-layer 413 is silent in the
+        # annotator (we never get to run, so we cannot show a message), and file
+        # size is a poor proxy anyway - a 1344x1024 time-lapse can be 256MB while
+        # a 4096x4096 RGB is only 50MB. Size is checked in check_image()
+        # instead, where a real message can be shown.
     )