S2FApp v1.1.0: units (Pa, µm, nN), provenance in reports, FN spheroid default, force-region metrics on, batch PDF report and TIFF (Pa) export

S2FApp/README.md

@@ -29,13 +29,31 @@ Checkpoints are downloaded automatically from the [Shape2Force model repo](https
 
 ## Usage
 
-1. Choose **Model type**: Single cell or Spheroid
-2. Select a **Checkpoint** from `ckp/`
-3. For single-cell: pick **Conditions** (e.g. Fibroblasts_Fibronectin_6KPa)
-4. Upload an image or pick from `samples/`
-5. Click **Run prediction**
-
-Output: heatmap, cell force (sum), and basic stats.
+1. Choose **Model type**: Single cell or Spheroid.
+2. Select a **Checkpoint** from `ckp/`. The architecture is read from the checkpoint. For spheroids the default is
+   `ckp_spheroid_FN.pth`, a smaller supervised model (11.8 M parameters) with smoother maps and similar accuracy;
+   `ckp_spheroid_GN.pth` is the adversarial S2F model (77 M parameters).
+3. Single cell: keep the **Substrate setting** at *Reference (6 kPa)*. The released model is most accurate with this
+   setting for every image, including cells on 1 or 10 kPa gels; presets and manual values are for exploration.
+4. Enter the **Image pixel size** (µm/px) of your bright-field image, for the scale bar, area and total force
+   (0.325 µm/px for the single-cell training images).
+5. Upload an image or pick one from `samples/`, then click **Run prediction**.
+
+## Output and units
+
+- The model predicts a normalised map in [0, 1] that converts to **traction stress** as
+  T = 500 Pa x value (single cells) or 50 Pa x value (spheroids), the fixed colour limits of the TFM ground-truth
+  maps used for training. All maps carry a colourbar in Pa and a µm scale bar.
+- Metrics: mean and maximum traction stress (Pa), area (µm²) and total force (nN = Σ stress x pixel area). By default
+  (*Measure force region only*) they are computed inside the region of high predicted stress (red contour), estimated
+  from the predicted map, so that the background does not dilute them; switch it off for the whole image.
+  S2F predicts magnitude only, not direction.
+- **Display range** narrows the colour window (e.g. 0–250 Pa); stresses above it saturate. Display only.
+- **Downloads**: map PNG (scale bar + colourbar), CSV with metrics and parameters, and a PDF report that records the
+  input file, model, checkpoint SHA-256, substrate setting, pixel size, display and force-region settings and app
+  version. Batch mode gives a PDF (summary table + one page per image), a CSV, and a ZIP with, per image, the PNG and a
+  TIFF whose pixel values are traction stress in Pa (for measurements in Fiji/ImageJ). Set `S2F_APP_COMMIT` to add
+  the git commit.
 
 ## Full Project
 

S2FApp/app.py

@@ -17,18 +17,26 @@ S2F_ROOT = os.path.dirname(os.path.abspath(__file__))
 if S2F_ROOT not in sys.path:
     sys.path.insert(0, S2F_ROOT)
 
+from datetime import datetime, timezone
+
 from config.constants import (
+    APP_VERSION,
     BATCH_INFERENCE_SIZE,
     BATCH_MAX_IMAGES,
     COLORMAPS,
+    DEFAULT_IMAGE_UM_PER_PX,
     DEFAULT_SUBSTRATE,
     MODEL_TYPE_LABELS,
+    REFERENCE_SUBSTRATE,
     SAMPLE_EXTENSIONS,
     SAMPLE_THUMBNAIL_LIMIT,
+    SPHEROID_DEFAULT_CKP,
+    STRESS_MAX_PA,
 )
 from utils.paths import get_ckp_base, get_ckp_folder, get_sample_folder, list_files_in_folder, model_subfolder
 from utils.segmentation import estimate_cell_mask
-from utils.substrate_settings import list_substrates
+from utils.substrate_settings import get_settings_of_category, list_substrates
+from utils.units import make_scale
 from utils.display import apply_display_scale
 from ui.components import (
     build_original_vals,
@@ -98,7 +106,7 @@ def _get_measure_dialog_fn():
 
 def _populate_measure_session_state(heatmap, img, pixel_sum, force, key_img, colormap_name,
                                     display_mode, auto_cell_boundary, cell_mask=None,
-                                    clip_min=0, clip_max=1, clamp_only=False):
+                                    clip_min=0, clip_max=1, clamp_only=False, scale=None):
     """Populate session state for the measure tool. If cell_mask is None and auto_cell_boundary, computes it."""
     if cell_mask is None and auto_cell_boundary:
         cell_mask = estimate_cell_mask(heatmap)
@@ -109,10 +117,10 @@ def _populate_measure_session_state(heatmap, img, pixel_sum, force, key_img, col
     st.session_state["measure_clamp_only"] = clamp_only
     st.session_state["measure_bf_img"] = img.copy()
     st.session_state["measure_input_filename"] = key_img or "image"
-    st.session_state["measure_original_vals"] = build_original_vals(heatmap, pixel_sum, force)
+    st.session_state["measure_original_vals"] = build_original_vals(heatmap, pixel_sum, force, scale)
     st.session_state["measure_colormap"] = colormap_name
     st.session_state["measure_auto_cell_on"] = auto_cell_boundary
-    st.session_state["measure_cell_vals"] = build_cell_vals(heatmap, cell_mask, pixel_sum, force) if auto_cell_boundary else None
+    st.session_state["measure_cell_vals"] = build_cell_vals(heatmap, cell_mask, pixel_sum, force, scale) if auto_cell_boundary else None
     st.session_state["measure_cell_mask"] = cell_mask if auto_cell_boundary else None
 
 
@@ -131,7 +139,7 @@ if os.path.exists(_css_path):
 st.markdown("""
 <div class="s2f-header">
     <h1>🦠 Shape2Force (S2F)</h1>
-    <p>Predict traction force maps from bright-field microscopy images of cells or spheroids</p>
+    <p>Predict traction-stress magnitude maps (Pa) from bright-field microscopy images of cells or spheroids</p>
 </div>
 """, unsafe_allow_html=True)
 
@@ -228,12 +236,18 @@ with st.sidebar:
         ckp_files = list_files_in_folder(ckp_folder, ".pth")
         ckp_subfolder_name = model_subfolder(model_type)
 
+        if model_type == "spheroid" and SPHEROID_DEFAULT_CKP in ckp_files:
+            ckp_files = [SPHEROID_DEFAULT_CKP] + [f for f in ckp_files if f != SPHEROID_DEFAULT_CKP]
+        _ckp_notes = {"ckp_spheroid_FN.pth": "recommended: smoother maps, 11.8 M parameters",
+                      "ckp_spheroid_GN.pth": "S2F adversarial model, 77 M parameters",
+                      "ckp_singlecell_GN.pth": "S2F, as in the paper"}
         if ckp_files:
             checkpoint = st.selectbox(
                 "Checkpoint",
                 ckp_files,
                 key=f"checkpoint_{model_type}",
-                help=f"Select a .pth file from ckp/{ckp_subfolder_name}/",
+                format_func=lambda f: f"{f} ({_ckp_notes[f]})" if f in _ckp_notes else f,
+                help=f"Select a .pth file from ckp/{ckp_subfolder_name}/. The architecture is read from the checkpoint.",
             )
         else:
             st.warning(f"No .pth files in ckp/{ckp_subfolder_name}/. Add checkpoints to load.")
@@ -241,38 +255,60 @@ with st.sidebar:
 
     substrate_config = None
     substrate_val = DEFAULT_SUBSTRATE
-    use_manual = True
+    use_manual = False
+    substrate_mode_label = "reference"
     if model_type == "single_cell":
         try:
             with st.container(border=False, key="s2f_grp_conditions"):
-                st.markdown('<p class="s2f-form-label s2f-form-label--section">Conditions</p>', unsafe_allow_html=True)
+                st.markdown('<p class="s2f-form-label s2f-form-label--section">Substrate setting (model input)</p>', unsafe_allow_html=True)
                 conditions_source = st.radio(
-                    "Conditions",
-                    ["From config", "Manually"],
+                    "Substrate setting",
+                    ["Reference (6 kPa)", "Preset", "Manual"],
                     horizontal=True,
                     label_visibility="collapsed",
+                    help="The released model is most accurate with the 6 kPa reference setting for all images, "
+                         "including cells on 1 or 10 kPa gels (sensitivity analysis in the paper). Other settings "
+                         "rescale the prediction and are provided for exploration only.",
                 )
-                from_config = conditions_source == "From config"
-                if from_config:
-                    substrate_config = None
+                if conditions_source == "Reference (6 kPa)":
+                    substrate_val = REFERENCE_SUBSTRATE
+                    st.caption("Recommended. Used for all results in the paper.")
+                elif conditions_source == "Preset":
+                    substrate_mode_label = "preset"
                     substrates = list_substrates()
                     substrate_val = st.selectbox(
-                        "Conditions (from config)",
-                        substrates,
-                        help="Select a preset from config/substrate_settings.json",
-                        label_visibility="collapsed",
+                        "Preset", substrates,
+                        index=substrates.index(REFERENCE_SUBSTRATE) if REFERENCE_SUBSTRATE in substrates else 0,
+                        help="Presets from config/substrate_settings.json", label_visibility="collapsed",
                     )
-                    use_manual = False
+                    if get_settings_of_category(substrate_val) != get_settings_of_category(REFERENCE_SUBSTRATE):
+                        st.warning("Settings other than the 6 kPa reference reduce accuracy (e.g. the 1 kPa setting "
+                                   "makes predictions about 5 times smaller). Use for exploration only.")
                 else:
-                    manual_pixelsize = st.number_input("Pixel size (µm/px)", min_value=0.1, max_value=50.0,
-                                                       value=3.0769, step=0.1, format="%.4f")
-                    manual_young = st.number_input("Pascals", min_value=100.0, max_value=100000.0,
+                    substrate_mode_label = "manual"
+                    manual_pixelsize = st.number_input("Pixel-size setting (TFM units, as in training)", min_value=0.1,
+                                                       max_value=50.0, value=3.0769, step=0.1, format="%.4f",
+                                                       help="Training used 3.0769 (fibroblasts) to 9.8138.")
+                    manual_young = st.number_input("Young's modulus (Pa)", min_value=100.0, max_value=100000.0,
                                                    value=6000.0, step=100.0, format="%.0f")
                     substrate_config = {"pixelsize": manual_pixelsize, "young": manual_young}
                     use_manual = True
+                    if (abs(manual_pixelsize - 3.0769) > 1e-3) or manual_young != 6000.0:
+                        st.warning("Settings other than the 6 kPa reference reduce accuracy. Use for exploration only.")
         except FileNotFoundError:
             st.error("config/substrate_settings.json not found")
 
+    with st.container(border=False, key="s2f_grp_pixel"):
+        _def_px = DEFAULT_IMAGE_UM_PER_PX.get(model_type) or 0.0
+        image_um_per_px = st.number_input(
+            "Image pixel size (µm/px)",
+            min_value=0.0, max_value=100.0, value=float(_def_px), step=0.005, format="%.4f",
+            key=f"s2f_um_per_px_{model_type}",
+            help="Pixel size of the uploaded bright-field image, for the scale bar, area (µm²) and total force (nN). "
+                 "0 = unknown (only traction stress in Pa is reported). The single-cell training images "
+                 "(2048 x 2048 px) have 0.325 µm/px.",
+        ) or None
+
     batch_mode = st.toggle(
         "Batch mode",
         value=False,
@@ -280,18 +316,23 @@ with st.sidebar:
     )
 
     auto_cell_boundary = st.toggle(
-        "Auto boundary",
-        value=False,
-        help="When on: estimate cell region from force map and use it for metrics (red contour). When off: use entire map.",
+        "Measure force region only",
+        value=True,
+        help="On (recommended): the metrics are computed inside the region where the predicted traction stress is "
+             "high (red contour), so the empty background does not dilute the mean stress or the area. The region is "
+             "estimated automatically from the predicted map, not from the cell outline in the bright-field image. "
+             "Off: the metrics cover the whole image. For your own regions, use the Measure tool.",
     )
 
+    _smax = STRESS_MAX_PA["spheroid" if model_type == "spheroid" else "single_cell"]
     with st.container(border=False, key="s2f_grp_force"):
         force_scale_mode = st.radio(
-            "Force scale",
+            "Display range",
             ["Default", "Range"],
             horizontal=True,
             key="s2f_force_scale",
-            help="Default: display forces on the full 0–1 scale. Range: set a sub-range; values outside are zeroed and the rest is stretched to the colormap.",
+            help=f"Default: 0–{_smax:.0f} Pa (the full output scale of this model). Range: show a narrower window, "
+                 "e.g. 0–250 Pa; stresses above the window are shown in the top colour. Display only.",
         )
         if force_scale_mode == "Default":
             clip_min, clip_max = 0.0, 1.0
@@ -300,29 +341,14 @@ with st.sidebar:
         else:
             mn_col, mx_col = st.columns(2)
             with mn_col:
-                clip_min = st.number_input(
-                    "Min",
-                    min_value=0.0,
-                    max_value=1.0,
-                    value=0.0,
-                    step=0.01,
-                    format="%.2f",
-                    key="s2f_clip_min",
-                    help="Lower bound of the display range (0–1).",
-                )
+                lo_pa = st.number_input("Min (Pa)", min_value=0.0, max_value=_smax, value=0.0, step=_smax / 50,
+                                        format="%.0f", key=f"s2f_clip_min_pa_{model_type}")
             with mx_col:
-                clip_max = st.number_input(
-                    "Max",
-                    min_value=0.0,
-                    max_value=1.0,
-                    value=1.0,
-                    step=0.01,
-                    format="%.2f",
-                    key="s2f_clip_max",
-                    help="Upper bound of the display range (0–1).",
-                )
+                hi_pa = st.number_input("Max (Pa)", min_value=0.0, max_value=_smax, value=_smax, step=_smax / 50,
+                                        format="%.0f", key=f"s2f_clip_max_pa_{model_type}")
+            clip_min, clip_max = lo_pa / _smax, hi_pa / _smax
             if clip_min >= clip_max:
-                st.warning("Min must be less than max. Using 0.00–1.00 for display.")
+                st.warning(f"Min must be less than max. Using 0–{_smax:.0f} Pa.")
                 clip_min, clip_max = 0.0, 1.0
             display_mode = "Range"
             clamp_only = False
@@ -429,12 +455,40 @@ def _load_predictor(model_type, checkpoint, ckp_folder):
     )
 
 
+def _build_info(predictor, key_img, img, pred_time, image_um_per_px, display_mode, clip_min, clip_max, colormap_name,
+                auto_cell_boundary):
+    """Provenance of one prediction (shown in the app and written to CSV/PDF)."""
+    smax = STRESS_MAX_PA["spheroid" if predictor.model_type == "spheroid" else "single_cell"]
+    sub = None
+    if predictor.model_type == "single_cell":
+        settings = substrate_config if (use_manual and substrate_config) else get_settings_of_category(sub_val_for_info)
+        sub = {"mode": substrate_mode_label if substrate_mode_label != "reference" else "preset",
+               "name": None if use_manual else (sub_val_for_info + (" (reference)" if substrate_mode_label == "reference" else "")),
+               "pixelsize": float(settings["pixelsize"]), "young": float(settings["young"]),
+               **predictor.substrate_channels(sub_val_for_info, substrate_config if use_manual else None)}
+    rng = (clip_min * smax, clip_max * smax) if display_mode == "Range" else (0.0, smax)
+    return {
+        "input_file": key_img or "image", "time": pred_time, "model": predictor.describe(), "substrate": sub,
+        "image_shape": tuple(img.shape[:2]), "image_um_per_px": image_um_per_px, "stress_max_pa": smax,
+        "display": {"mode": display_mode, "range_pa": rng, "colormap": colormap_name},
+        "auto_boundary": bool(auto_cell_boundary), "app_version": APP_VERSION,
+        "app_commit": os.environ.get("S2F_APP_COMMIT", ""),
+    }
+
+
+sub_val_for_info = substrate_val if (model_type == "single_cell" and not use_manual) else DEFAULT_SUBSTRATE
+
+
 def _prepare_and_render_cached_result(r, key_img, colormap_name, display_mode, auto_cell_boundary,
                                      clip_min, clip_max, clamp_only,
                                      download_key_suffix="", check_measure_dialog=False,
                                      show_success=False):
     """Prepare display from cached result and render. Used by both just_ran and has_cached paths."""
     img, heatmap, force, pixel_sum = r["img"], r["heatmap"], r["force"], r["pixel_sum"]
+    predictor = _load_predictor(model_type, checkpoint, ckp_folder)
+    scale = make_scale(model_type, image_um_per_px, img.shape[:2], heatmap.shape)
+    info = _build_info(predictor, key_img, img, r.get("time", "–"), image_um_per_px, display_mode, clip_min, clip_max,
+                       colormap_name, auto_cell_boundary)
     display_heatmap = apply_display_scale(
         heatmap, display_mode,
         clip_min=clip_min,
@@ -445,7 +499,7 @@ def _prepare_and_render_cached_result(r, key_img, colormap_name, display_mode, a
     _populate_measure_session_state(
         heatmap, img, pixel_sum, force, key_img, colormap_name,
         display_mode, auto_cell_boundary, cell_mask=cell_mask,
-        clip_min=clip_min, clip_max=clip_max, clamp_only=clamp_only,
+        clip_min=clip_min, clip_max=clip_max, clamp_only=clamp_only, scale=scale,
     )
     if check_measure_dialog and st.session_state.pop("open_measure_dialog", False):
         measure_region_dialog()
@@ -460,9 +514,23 @@ def _prepare_and_render_cached_result(r, key_img, colormap_name, display_mode, a
         auto_cell_boundary=auto_cell_boundary,
         cell_mask=cell_mask,
         clip_min=clip_min, clip_max=clip_max, clamp_only=clamp_only,
+        scale=scale, info=info,
     )
 
 
+def _attach_batch_info(results):
+    """Physical scale and provenance for each batch result (depends on current sidebar settings)."""
+    predictor = _load_predictor(model_type, checkpoint, ckp_folder)
+    for r in results:
+        r["scale"] = make_scale(model_type, image_um_per_px, r["img"].shape[:2], r["heatmap"].shape)
+        r["info"] = _build_info(predictor, r["key_img"], r["img"], r.get("time", "–"), image_um_per_px, display_mode,
+                                clip_min, clip_max, colormap_name, auto_cell_boundary)
+
+
+def _utc_now():
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
+
+
 if just_ran_batch:
     st.session_state["prediction_result"] = None
     st.session_state["batch_results"] = None
@@ -484,6 +552,7 @@ if just_ran_batch:
                 pred_results.extend(chunk_results)
                 progress_bar.progress(min(start + len(chunk), n_images) / n_images,
                                      text=f"Predicting {len(pred_results)} / {n_images} images")
+            pred_time = _utc_now()
             batch_results = [
                 {
                     "img": img_b.copy(),
@@ -491,11 +560,13 @@ if just_ran_batch:
                     "force": force,
                     "pixel_sum": pixel_sum,
                     "key_img": key_b,
+                    "time": pred_time,
                     "cell_mask": estimate_cell_mask(heatmap) if auto_cell_boundary else None,
                 }
                 for (img_b, key_b), (heatmap, force, pixel_sum) in zip(imgs_batch, pred_results)
             ]
             st.session_state["batch_results"] = batch_results
+            _attach_batch_info(batch_results)
             progress_bar.empty()
             st.success(f"Prediction complete for {len(batch_results)} image(s)!")
             render_batch_results(
@@ -514,6 +585,7 @@ if just_ran_batch:
             st.code(traceback.format_exc())
 
 elif batch_mode and st.session_state.get("batch_results"):
+    _attach_batch_info(st.session_state["batch_results"])
     render_batch_results(
         st.session_state["batch_results"],
         colormap_name=colormap_name,
@@ -542,6 +614,7 @@ elif just_ran:
                 "force": force,
                 "pixel_sum": pixel_sum,
                 "cache_key": cache_key,
+                "time": _utc_now(),
             }
             st.session_state["prediction_result"] = r
             _prepare_and_render_cached_result(

S2FApp/config/constants.py

@@ -6,8 +6,36 @@ import cv2
 # Model & paths
 MODEL_INPUT_SIZE = 1024
 
-# Default substrate (used when config lookup fails or manual mode fallback)
+APP_VERSION = "1.1.0"   # shown in reports; the git commit is added from S2F_APP_COMMIT if set
+
+# Default substrate (used when config lookup fails or manual mode fallback).
+# 6 kPa reference setting: the released single-cell model is most accurate with it for every image
+# (sensitivity analysis in the paper's revision, Fig. S4), so it is the recommended input.
 DEFAULT_SUBSTRATE = "Fibroblasts_Fibronectin_6KPa"
+REFERENCE_SUBSTRATE = DEFAULT_SUBSTRATE
+
+# Normalisation of the two substrate channels: the ranges used in training (S2F config/substrate_settings.json).
+# Fixed here so that the model input does not depend on which presets the app lists.
+SETTINGS_NORMALIZATION = {"pixelsize": {"min": 3.0769, "max": 9.8138}, "young": {"min": 1000.0, "max": 10000.0}}
+
+# Physical scale of the output: the ground-truth maps were exported on a fixed colour scale,
+# so a normalised value of 1 corresponds to this traction stress.
+STRESS_MAX_PA = {"single_cell": 500.0, "spheroid": 50.0}
+
+# Default pixel size of the bright-field image (µm/px) offered in the sidebar; None = ask the user.
+# 0.325 µm/px is the pixel size of the 2048 x 2048 single-cell training images (TFM setting 3.0769 px/µm).
+DEFAULT_IMAGE_UM_PER_PX = {"single_cell": 0.325, "spheroid": None}
+
+# Spheroid checkpoints: default = the smaller supervised model (FN), which gives smoother maps and similar accuracy
+# (validation, 28 spheroids: pixel r 0.88 vs 0.88, RME 0.44 vs 0.47, MS-SSIM 0.79 vs 0.74 for the S2F/GN model)
+SPHEROID_DEFAULT_CKP = "ckp_spheroid_FN.pth"
+ARCH_LABELS = {
+    "s2f": "S2F generator (attention U-Net + PatchGAN training), 77.0 M parameters",
+    "s2f_spheroid": "Supervised attention U-Net (no discriminator), 11.8 M parameters",
+}
+
+# Auto-boundary parameters (utils/segmentation.estimate_cell_mask defaults), recorded in reports
+AUTO_BOUNDARY_DESCRIPTION = "high-stress region from the predicted map: Otsu threshold x 0.85 after Gaussian smoothing (sigma 2 px), dilated by 4 px"
 
 # UI
 CANVAS_SIZE = 320

S2FApp/download_ckp.py

@@ -14,12 +14,8 @@ if not has_any:
         repo = os.environ.get("HF_MODEL_REPO", "Angione-Lab/Shape2Force")
         files = list_repo_files(repo)
         pth_files = [f for f in files if f.startswith("ckp/") and f.endswith(".pth")]
-        # For spheroid: only download ckp_spheroid_FN.pth (not ckp_spheroid_GN.pth or others)
-        def should_download(f):
-            if "spheroid" in f and "ckp_spheroid_FN.pth" not in f:
-                return False
-            return True
-        pth_files = [f for f in pth_files if should_download(f)]
+        # All checkpoints: single cell (S2F), spheroid S2F (ckp_spheroid_GN.pth, the model reported in the paper
+        # and the app default) and the smaller supervised spheroid model (ckp_spheroid_FN.pth).
         for f in pth_files:
             hf_hub_download(repo_id=repo, filename=f, local_dir="/app")
         print("Downloaded checkpoints from", repo)

S2FApp/predictor.py

@@ -2,6 +2,7 @@
 Core inference logic for S2F (Shape2Force).
 Predicts force maps from bright field microscopy images.
 """
+import hashlib
 import os
 import sys
 import cv2
@@ -77,9 +78,34 @@ def create_settings_channels_single(substrate_name, device, height, width, confi
     return torch.cat([pixelsize_ch, young_ch], dim=1)
 
 
+def file_sha256(path, chunk=1 << 20):
+    """SHA-256 of a file (recorded in reports so a prediction can be traced to its checkpoint)."""
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for block in iter(lambda: f.read(chunk), b""):
+            h.update(block)
+    return h.hexdigest()
+
+
+def detect_architecture(state_dict):
+    """
+    Generator architecture from the checkpoint keys:
+      's2f'          S2FGenerator (multi-scale input 'scale_pyramid.*'); tanh output -> (y + 1) / 2
+      's2f_spheroid' supervised attention U-Net ('encoder1.*'); sigmoid output in [0, 1]
+    """
+    keys = list(state_dict.keys())
+    if any(k.startswith("scale_pyramid.") or k.startswith("initial_conv.") for k in keys):
+        return "s2f"
+    if any(k.startswith("encoder1.") for k in keys):
+        return "s2f_spheroid"
+    raise ValueError("Unrecognised checkpoint: neither S2FGenerator nor the supervised spheroid model")
+
+
 class S2FPredictor:
     """
     Shape2Force predictor for single-cell or spheroid force map prediction.
+    The generator architecture is selected from the checkpoint itself, so both spheroid checkpoints
+    (ckp_spheroid_GN.pth = S2F generator as in the paper, ckp_spheroid_FN.pth = smaller supervised model) load.
     """
 
     def __init__(self, model_type="single_cell", checkpoint_path=None, ckp_folder=None, device=None):
@@ -97,37 +123,58 @@ class S2FPredictor:
         ckp_dir = ckp_folder if ckp_folder else os.path.join(ckp_base, subfolder)
         if not os.path.isdir(ckp_dir):
             ckp_dir = ckp_base  # fallback if subfolders not used
-
-        in_channels = 3 if model_type == "single_cell" else 1
-        s2f_model_type = "s2f" if model_type == "single_cell" else "s2f_spheroid"
-        generator, _ = create_s2f_model(in_channels=in_channels, model_type=s2f_model_type)
-        self.generator = generator
-
-        if checkpoint_path:
-            full_path = checkpoint_path
-            if not os.path.isabs(checkpoint_path):
-                full_path = os.path.join(ckp_dir, checkpoint_path)
-            if not os.path.exists(full_path):
-                full_path = os.path.join(ckp_base, checkpoint_path)  # try base folder
-            if not os.path.exists(full_path):
-                raise FileNotFoundError(f"Checkpoint not found: {full_path}")
-
-            if model_type == "single_cell":
-                self.generator.load_checkpoint_with_expansion(full_path, strict=True)
-            else:
-                checkpoint = torch.load(full_path, map_location="cpu", weights_only=False)
-                state = checkpoint.get("generator_state_dict") or checkpoint.get("model_state_dict") or checkpoint
-                self.generator.load_state_dict(state, strict=True)
-                if hasattr(self.generator, "set_output_mode"):
-                    self.generator.set_output_mode(use_tanh=False)  # sigmoid [0,1] for inference
-
-        self.generator = self.generator.to(self.device)
-        self.generator.eval()
-
+        if not checkpoint_path:
+            raise ValueError("checkpoint_path is required")
+
+        full_path = checkpoint_path
+        if not os.path.isabs(checkpoint_path):
+            full_path = os.path.join(ckp_dir, checkpoint_path)
+        if not os.path.exists(full_path):
+            full_path = os.path.join(ckp_base, checkpoint_path)  # try base folder
+        if not os.path.exists(full_path):
+            raise FileNotFoundError(f"Checkpoint not found: {full_path}")
+
+        checkpoint = torch.load(full_path, map_location="cpu", weights_only=False)
+        state = checkpoint.get("generator_state_dict") or checkpoint.get("model_state_dict") or checkpoint
+        self.architecture = detect_architecture(state)
+        self.in_channels = 3 if model_type == "single_cell" else 1
+        generator, _ = create_s2f_model(in_channels=self.in_channels, model_type=self.architecture)
+        if model_type == "single_cell":
+            generator.load_checkpoint_with_expansion(full_path, strict=True)
+        else:
+            generator.load_state_dict(state, strict=True)
+        if self.architecture == "s2f_spheroid" and hasattr(generator, "set_output_mode"):
+            generator.set_output_mode(use_tanh=False)  # trained with sigmoid output in [0, 1]
+        self._use_tanh_output = self.architecture == "s2f"  # S2FGenerator: tanh in [-1, 1]
+
+        self.generator = generator.to(self.device).eval()
+        self.checkpoint_name = os.path.basename(full_path)
+        self.checkpoint_sha256 = file_sha256(full_path)
+        self.checkpoint_epoch = checkpoint.get("epoch") if isinstance(checkpoint, dict) else None
+        self.n_params = sum(p.numel() for p in self.generator.parameters())
         self.norm_params = compute_settings_normalization() if model_type == "single_cell" else None
-        self._use_tanh_output = model_type == "single_cell"  # single_cell uses tanh, spheroid uses sigmoid
         self.config_path = os.path.join(S2F_ROOT, "config", "substrate_settings.json")
 
+    def describe(self):
+        """Model information for reports."""
+        return {
+            "model_type": self.model_type,
+            "architecture": self.architecture,
+            "checkpoint": self.checkpoint_name,
+            "checkpoint_sha256": self.checkpoint_sha256,
+            "checkpoint_epoch": self.checkpoint_epoch,
+            "n_params_M": round(self.n_params / 1e6, 1),
+            "device": str(self.device),
+        }
+
+    def substrate_channels(self, substrate=None, substrate_config=None):
+        """Values of the two substrate input channels (normalised pixel-size and Young's-modulus settings)."""
+        if self.model_type != "single_cell":
+            return None
+        ch = create_settings_channels_single(substrate if substrate is not None else DEFAULT_SUBSTRATE, "cpu", 1, 1,
+                                             config_path=self.config_path, substrate_config=substrate_config)
+        return {"pixelsize_norm": float(ch[0, 0, 0, 0]), "young_norm": float(ch[0, 1, 0, 0])}
+
     def predict(self, image_path=None, image_array=None, substrate=None,
                 substrate_config=None):
         """
@@ -171,7 +218,7 @@ class S2FPredictor:
 
         if self._use_tanh_output:
             pred = (pred + 1.0) / 2.0  # Tanh [-1,1] to [0, 1]
-        # else: spheroid already outputs sigmoid [0, 1]
+        # else: the supervised spheroid model already outputs sigmoid [0, 1]
         heatmap = pred[0, 0].cpu().numpy()
         force = sum_force_map(pred).item()
         pixel_sum = float(np.sum(heatmap))

S2FApp/ui/heatmaps.py

@@ -44,22 +44,32 @@ def _draw_region_overlay(annotated, mask, color, fill_alpha=0.3, stroke_width=2)
     cv2.drawContours(annotated, contours, -1, color, stroke_width)
 
 
-def render_horizontal_colorbar(colormap_name, clip_min=0, clip_max=1, is_rescale=False, caption=None):
+def colorbar_ticks_pa(clip_min=0.0, clip_max=1.0, stress_max_pa=500.0, n=5):
+    """Tick positions (0-1 along the colormap) and labels in Pa at round values for the displayed window."""
+    lo, hi = float(clip_min), float(clip_max)
+    if not hi > lo:
+        lo, hi = 0.0, 1.0
+    lo_pa, hi_pa = lo * stress_max_pa, hi * stress_max_pa
+    span = hi_pa - lo_pa
+    raw = span / max(n - 1, 1)
+    k = 10 ** np.floor(np.log10(raw))
+    step = min((m * k for m in (1, 2, 2.5, 5, 10)), key=lambda st_: abs(st_ - raw))
+    first = np.ceil(lo_pa / step - 1e-9) * step
+    vals = np.arange(first, hi_pa + 1e-9, step) + 0.0   # +0.0 turns -0 into 0
+    pos = [float((v - lo_pa) / span) for v in vals]
+    labels = [f"{v:g}" for v in vals]
+    return pos, labels
+
+
+def render_horizontal_colorbar(colormap_name, clip_min=0, clip_max=1, is_rescale=False, caption=None,
+                               stress_max_pa=500.0):
     """
-    Render a compact horizontal colorbar for batch mode, anchored above the table.
-
-    When ``is_rescale`` is True (Force scale **Range** with a strict sub-interval), tick labels show
-    model force values in ``[clip_min, clip_max]``. The gradient still spans the full colormap because
-    the heatmap has already been **rescaled** so the lowest (highest) value in your range maps to
-    the colormap minimum (maximum)—same convention as the main Plotly view.
+    Compact horizontal colorbar (batch mode) labelled in Pa. With a display window (Range mode) the gradient
+    spans the window [clip_min, clip_max]; values above it are shown in the top colour.
     """
-    ticks = [0, 0.25, 0.5, 0.75, 1]
-    if is_rescale:
-        rng = clip_max - clip_min
-        labels = [f"{clip_min + t * rng:.2f}" for t in ticks]
-    else:
-        labels = [f"{t:.2f}" for t in ticks]
-
+    ticks, labels = colorbar_ticks_pa(clip_min, clip_max, stress_max_pa)
+    if not is_rescale:
+        ticks, labels = colorbar_ticks_pa(0.0, 1.0, stress_max_pa)
     data_url = _colormap_gradient_base64(colormap_name)
     labels_html = "".join(f'<span class="cb-tick">{l}</span>' for l in labels)
     html = f"""
@@ -69,8 +79,7 @@ def render_horizontal_colorbar(colormap_name, clip_min=0, clip_max=1, is_rescale
     </div>
     """
     st.markdown(html, unsafe_allow_html=True)
-    if caption:
-        st.caption(caption)
+    st.caption(caption or "Traction stress (Pa)")
 
 
 def make_annotated_heatmap(heatmap_rgb, mask, fill_alpha=0.3, stroke_color=(0, 188, 212), stroke_width=2):

S2FApp/ui/measure_tool.py

@@ -12,6 +12,7 @@ from PIL import Image
 from config.constants import CANVAS_SIZE, DRAW_TOOLS, TOOL_LABELS
 from utils.report import heatmap_to_rgb_with_contour, create_measure_pdf_report
 from ui.heatmaps import make_annotated_heatmap_multi_regions
+from utils.units import fmt, make_scale, region_metrics
 
 try:
     from streamlit_drawable_canvas import st_canvas
@@ -94,66 +95,32 @@ def parse_canvas_shapes_to_masks(json_data, canvas_h, canvas_w, heatmap_h, heatm
     return masks
 
 
-def build_original_vals(raw_heatmap, pixel_sum, force):
-    """Build original_vals dict for measure tool (full map)."""
-    return {
-        "pixel_sum": pixel_sum,
-        "force": force,
-        "max": float(np.max(raw_heatmap)),
-        "mean": float(np.mean(raw_heatmap)),
-    }
+def build_original_vals(raw_heatmap, pixel_sum, force, scale=None):
+    """Whole-map values for the measure tool (physical units when `scale` is given; see utils/units.py)."""
+    scale = scale or make_scale("single_cell")
+    m = region_metrics(raw_heatmap, None, scale)
+    return {"pixel_sum": pixel_sum, "force": force, "scale": scale, **m}
 
 
-def _compute_cell_metrics(raw_heatmap, cell_mask, pixel_sum, force):
-    """Compute metrics over estimated cell area only."""
-    area_px = int(np.sum(cell_mask))
-    if area_px == 0:
-        return None, None, None
-    region_values = raw_heatmap * cell_mask
-    cell_pixel_sum = float(np.sum(region_values))
-    cell_force = cell_pixel_sum * (force / pixel_sum) if pixel_sum > 0 else cell_pixel_sum
-    cell_mean = cell_pixel_sum / area_px
-    return cell_pixel_sum, cell_force, cell_mean
+def _compute_cell_metrics(raw_heatmap, cell_mask, pixel_sum, force, scale=None):
+    """Metrics over the estimated cell area: dict from utils.units.region_metrics, or None if the mask is empty."""
+    if cell_mask is None or int(np.sum(cell_mask)) == 0:
+        return None
+    return region_metrics(raw_heatmap, cell_mask, scale or make_scale("single_cell"))
 
 
-def build_cell_vals(raw_heatmap, cell_mask, pixel_sum, force):
-    """Build cell_vals dict for measure tool (estimated cell area). Returns None if invalid."""
-    cell_pixel_sum, cell_force, cell_mean = _compute_cell_metrics(raw_heatmap, cell_mask, pixel_sum, force)
-    if cell_pixel_sum is None:
+def build_cell_vals(raw_heatmap, cell_mask, pixel_sum, force, scale=None):
+    """Values over the estimated cell area for the measure tool. Returns None if invalid."""
+    m = _compute_cell_metrics(raw_heatmap, cell_mask, pixel_sum, force, scale)
+    if m is None:
         return None
-    region_values = raw_heatmap * cell_mask
-    region_nonzero = region_values[cell_mask > 0]
-    cell_max = float(np.max(region_nonzero)) if len(region_nonzero) > 0 else 0
-    return {
-        "pixel_sum": cell_pixel_sum,
-        "force": cell_force,
-        "max": cell_max,
-        "mean": cell_mean,
-    }
+    return {"scale": scale, **m}
 
 
 def compute_region_metrics(raw_heatmap, mask, original_vals=None):
-    """Compute region metrics from mask."""
-    area_px = int(np.sum(mask))
-    region_values = raw_heatmap * mask
-    region_nonzero = region_values[mask > 0]
-    force_sum = float(np.sum(region_values))
-    density = force_sum / area_px if area_px > 0 else 0
-    region_max = float(np.max(region_nonzero)) if len(region_nonzero) > 0 else 0
-    region_mean = float(np.mean(region_nonzero)) if len(region_nonzero) > 0 else 0
-    region_force_scaled = (
-        force_sum * (original_vals["force"] / original_vals["pixel_sum"])
-        if original_vals and original_vals.get("pixel_sum", 0) > 0
-        else force_sum
-    )
-    return {
-        "area_px": area_px,
-        "force_sum": force_sum,
-        "density": density,
-        "max": region_max,
-        "mean": region_mean,
-        "force_scaled": region_force_scaled,
-    }
+    """Region metrics in physical units (area µm², total force nN, mean/max traction stress Pa)."""
+    scale = (original_vals or {}).get("scale") or make_scale("single_cell")
+    return region_metrics(raw_heatmap, mask, scale)
 
 
 def _draw_contour_on_image(img_rgb, mask, stroke_color=(255, 0, 0), stroke_width=3):
@@ -171,29 +138,19 @@ def render_region_metrics_and_downloads(metrics_list, masks, heatmap_rgb, input_
                                         first_region_label=None, bf_img=None, cell_mask=None, colormap_name="Jet"):
     """
     Render per-shape metrics table and download buttons.
-    first_region_label: custom label for first row (e.g. 'Auto boundary').
+    first_region_label: custom label for first row (e.g. 'Force region').
     masks: list of region masks (user-drawn only; used for labeled heatmap with R1, R2...).
     """
     base_name = os.path.splitext(input_filename or "image")[0]
     st.markdown("**Regions (each selection = one row)**")
-    if has_original_vals:
-        headers = ["Region", "Area", "F.sum", "Force", "Max", "Mean"]
-        csv_rows = [["image", "region"] + headers[1:]]
-    else:
-        headers = ["Region", "Area (px²)", "Force sum", "Mean"]
-        csv_rows = [["image", "region", "Area", "Force sum", "Mean"]]
+    headers = ["Region", "Area (µm²)", "Total force (nN)", "Mean stress (Pa)", "Max stress (Pa)"]
+    csv_rows = [["image", "region", "area_um2", "total_force_nN", "mean_stress_Pa", "max_stress_Pa", "n_pixels"]]
     table_rows = [headers]
     for i, metrics in enumerate(metrics_list, 1):
         region_label = first_region_label if (i == 1 and first_region_label) else f"Region {i - (1 if first_region_label else 0)}"
-        if has_original_vals:
-            row = [region_label, str(metrics["area_px"]), f"{metrics['force_sum']:.3f}", f"{metrics['force_scaled']:.1f}",
-                   f"{metrics['max']:.3f}", f"{metrics['mean']:.4f}"]
-            csv_rows.append([base_name, region_label, metrics["area_px"], f"{metrics['force_sum']:.3f}",
-                            f"{metrics['force_scaled']:.1f}", f"{metrics['max']:.3f}", f"{metrics['mean']:.4f}"])
-        else:
-            row = [region_label, str(metrics["area_px"]), f"{metrics['force_sum']:.4f}", f"{metrics['mean']:.6f}"]
-            csv_rows.append([base_name, region_label, metrics["area_px"], f"{metrics['force_sum']:.4f}",
-                            f"{metrics['mean']:.6f}"])
+        row = [region_label, fmt(metrics["area_um2"], nd=0), fmt(metrics["total_force_nN"], nd=2),
+               fmt(metrics["mean_pa"], nd=1), fmt(metrics["max_pa"], nd=1)]
+        csv_rows.append([base_name, region_label] + row[1:] + [metrics["n_px"]])
         table_rows.append(row)
     # Render as HTML table to avoid Streamlit's default row/column indices
     header = table_rows[0]
@@ -273,14 +230,14 @@ def render_region_canvas(display_heatmap, raw_heatmap=None, bf_img=None, origina
         with right_col:
             vals = cell_vals if cell_vals else original_vals
             if vals:
-                label = "Cell area" if cell_vals else "Full map"
+                label = "Force region" if cell_vals else "Full map"
                 st.markdown(
                     f'<p class="s2f-measure-vals-heading">{html.escape(label)}</p>'
                     f'<div class="s2f-measure-vals-panel"><div class="s2f-measure-vals-grid">'
-                    f"<span><strong>Sum:</strong> {vals['pixel_sum']:.1f}</span>"
-                    f"<span><strong>Force:</strong> {vals['force']:.1f}</span>"
-                    f"<span><strong>Max:</strong> {vals['max']:.3f}</span>"
-                    f"<span><strong>Mean:</strong> {vals['mean']:.3f}</span>"
+                    f"<span><strong>Mean:</strong> {fmt(vals.get('mean_pa'), 'Pa')}</span>"
+                    f"<span><strong>Max:</strong> {fmt(vals.get('max_pa'), 'Pa')}</span>"
+                    f"<span><strong>Area:</strong> {fmt(vals.get('area_um2'), 'µm²', 0)}</span>"
+                    f"<span><strong>Force:</strong> {fmt(vals.get('total_force_nN'), 'nN', 2)}</span>"
                     f"</div></div>",
                     unsafe_allow_html=True,
                 )
@@ -311,6 +268,6 @@ def render_region_canvas(display_heatmap, raw_heatmap=None, bf_img=None, origina
                 metrics_list = [cell_metrics] + metrics_list
             render_region_metrics_and_downloads(
                 metrics_list, masks, heatmap_rgb, input_filename, key_suffix, original_vals is not None,
-                first_region_label="Auto boundary" if (cell_mask is not None and np.any(cell_mask > 0)) else None,
+                first_region_label="Force region" if (cell_mask is not None and np.any(cell_mask > 0)) else None,
                 bf_img=bf_img, cell_mask=cell_mask, colormap_name=colormap_name,
             )

S2FApp/ui/result_display.py

@@ -1,4 +1,4 @@
-"""Result display: single and batch prediction views."""
+"""Result display: single and batch prediction views (traction stress in Pa, areas in µm², forces in nN)."""
 import csv
 import io
 import os
@@ -11,21 +11,29 @@ import plotly.graph_objects as go
 from plotly.subplots import make_subplots
 
 from utils.display import apply_display_scale, cv_colormap_to_plotly_colorscale, is_display_range_remapped
-from utils.report import heatmap_to_rgb_with_contour, heatmap_to_png_bytes, create_pdf_report
+from utils.report import (create_batch_pdf_report, create_pdf_report, heatmap_figure_png_bytes,
+                          heatmap_to_rgb_with_contour, info_rows)
 from utils.segmentation import estimate_cell_mask
-from ui.heatmaps import render_horizontal_colorbar, add_cell_contour_to_fig
+from utils.units import fmt, make_scale, metric_rows, nice_scale_bar_um, region_metrics, to_pa
+from ui.heatmaps import colorbar_ticks_pa, render_horizontal_colorbar, add_cell_contour_to_fig
 from ui.measure_tool import (
     build_original_vals,
     build_cell_vals,
     render_region_canvas,
-    _compute_cell_metrics,
     HAS_DRAWABLE_CANVAS,
 )
 
 # Histogram bar color (matches static/s2f_styles.css accent)
 _HISTOGRAM_ACCENT = "#0d9488"
-_RESULT_FIG_HEIGHT = 320
+_RESULT_FIG_HEIGHT = 340
 _HISTOGRAM_HEIGHT = 180
+_METRIC_HELP = {
+    "Mean traction stress": "Mean predicted traction-stress magnitude over the region (Pa)",
+    "Max traction stress": "Peak predicted traction-stress magnitude (Pa)",
+    "Area": "Region area in µm² (needs the image pixel size)",
+    "Total force": "Sum of traction stress × pixel area, in nN (needs the image pixel size). Magnitudes only: "
+                   "vector cancellation is not taken into account",
+}
 
 
 def _result_banner(badge: str, badge_class: str, title: str) -> str:
@@ -35,284 +43,266 @@ def _result_banner(badge: str, badge_class: str, title: str) -> str:
     )
 
 
+def _metrics_csv(base_name, metrics_full, metrics_cell, info):
+    """CSV: one row of metrics with units, then the parameters needed to reproduce the prediction."""
+    rows = [["image", "region", "mean_stress_Pa", "max_stress_Pa", "area_um2", "total_force_nN", "n_pixels"]]
+    for region, m in [("whole_field", metrics_full), ("force_region", metrics_cell)]:
+        if m:
+            rows.append([base_name, region, fmt(m["mean_pa"], nd=2), fmt(m["max_pa"], nd=2), fmt(m["area_um2"], nd=1),
+                         fmt(m["total_force_nN"], nd=3), m["n_px"]])
+    rows += [[], ["parameter", "value"]] + [[k.strip(), v] for k, v in info_rows(info)]
+    buf = io.StringIO()
+    csv.writer(buf).writerows(rows)
+    return buf.getvalue()
+
+
+def _add_scale_bar_to_fig(fig, width_px, height_px, um_per_px, row, col):
+    """Draw a µm scale bar (bottom right) on a Plotly image subplot whose axes are in pixels."""
+    if not um_per_px:
+        return
+    length_um = nice_scale_bar_um(width_px * um_per_px)
+    if not length_um:
+        return
+    length_px = length_um / um_per_px
+    m = 0.05 * width_px
+    x1, y = width_px - m, height_px - m
+    xref = "x" if (row, col) == (1, 1) else "x2"
+    yref = "y" if (row, col) == (1, 1) else "y2"
+    fig.add_shape(type="line", x0=x1 - length_px, x1=x1, y0=y, y1=y, xref=xref, yref=yref,
+                  line=dict(color="white", width=4))
+    fig.add_annotation(x=x1 - length_px / 2, y=y - 0.03 * height_px, xref=xref, yref=yref, text=f"{length_um:g} µm",
+                       showarrow=False, font=dict(color="white", size=11))
+
+
 def render_batch_results(batch_results, colormap_name="Jet", display_mode="Default",
-                        clip_min=0, clip_max=1,
-                        auto_cell_boundary=False, clamp_only=False):
+                         clip_min=0, clip_max=1,
+                         auto_cell_boundary=False, clamp_only=False):
     """
-    Render batch prediction results: summary table, bright-field row, heatmap row, and bulk download.
-    batch_results: list of dicts with img, heatmap, force, pixel_sum, key_img, cell_mask.
-    cell_mask is computed on-the-fly when auto_cell_boundary is True and not stored.
+    Render batch prediction results: summary table (units), bright-field row, heatmap row and bulk downloads.
+    batch_results: list of dicts with img, heatmap, key_img, cell_mask, scale, info.
     """
     if not batch_results:
         return
 
-    # Resolve cell_mask and precompute display_heatmap for each result
     for r in batch_results:
         if auto_cell_boundary and (r.get("cell_mask") is None or not np.any(r.get("cell_mask", 0) > 0)):
             r["_cell_mask"] = estimate_cell_mask(r["heatmap"])
         else:
             r["_cell_mask"] = r.get("cell_mask") if auto_cell_boundary else None
-        r["_display_heatmap"] = apply_display_scale(
-            r["heatmap"], display_mode,
-            clip_min=clip_min, clip_max=clip_max, clamp_only=clamp_only,
-        )
-    # Build table rows - consistent column names for both modes
-    headers = ["Image", "Force", "Sum", "Max", "Mean"]
+        r["_display_heatmap"] = apply_display_scale(r["heatmap"], display_mode, clip_min=clip_min, clip_max=clip_max)
+        r["_metrics"] = region_metrics(r["heatmap"], r["_cell_mask"] if auto_cell_boundary else None, r["scale"])
+
+    region = "force region (red contour)" if auto_cell_boundary else "whole field"
+    headers = ["Image", "Mean stress (Pa)", "Max stress (Pa)", "Area (µm²)", "Total force (nN)"]
     rows = []
-    csv_rows = [["image"] + headers[1:]]
+    csv_rows = [["image", "region", "mean_stress_Pa", "max_stress_Pa", "area_um2", "total_force_nN", "n_pixels",
+                 "model", "checkpoint", "checkpoint_sha256", "substrate_setting", "image_um_per_px", "stress_max_Pa",
+                 "app_version"]]
     for r in batch_results:
-        heatmap = r["heatmap"]
-        cell_mask = r.get("_cell_mask")
-        key = r["key_img"] or "image"
-        if auto_cell_boundary and cell_mask is not None and np.any(cell_mask > 0):
-            vals = heatmap[cell_mask > 0]
-            cell_pixel_sum = float(np.sum(vals))
-            cell_force = cell_pixel_sum * (r["force"] / r["pixel_sum"]) if r["pixel_sum"] > 0 else cell_pixel_sum
-            cell_mean = cell_pixel_sum / np.sum(cell_mask) if np.sum(cell_mask) > 0 else 0
-            row = [key, f"{cell_force:.2f}", f"{cell_pixel_sum:.2f}",
-                   f"{np.max(heatmap):.4f}", f"{cell_mean:.4f}"]
-        else:
-            row = [key, f"{r['force']:.2f}", f"{r['pixel_sum']:.2f}",
-                   f"{np.max(heatmap):.4f}", f"{np.mean(heatmap):.4f}"]
-        rows.append(row)
-        csv_rows.append([os.path.splitext(key)[0]] + row[1:])
+        m, key, info = r["_metrics"], r["key_img"] or "image", r.get("info", {})
+        rows.append([key, fmt(m["mean_pa"], nd=1), fmt(m["max_pa"], nd=1), fmt(m["area_um2"], nd=0),
+                     fmt(m["total_force_nN"], nd=2)])
+        sub = info.get("substrate") or {}
+        csv_rows.append([os.path.splitext(key)[0], region, fmt(m["mean_pa"], nd=2), fmt(m["max_pa"], nd=2),
+                         fmt(m["area_um2"], nd=1), fmt(m["total_force_nN"], nd=3), m["n_px"],
+                         info.get("model", {}).get("architecture", ""), info.get("model", {}).get("checkpoint", ""),
+                         info.get("model", {}).get("checkpoint_sha256", ""),
+                         sub.get("name") or (f"manual {sub.get('pixelsize')}/{sub.get('young')}" if sub else ""),
+                         info.get("image_um_per_px") or "", info.get("stress_max_pa", ""), info.get("app_version", "")])
     st.markdown(_result_banner("INPUT", "input", "Bright-field images"), unsafe_allow_html=True)
     n_cols = min(5, len(batch_results))
     bf_cols = st.columns(n_cols)
     for i, r in enumerate(batch_results):
         img = r["img"]
-        if img.ndim == 2:
-            img_rgb = cv2.cvtColor(img, cv2.COLOR_GRAY2RGB)
-        else:
-            img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+        img_rgb = cv2.cvtColor(img, cv2.COLOR_GRAY2RGB) if img.ndim == 2 else cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
         with bf_cols[i % n_cols]:
             st.image(img_rgb, caption=r["key_img"], use_container_width=True)
     is_rescale_b = is_display_range_remapped(display_mode, clip_min, clip_max)
-    st.markdown(_result_banner("OUTPUT", "output", "Predicted force maps"), unsafe_allow_html=True)
+    st.markdown(_result_banner("OUTPUT", "output", "Predicted traction-stress maps"), unsafe_allow_html=True)
     hm_cols = st.columns(n_cols)
     for i, r in enumerate(batch_results):
-        hm_rgb = heatmap_to_rgb_with_contour(
-            r["_display_heatmap"], colormap_name,
-            r.get("_cell_mask") if auto_cell_boundary else None,
-        )
+        hm_rgb = heatmap_to_rgb_with_contour(r["_display_heatmap"], colormap_name,
+                                             r.get("_cell_mask") if auto_cell_boundary else None)
         with hm_cols[i % n_cols]:
             st.image(hm_rgb, caption=r["key_img"], use_container_width=True)
-    render_horizontal_colorbar(colormap_name, clip_min, clip_max, is_rescale_b)
-    # Table
-    st.dataframe(
-        {h: [r[i] for r in rows] for i, h in enumerate(headers)},
-        use_container_width=True,
-        hide_index=True,
-    )
-    # Histograms in accordion (one per row for visibility)
-    with st.expander("Force distribution (histograms)", expanded=False):
+    smax = batch_results[0]["scale"]["stress_max_pa"]
+    render_horizontal_colorbar(colormap_name, clip_min, clip_max, is_rescale_b, stress_max_pa=smax)
+    st.dataframe({h: [row[i] for row in rows] for i, h in enumerate(headers)}, use_container_width=True, hide_index=True)
+    st.caption(f"Metrics over the {region}. Area and total force need the image pixel size (sidebar).")
+    with st.expander("Traction-stress distribution (histograms)", expanded=False):
         for i, r in enumerate(batch_results):
-            heatmap = r["heatmap"]
             cell_mask = r.get("_cell_mask")
-            vals = heatmap[cell_mask > 0] if (cell_mask is not None and np.any(cell_mask > 0) and auto_cell_boundary) else heatmap.flatten()
+            vals = to_pa(r["heatmap"], r["scale"])
+            vals = vals[cell_mask > 0] if (cell_mask is not None and np.any(cell_mask > 0) and auto_cell_boundary) else vals.ravel()
             vals = vals[vals > 0] if np.any(vals > 0) else vals
             st.markdown(f"**{r['key_img']}**")
             if len(vals) > 0:
                 fig = go.Figure(data=[go.Histogram(x=vals, nbinsx=50, marker_color=_HISTOGRAM_ACCENT)])
-                fig.update_layout(
-                    height=_HISTOGRAM_HEIGHT, margin=dict(l=40, r=20, t=10, b=40),
-                    xaxis_title="Force value", yaxis_title="Count",
-                    showlegend=False,
-                )
+                fig.update_layout(height=_HISTOGRAM_HEIGHT, margin=dict(l=40, r=20, t=10, b=40),
+                                  xaxis_title="Traction stress (Pa)", yaxis_title="Pixels", showlegend=False)
                 st.plotly_chart(fig, use_container_width=True, config={"displayModeBar": False})
             else:
                 st.caption("No data")
             if i < len(batch_results) - 1:
                 st.divider()
-    # Bulk downloads: CSV and heatmaps (zip)
     buf_csv = io.StringIO()
     csv.writer(buf_csv).writerows(csv_rows)
+    lo_b, hi_b = (clip_min, clip_max) if is_rescale_b else (0.0, 1.0)
     zip_buf = io.BytesIO()
     with zipfile.ZipFile(zip_buf, "w", zipfile.ZIP_DEFLATED) as zf:
         for r in batch_results:
-            hm_bytes = heatmap_to_png_bytes(
-                r["_display_heatmap"], colormap_name,
-                r.get("_cell_mask") if auto_cell_boundary else None,
-            )
             base = os.path.splitext(r["key_img"] or "image")[0]
-            zf.writestr(f"{base}_heatmap.png", hm_bytes.getvalue())
+            png = heatmap_figure_png_bytes(r["_display_heatmap"], colormap_name,
+                                           r.get("_cell_mask") if auto_cell_boundary else None, r["scale"], lo_b, hi_b)
+            zf.writestr(f"{base}_traction_stress.png", png.getvalue())
+            zf.writestr(f"{base}_traction_stress_Pa.tif", _tiff_pa_bytes(r["heatmap"], r["scale"]))
+        zf.writestr("README.txt", _ZIP_README.format(smax=smax))
     zip_buf.seek(0)
-    dl_col1, dl_col2 = st.columns(2)
+    pdf_items = [dict(img=r["img"], display_heatmap=r["_display_heatmap"], raw_heatmap=r["heatmap"],
+                      base_name=os.path.splitext(r["key_img"] or "image")[0],
+                      cell_mask=r.get("_cell_mask") if auto_cell_boundary else None,
+                      metrics_full=region_metrics(r["heatmap"], None, r["scale"]),
+                      metrics_cell=r["_metrics"] if auto_cell_boundary else None,
+                      info=r.get("info"), scale=r["scale"]) for r in batch_results]
+    pdf_bytes = create_batch_pdf_report(pdf_items, colormap_name, lo_b, hi_b, auto_cell_boundary)
+    dl_col1, dl_col2, dl_col3 = st.columns(3)
     with dl_col1:
-        st.download_button(
-            "Download all as CSV",
-            data=buf_csv.getvalue(),
-            file_name="s2f_batch_results.csv",
-            mime="text/csv",
-            key="download_batch_csv",
-            icon=":material/download:",
-        )
+        st.download_button("Download report (PDF)", data=pdf_bytes, file_name="s2f_batch_report.pdf",
+                           mime="application/pdf", key="download_batch_pdf", icon=":material/picture_as_pdf:",
+                           help="Summary table of all images, then one page per image with maps, metrics and parameters.")
     with dl_col2:
-        st.download_button(
-            "Download all heatmaps",
-            data=zip_buf.getvalue(),
-            file_name="s2f_batch_heatmaps.zip",
-            mime="application/zip",
-            key="download_batch_heatmaps",
-            icon=":material/image:",
-        )
+        st.download_button("Download values (CSV)", data=buf_csv.getvalue(), file_name="s2f_batch_results.csv",
+                           mime="text/csv", key="download_batch_csv", icon=":material/download:",
+                           help="One row per image: metrics with units and the parameters used.")
+    with dl_col3:
+        st.download_button("Download maps (ZIP)", data=zip_buf.getvalue(), file_name="s2f_batch_maps.zip",
+                           mime="application/zip", key="download_batch_heatmaps", icon=":material/image:",
+                           help="For each image: a PNG to view (colourbar and scale bar) and a TIFF whose pixel "
+                                "values are traction stress in Pa, for measurements in Fiji/ImageJ.")
+
+
+_ZIP_README = """Shape2Force (S2F) - predicted traction-stress maps
+
+For each image:
+  <name>_traction_stress.png     picture of the map with colourbar (Pa) and scale bar, for viewing and figures
+  <name>_traction_stress_Pa.tif  the same map as numbers: each pixel value is the predicted traction stress in Pa
+                                 (32-bit, 1024 x 1024). Open it in Fiji/ImageJ to measure regions yourself
+                                 (e.g. draw an ROI and use Analyze > Measure: Mean = mean traction stress in Pa).
+
+Scale: model output 1.0 = {smax:.0f} Pa. S2F predicts the magnitude of the traction stress, not its direction.
+The TIFF covers the whole image resized to 1024 x 1024 pixels; one TIFF pixel = (image width x pixel size / 1024) um.
+"""
+
+
+def _tiff_pa_bytes(heatmap, scale):
+    """Traction-stress map in Pa as a 32-bit float TIFF (readable by Fiji/ImageJ)."""
+    ok, enc = cv2.imencode(".tif", to_pa(heatmap, scale).astype(np.float32))
+    return enc.tobytes() if ok else b""
 
 
 def render_result_display(img, raw_heatmap, display_heatmap, pixel_sum, force, key_img, download_key_suffix="",
-                         colormap_name="Jet", display_mode="Default", measure_region_dialog=None, auto_cell_boundary=True,
-                         cell_mask=None, clip_min=0.0, clip_max=1.0, clamp_only=False):
+                          colormap_name="Jet", display_mode="Default", measure_region_dialog=None, auto_cell_boundary=True,
+                          cell_mask=None, clip_min=0.0, clip_max=1.0, clamp_only=False, scale=None, info=None):
     """
-    Render prediction result: plot, metrics, expander, and download/measure buttons.
-    measure_region_dialog: callable to open measure dialog (when ST_DIALOG available).
-    auto_cell_boundary: when True, use estimated cell area for metrics; when False, use entire map.
-    cell_mask: optional precomputed cell mask; if None and auto_cell_boundary, will be computed.
+    Render one prediction: bright field + traction-stress map (µm scale bars, colourbar in Pa), metrics with
+    units, statistics, and downloads (PNG with scale bar and colourbar, CSV and PDF report with all parameters).
+    scale: utils.units.make_scale(...); info: provenance dict (see app.py).
     """
+    scale = scale or make_scale("single_cell", image_shape=img.shape[:2])
+    smax = scale["stress_max_pa"]
     if cell_mask is None and auto_cell_boundary:
         cell_mask = estimate_cell_mask(raw_heatmap)
     elif not auto_cell_boundary:
         cell_mask = None
-    cell_pixel_sum, cell_force, cell_mean = _compute_cell_metrics(raw_heatmap, cell_mask, pixel_sum, force) if cell_mask is not None else (None, None, None)
-    use_cell_metrics = auto_cell_boundary and cell_pixel_sum is not None and cell_force is not None and cell_mean is not None
-
+    metrics_full = region_metrics(raw_heatmap, None, scale)
+    metrics_cell = region_metrics(raw_heatmap, cell_mask, scale) if (cell_mask is not None and np.any(cell_mask > 0)) else None
+    shown = metrics_cell if (auto_cell_boundary and metrics_cell) else metrics_full
     base_name = os.path.splitext(key_img or "image")[0]
-    if use_cell_metrics:
-        main_csv_rows = [
-            ["image", "Cell sum", "Cell force (scaled)", "Heatmap max", "Heatmap mean"],
-            [base_name, f"{cell_pixel_sum:.2f}", f"{cell_force:.2f}",
-             f"{np.max(raw_heatmap):.4f}", f"{cell_mean:.4f}"],
-        ]
-    else:
-        main_csv_rows = [
-            ["image", "Sum of all pixels", "Force (scaled)", "Heatmap max", "Heatmap mean"],
-            [base_name, f"{pixel_sum:.2f}", f"{force:.2f}",
-             f"{np.max(raw_heatmap):.4f}", f"{np.mean(raw_heatmap):.4f}"],
-        ]
-    buf_main_csv = io.StringIO()
-    csv.writer(buf_main_csv).writerows(main_csv_rows)
-
-    buf_hm = heatmap_to_png_bytes(display_heatmap, colormap_name, cell_mask=cell_mask)
-
     is_rescale = is_display_range_remapped(display_mode, clip_min, clip_max)
+    lo, hi = (clip_min, clip_max) if is_rescale else (0.0, 1.0)
 
     tit1, tit2 = st.columns(2)
     with tit1:
         st.markdown(_result_banner("INPUT", "input", "Bright-field image"), unsafe_allow_html=True)
     with tit2:
-        st.markdown(_result_banner("OUTPUT", "output", "Predicted force map"), unsafe_allow_html=True)
+        st.markdown(_result_banner("OUTPUT", "output", "Predicted traction-stress map"), unsafe_allow_html=True)
     fig_pl = make_subplots(rows=1, cols=2)
-    fig_pl.add_trace(go.Heatmap(z=img, colorscale="gray", showscale=False), row=1, col=1)
-    plotly_colorscale = cv_colormap_to_plotly_colorscale(colormap_name)
-    colorbar_cfg = dict(len=0.4, thickness=12, tickmode="array")
-    tick_positions = [0, 0.25, 0.5, 0.75, 1]
-    if is_rescale:
-        rng = clip_max - clip_min
-        colorbar_cfg["tickvals"] = tick_positions
-        colorbar_cfg["ticktext"] = [f"{clip_min + t * rng:.2f}" for t in tick_positions]
-    else:
-        colorbar_cfg["tickvals"] = tick_positions
-        colorbar_cfg["ticktext"] = [f"{t:.2f}" for t in tick_positions]
-    fig_pl.add_trace(go.Heatmap(z=display_heatmap, colorscale=plotly_colorscale, zmin=0.0, zmax=1.0, showscale=True,
-        colorbar=colorbar_cfg), row=1, col=2)
+    fig_pl.add_trace(go.Heatmap(z=img, colorscale="gray", showscale=False, hoverinfo="skip"), row=1, col=1)
+    ticks, labels = colorbar_ticks_pa(lo, hi, smax)
+    colorbar_cfg = dict(len=0.8, thickness=12, tickmode="array", tickvals=ticks, ticktext=labels,
+                        title=dict(text="Pa", side="top"))
+    fig_pl.add_trace(go.Heatmap(z=display_heatmap, colorscale=cv_colormap_to_plotly_colorscale(colormap_name),
+                                zmin=0.0, zmax=1.0, showscale=True, colorbar=colorbar_cfg,
+                                customdata=to_pa(raw_heatmap, scale),
+                                hovertemplate="x %{x}, y %{y}<br>%{customdata:.1f} Pa<extra></extra>"), row=1, col=2)
     add_cell_contour_to_fig(fig_pl, cell_mask, row=1, col=2)
-    fig_pl.update_layout(
-        height=_RESULT_FIG_HEIGHT,
-        margin=dict(l=10, r=10, t=10, b=10),
-        xaxis=dict(scaleanchor="y", scaleratio=1),
-        xaxis2=dict(scaleanchor="y2", scaleratio=1),
-    )
+    _add_scale_bar_to_fig(fig_pl, img.shape[1], img.shape[0], scale.get("image_um_per_px"), 1, 1)
+    _add_scale_bar_to_fig(fig_pl, display_heatmap.shape[1], display_heatmap.shape[0], scale.get("hm_um_per_px_x"), 1, 2)
+    fig_pl.update_layout(height=_RESULT_FIG_HEIGHT, margin=dict(l=10, r=10, t=10, b=10),
+                         xaxis=dict(scaleanchor="y", scaleratio=1), xaxis2=dict(scaleanchor="y2", scaleratio=1))
     fig_pl.update_xaxes(showticklabels=False, showgrid=False, zeroline=False)
     fig_pl.update_yaxes(showticklabels=False, autorange="reversed", showgrid=False, zeroline=False)
     st.plotly_chart(fig_pl, use_container_width=True, config={"displayModeBar": True, "responsive": True})
+    if is_rescale:
+        st.caption(f"Display range {lo * smax:.0f}–{hi * smax:.0f} Pa; stresses above {hi * smax:.0f} Pa are shown "
+                   "in the top colour. Metrics always use the full prediction.")
 
-    col1, col2, col3, col4 = st.columns(4)
-    if use_cell_metrics:
-        with col1:
-            st.metric("Cell sum", f"{cell_pixel_sum:.2f}", help="Sum over estimated cell area (background excluded)")
-        with col2:
-            st.metric("Cell force (scaled)", f"{cell_force:.2f}", help="Total traction force in physical units")
-        with col3:
-            st.metric("Heatmap max", f"{np.max(raw_heatmap):.4f}", help="Peak force intensity in the map")
-        with col4:
-            st.metric("Heatmap mean", f"{cell_mean:.4f}", help="Mean force over estimated cell area")
-    else:
-        with col1:
-            st.metric("Sum of all pixels", f"{pixel_sum:.2f}", help="Raw sum of all pixel values in the force map")
-        with col2:
-            st.metric("Force (scaled)", f"{force:.2f}", help="Total traction force in physical units (full field of view)")
-        with col3:
-            st.metric("Heatmap max", f"{np.max(raw_heatmap):.4f}", help="Peak force intensity in the map")
-        with col4:
-            st.metric("Heatmap mean", f"{np.mean(raw_heatmap):.4f}", help="Average force intensity (full FOV)")
+    cols = st.columns(4)
+    for col, (label, value) in zip(cols, metric_rows(shown)):
+        with col:
+            st.metric(label, value, help=_METRIC_HELP[label])
+    st.caption(("Metrics inside the force region (red contour), estimated from the predicted map." if shown is metrics_cell else
+                "Metrics over the whole field of view.")
+               + ("" if scale.get("hm_px_area_um2") else " Enter the image pixel size in the sidebar to get area and total force."))
 
-    # Statistics panel (mean, std, percentiles, histogram)
     with st.expander("Statistics"):
-        vals = raw_heatmap[cell_mask > 0] if (cell_mask is not None and np.any(cell_mask > 0) and use_cell_metrics) else raw_heatmap.flatten()
+        vals = to_pa(raw_heatmap, scale)
+        vals = vals[cell_mask > 0] if (shown is metrics_cell and cell_mask is not None) else vals.ravel()
         if len(vals) > 0:
-            stat_col1, stat_col2, stat_col3 = st.columns(3)
-            p25, p50, p75, p90 = (
-                float(np.percentile(vals, 25)), float(np.percentile(vals, 50)),
-                float(np.percentile(vals, 75)), float(np.percentile(vals, 90)),
-            )
-            with stat_col1:
-                st.metric("Mean", f"{float(np.mean(vals)):.4f}")
-                st.metric("Std", f"{float(np.std(vals)):.4f}")
-            with stat_col2:
-                st.metric("P25", f"{p25:.4f}")
-                st.metric("P50 (median)", f"{p50:.4f}")
-            with stat_col3:
-                st.metric("P75", f"{p75:.4f}")
-                st.metric("P90", f"{p90:.4f}")
-            st.markdown("**Histogram**")
+            c1, c2, c3 = st.columns(3)
+            p25, p50, p75, p90 = (float(np.percentile(vals, q)) for q in (25, 50, 75, 90))
+            with c1:
+                st.metric("Mean", f"{float(np.mean(vals)):.1f} Pa")
+                st.metric("Std", f"{float(np.std(vals)):.1f} Pa")
+            with c2:
+                st.metric("P25", f"{p25:.1f} Pa")
+                st.metric("P50 (median)", f"{p50:.1f} Pa")
+            with c3:
+                st.metric("P75", f"{p75:.1f} Pa")
+                st.metric("P90", f"{p90:.1f} Pa")
             hist_fig = go.Figure(data=[go.Histogram(x=vals, nbinsx=50, marker_color=_HISTOGRAM_ACCENT)])
-            hist_fig.update_layout(
-                height=_HISTOGRAM_HEIGHT, margin=dict(l=40, r=20, t=20, b=40),
-                xaxis_title="Force value", yaxis_title="Count",
-                showlegend=False,
-            )
+            hist_fig.update_layout(height=_HISTOGRAM_HEIGHT, margin=dict(l=40, r=20, t=20, b=40),
+                                   xaxis_title="Traction stress (Pa)", yaxis_title="Pixels", showlegend=False)
             st.plotly_chart(hist_fig, use_container_width=True, config={"displayModeBar": False})
         else:
-            st.caption("No nonzero values to compute statistics.")
-
-    with st.expander("How to read the results"):
-        if use_cell_metrics:
-            st.markdown("""
-**Input (left):** Bright-field microscopy image of a cell or spheroid on a substrate.  
-This is the raw image you provided—it shows cell shape but not forces.
+            st.caption("No values to compute statistics.")
 
-**Output (right):** Predicted traction force map.  
-- **Color** indicates force magnitude: blue = low, red = high  
-- **Brighter/warmer colors** = stronger forces exerted by the cell on the substrate  
-- **Red border = estimated cell area** (background excluded from metrics)
-- Values are normalized to [0, 1] for visualization
+    with st.expander("Parameters of this prediction"):
+        st.table({"Parameter": [k for k, _ in info_rows(info)], "Value": [str(v) for _, v in info_rows(info)]})
 
-**Metrics (auto cell boundary on):**
-- **Cell sum:** Sum over estimated cell area (background excluded)
-- **Cell force (scaled):** Total traction force in physical units
-- **Heatmap max:** Peak force intensity in the map
-- **Heatmap mean:** Mean force over the estimated cell area
-            """)
-        else:
-            st.markdown("""
-**Input (left):** Bright-field microscopy image of a cell or spheroid on a substrate.  
-This is the raw image you provided—it shows cell shape but not forces.
-
-**Output (right):** Predicted traction force map.  
-- **Color** indicates force magnitude: blue = low, red = high  
-- **Brighter/warmer colors** = stronger forces exerted by the cell on the substrate  
-- Values are normalized to [0, 1] for visualization
+    with st.expander("How to read the results"):
+        st.markdown(f"""
+**Input (left):** the bright-field image you provided (cell shape only, no force information).
 
-**Metrics (auto cell boundary off):**
-- **Sum of all pixels:** Raw sum over entire map
-- **Force (scaled):** Total traction force in physical units (full field of view)
-- **Heatmap max/mean:** Peak and average force intensity (full field of view)
-            """)
+**Output (right):** predicted **traction-stress magnitude** (Pa).
+- The model output is normalised to 0–1, with 1 = **{smax:.0f} Pa**, the fixed colour limit of the
+  {'single-cell' if smax >= 500 else 'spheroid'} ground-truth TFM maps used for training. The colourbar shows Pa.
+- S2F predicts the magnitude only, not the direction, and predictions tend to underestimate the highest stresses.
+- **Range** (sidebar) narrows the displayed window, e.g. 0–250 Pa, to show low-stress patterns; stresses above the
+  window saturate. The metrics are always computed from the full prediction.
+- **Red contour** ("Measure force region only", on by default): the region of high predicted stress, estimated from
+  the map (not the cell outline); the metrics refer to this region so the background does not dilute them.
 
-    original_vals = build_original_vals(raw_heatmap, pixel_sum, force)
+**Metrics:** mean and maximum traction stress (Pa); area (µm²) and total force (nN = Σ stress × pixel area)
+need the image pixel size. Total force sums magnitudes, so it is not the net force.
+        """)
 
-    pdf_bytes = create_pdf_report(
-        img, display_heatmap, raw_heatmap, pixel_sum, force, base_name, colormap_name,
-        cell_mask=cell_mask, cell_pixel_sum=cell_pixel_sum, cell_force=cell_force, cell_mean=cell_mean
-    )
+    original_vals = build_original_vals(raw_heatmap, pixel_sum, force, scale)
+    buf_hm = heatmap_figure_png_bytes(display_heatmap, colormap_name, cell_mask, scale, lo, hi)
+    csv_text = _metrics_csv(base_name, metrics_full, metrics_cell, info)
+    pdf_bytes = create_pdf_report(img, display_heatmap, raw_heatmap, base_name, colormap_name, cell_mask=cell_mask,
+                                  metrics_full=metrics_full, metrics_cell=metrics_cell, info=info, scale=scale,
+                                  clip_min=lo, clip_max=hi)
 
     btn_col1, btn_col2, btn_col3, btn_col4 = st.columns(4)
     with btn_col1:
@@ -322,48 +312,20 @@ This is the raw image you provided—it shows cell shape but not forces.
                 st.rerun()
         elif HAS_DRAWABLE_CANVAS:
             with st.expander("Measure tool"):
-                expander_cell_vals = build_cell_vals(raw_heatmap, cell_mask, pixel_sum, force) if (auto_cell_boundary and cell_mask is not None) else None
-                expander_cell_mask = cell_mask if auto_cell_boundary else None
-                render_region_canvas(
-                    display_heatmap,
-                    raw_heatmap=raw_heatmap,
-                    bf_img=img,
-                    original_vals=original_vals,
-                    cell_vals=expander_cell_vals,
-                    cell_mask=expander_cell_mask,
-                    key_suffix="expander",
-                    input_filename=key_img,
-                    colormap_name=colormap_name,
-                )
+                expander_cell_vals = build_cell_vals(raw_heatmap, cell_mask, pixel_sum, force, scale) if (auto_cell_boundary and cell_mask is not None) else None
+                render_region_canvas(display_heatmap, raw_heatmap=raw_heatmap, bf_img=img, original_vals=original_vals,
+                                     cell_vals=expander_cell_vals, cell_mask=cell_mask if auto_cell_boundary else None,
+                                     key_suffix="expander", input_filename=key_img, colormap_name=colormap_name)
         else:
             st.caption("Install `streamlit-drawable-canvas-fix` for region measurement: `pip install streamlit-drawable-canvas-fix`")
     with btn_col2:
-        st.download_button(
-            "Download heatmap",
-            width="stretch",
-            data=buf_hm.getvalue(),
-            file_name="s2f_heatmap.png",
-            mime="image/png",
-            key=f"download_heatmap{download_key_suffix}",
-            icon=":material/download:",
-        )
+        st.download_button("Download map", width="stretch", data=buf_hm.getvalue(),
+                           file_name=f"{base_name}_traction_stress.png", mime="image/png",
+                           key=f"download_heatmap{download_key_suffix}", icon=":material/download:")
     with btn_col3:
-        st.download_button(
-            "Download values",
-            width="stretch",
-            data=buf_main_csv.getvalue(),
-            file_name=f"{base_name}_main_values.csv",
-            mime="text/csv",
-            key=f"download_main_values{download_key_suffix}",
-            icon=":material/download:",
-        )
+        st.download_button("Download values", width="stretch", data=csv_text, file_name=f"{base_name}_values.csv",
+                           mime="text/csv", key=f"download_main_values{download_key_suffix}", icon=":material/download:")
     with btn_col4:
-        st.download_button(
-            "Download report",
-            width="stretch",
-            data=pdf_bytes,
-            file_name=f"{base_name}_report.pdf",
-            mime="application/pdf",
-            key=f"download_pdf{download_key_suffix}",
-            icon=":material/picture_as_pdf:",
-        )
+        st.download_button("Download report", width="stretch", data=pdf_bytes, file_name=f"{base_name}_report.pdf",
+                           mime="application/pdf", key=f"download_pdf{download_key_suffix}",
+                           icon=":material/picture_as_pdf:")

S2FApp/utils/display.py

@@ -32,30 +32,18 @@ def is_display_range_remapped(display_mode, clip_min, clip_max):
 
 def apply_display_scale(heatmap, mode, clip_min=0, clip_max=1, clamp_only=False):
     """
-    Apply display scaling. Display only—does not change underlying values.
+    Map the normalised prediction (0-1) to colormap positions. Display only; values are unchanged.
 
-    Supports modes used by the app: ``Default`` (clip to [0, 1]) and ``Range``
-    (window to [clip_min, clip_max]). Unknown ``mode`` is treated like ``Default``.
-
-    Parameters
-    ----------
-    clamp_only : bool
-        For ``mode == "Range"`` when ``clip_max > clip_min``:
-
-        - **False** (default in the app for Range): pixels outside ``[clip_min, clip_max]`` are set
-          to 0; values inside are linearly mapped to ``[0, 1]`` for the colormap.
-        - **True**: values are clamped to ``[clip_min, clip_max]`` without rescaling to ``[0, 1]``.
+    ``Default``: the full scale, 0-1 (= 0-500 Pa single cells, 0-50 Pa spheroids).
+    ``Range``: the window [clip_min, clip_max] is stretched over the whole colormap; values below the window
+    are shown as the lowest colour and values above it **saturate at the highest colour**. (Earlier versions set
+    values above the window to 0, which displayed the strongest stresses as zero.)
+    ``clamp_only`` is kept for backward compatibility and ignored.
     """
+    h = np.asarray(heatmap, dtype=np.float32)
     if mode != "Range":
-        return np.clip(heatmap, 0, 1).astype(np.float32)
-    # Range
+        return np.clip(h, 0, 1).astype(np.float32)
     vmin, vmax = float(clip_min), float(clip_max)
     if vmax > vmin:
-        h = heatmap.astype(np.float32)
-        if clamp_only:
-            return np.clip(h, vmin, vmax).astype(np.float32)
-        mask = (h >= vmin) & (h <= vmax)
-        out = np.zeros_like(h)
-        out[mask] = (h[mask] - vmin) / (vmax - vmin)
-        return np.clip(out, 0, 1).astype(np.float32)
-    return np.clip(heatmap, 0, 1).astype(np.float32)
+        return np.clip((h - vmin) / (vmax - vmin), 0, 1).astype(np.float32)
+    return np.clip(h, 0, 1).astype(np.float32)

S2FApp/utils/report.py

@@ -1,5 +1,6 @@
 """Report and heatmap export utilities."""
 import io
+import textwrap
 from datetime import datetime
 
 import cv2
@@ -10,7 +11,7 @@ from reportlab.lib.units import inch
 from reportlab.lib.utils import ImageReader
 from reportlab.pdfgen import canvas
 
-from config.constants import COLORMAPS
+from config.constants import ARCH_LABELS, AUTO_BOUNDARY_DESCRIPTION, COLORMAPS
 
 
 def _draw_pdf_footer(c, margin=72, footer_y=40, include_web_app=False):
@@ -82,73 +83,243 @@ def heatmap_to_png_bytes(scaled_heatmap, colormap_name="Jet", cell_mask=None, zm
     return buf
 
 
-def create_pdf_report(img, display_heatmap, raw_heatmap, pixel_sum, force, base_name, colormap_name="Jet",
-                      cell_mask=None, cell_pixel_sum=None, cell_force=None, cell_mean=None, zmin=None, zmax=None):
-    """Create a PDF report with input image, heatmap, and metrics."""
+def info_rows(info):
+    """Provenance of a prediction as (label, value) rows: everything needed to reproduce it."""
+    if not info:
+        return []
+    m = info.get("model", {})
+    rows = [
+        ("Input file", info.get("input_file", "–")),
+        ("Prediction time (UTC)", info.get("time", "–")),
+        ("Model type", {"single_cell": "Single cell", "spheroid": "Spheroid"}.get(m.get("model_type"), "–")),
+        ("Architecture", ARCH_LABELS.get(m.get("architecture"), m.get("architecture", "–"))),
+        ("Checkpoint", m.get("checkpoint", "–")),
+        ("Checkpoint SHA-256", m.get("checkpoint_sha256", "–")),
+    ]
+    sub = info.get("substrate")
+    if sub:
+        if sub.get("mode") == "preset":
+            rows.append(("Substrate setting (preset)", sub.get("name", "–")))
+        else:
+            rows.append(("Substrate setting (manual)", "–"))
+        rows.append(("  pixel-size setting / Young's modulus", f"{sub.get('pixelsize'):.4f} / {sub.get('young'):.0f} Pa"))
+        rows.append(("  model input channels (normalised)",
+                     f"{sub.get('pixelsize_norm'):.3f} / {sub.get('young_norm'):.3f}"))
+    shp = info.get("image_shape")
+    rows += [
+        ("Image size (px)", f"{shp[1]} x {shp[0]}" if shp else "–"),
+        ("Image pixel size", f"{info['image_um_per_px']:.4f} µm/px (user input)" if info.get("image_um_per_px") else "not set"),
+        ("Stress scale", f"normalised output 1.0 = {info.get('stress_max_pa', 0):.0f} Pa"),
+    ]
+    d = info.get("display", {})
+    if d:
+        rows.append(("Display", f"{d.get('colormap', '–')}, {d.get('range_pa', ('–', '–'))[0]:.0f}-{d.get('range_pa', ('–', '–'))[1]:.0f} Pa"
+                     + (" (values above the range shown in the top colour)" if d.get("mode") == "Range" else "")))
+    rows.append(("Measure force region only", f"on ({AUTO_BOUNDARY_DESCRIPTION})" if info.get("auto_boundary") else "off (whole field of view)"))
+    rows.append(("App version", f"{info.get('app_version', '–')}" + (f" (commit {info['app_commit']})" if info.get("app_commit") else "")))
+    return rows
+
+
+def colorbar_strip_rgb(width, colormap_name, clip_min=0.0, clip_max=1.0, stress_max_pa=500.0, height=70):
+    """Horizontal colourbar with tick labels in Pa, as an RGB image (white background)."""
+    from ui.heatmaps import colorbar_ticks_pa
+    strip = np.full((height, width, 3), 255, np.uint8)
+    pad = max(10, width // 30)
+    bar_w = width - 2 * pad
+    grad = np.linspace(0, 255, bar_w).astype(np.uint8).reshape(1, -1)
+    rgb = cv2.cvtColor(cv2.applyColorMap(grad, COLORMAPS.get(colormap_name, cv2.COLORMAP_JET)), cv2.COLOR_BGR2RGB)
+    bar_h = height // 4
+    strip[6:6 + bar_h, pad:pad + bar_w] = np.repeat(rgb, bar_h, axis=0)
+    pos, labels = colorbar_ticks_pa(clip_min, clip_max, stress_max_pa)
+    fs = max(0.4, width / 950)
+    lw = max(1, int(round(fs * 1.6)))
+    for t, lab in zip(pos, labels):
+        x = pad + int(t * (bar_w - 1))
+        cv2.line(strip, (x, 6 + bar_h), (x, 12 + bar_h), (0, 0, 0), lw)
+        (tw, th), _ = cv2.getTextSize(lab, cv2.FONT_HERSHEY_SIMPLEX, fs, lw)
+        cv2.putText(strip, lab, (min(max(x - tw // 2, 0), width - tw), 18 + bar_h + th), cv2.FONT_HERSHEY_SIMPLEX, fs,
+                    (0, 0, 0), lw, cv2.LINE_AA)
+    title = "Traction stress (Pa)"
+    (tw, th), _ = cv2.getTextSize(title, cv2.FONT_HERSHEY_SIMPLEX, fs, lw)
+    cv2.putText(strip, title, ((width - tw) // 2, height - 8), cv2.FONT_HERSHEY_SIMPLEX, fs, (0, 0, 0), lw, cv2.LINE_AA)
+    return strip
+
+
+def heatmap_figure_rgb(display_heatmap, colormap_name="Jet", cell_mask=None, scale=None, clip_min=0.0, clip_max=1.0):
+    """Heatmap with optional red boundary, µm scale bar and a Pa colourbar underneath (for PNG/PDF export)."""
+    from utils.units import draw_scale_bar
+    hm = heatmap_to_rgb_with_contour(display_heatmap, colormap_name, cell_mask)
+    if scale is not None and scale.get("hm_um_per_px_x"):
+        draw_scale_bar(hm, scale["hm_um_per_px_x"])
+    smax = scale["stress_max_pa"] if scale else 1.0
+    bar = colorbar_strip_rgb(hm.shape[1], colormap_name, clip_min, clip_max, smax, height=max(80, hm.shape[0] // 6))
+    return np.vstack([hm, bar])
+
+
+def heatmap_figure_png_bytes(display_heatmap, colormap_name="Jet", cell_mask=None, scale=None, clip_min=0.0, clip_max=1.0):
     buf = io.BytesIO()
-    c = canvas.Canvas(buf, pagesize=A4)
-    c.setTitle("Shape2Force")
-    c.setAuthor("Angione-Lab")
+    Image.fromarray(heatmap_figure_rgb(display_heatmap, colormap_name, cell_mask, scale, clip_min, clip_max)).save(buf, format="PNG")
+    buf.seek(0)
+    return buf
+
+
+def _draw_prediction_page(c, img, display_heatmap, raw_heatmap, base_name, colormap_name="Jet", cell_mask=None,
+                          metrics_full=None, metrics_cell=None, info=None, scale=None, clip_min=0.0, clip_max=1.0,
+                          page_label=None):
+    """Draw one prediction (images, metrics, parameters) on the current page of canvas `c`."""
+    from utils.units import draw_scale_bar, metric_rows
     page_w_pt, page_h_pt = A4[0], A4[1]
-    margin = 72
+    margin = 60
     layout = _pdf_image_layout(page_w_pt, page_h_pt, margin)
-    img_w = layout["img_w"]
-    img_h = layout["img_h"]
-    bf_x = layout["bf_x"]
-    hm_x = layout["hm_x"]
+    img_w, img_h = layout["img_w"], layout["img_h"]
+    bf_x, hm_x, y_top = layout["bf_x"], layout["hm_x"], layout["y_top"]
     img_bottom = layout["img_bottom"]
-    y_top = layout["y_top"]
 
     _draw_pdf_footer(c, margin=margin, include_web_app=True)
-    c.setFont("Helvetica-Bold", 16)
+    c.setFont("Helvetica-Bold", 15)
     c.drawString(margin, y_top, "Shape2Force (S2F) - Prediction Report")
     c.setFont("Helvetica", 10)
-    c.drawString(margin, y_top - 14, f"Image: {base_name}")
-    y_top -= 35
+    c.drawString(margin, y_top - 14, f"Image: {base_name}" + (f"   ({page_label})" if page_label else ""))
 
-    img_pil = Image.fromarray(img) if img.ndim == 2 else Image.fromarray(cv2.cvtColor(img, cv2.COLOR_BGR2RGB))
-    img_buf = io.BytesIO()
-    img_pil.save(img_buf, format="PNG")
-    img_buf.seek(0)
-    c.drawImage(ImageReader(img_buf), bf_x, img_bottom, width=img_w, height=img_h, preserveAspectRatio=True)
+    bf = img if img.ndim == 3 else cv2.cvtColor(img, cv2.COLOR_GRAY2RGB)
+    bf_um_per_px = scale.get("image_um_per_px") if scale else None
+    if max(bf.shape[:2]) > 1024:   # keep the PDF small; the scale bar follows the resampling
+        f = 1024 / max(bf.shape[:2])
+        bf = cv2.resize(bf, (int(bf.shape[1] * f), int(bf.shape[0] * f)), interpolation=cv2.INTER_AREA)
+        bf_um_per_px = bf_um_per_px / f if bf_um_per_px else None
+    bf = np.ascontiguousarray(bf.copy())
+    if bf_um_per_px:
+        draw_scale_bar(bf, bf_um_per_px)
+    bf_buf = io.BytesIO(); Image.fromarray(bf).save(bf_buf, format="PNG"); bf_buf.seek(0)
+    c.drawImage(ImageReader(bf_buf), bf_x, img_bottom, width=img_w, height=img_h, preserveAspectRatio=True)
     c.setFont("Helvetica", 9)
-    bf_label_w = c.stringWidth("Bright-field", "Helvetica", 9)
-    c.drawString(bf_x + (img_w - bf_label_w) / 2, img_bottom - 14, "Bright-field")
+    c.drawCentredString(bf_x + img_w / 2, img_bottom - 12, "Bright field")
 
-    heatmap_rgb = heatmap_to_rgb_with_contour(display_heatmap, colormap_name, cell_mask, zmin=zmin, zmax=zmax)
-    hm_buf = io.BytesIO()
-    Image.fromarray(heatmap_rgb).save(hm_buf, format="PNG")
-    hm_buf.seek(0)
-    c.drawImage(ImageReader(hm_buf), hm_x, img_bottom, width=img_w, height=img_h, preserveAspectRatio=True)
-    hm_label = "Force map (red = estimated boundary)" if cell_mask is not None and np.any(cell_mask > 0) else "Force map"
-    hm_label_w = c.stringWidth(hm_label, "Helvetica", 9)
-    c.drawString(hm_x + (img_w - hm_label_w) / 2, img_bottom - 14, hm_label)
+    fig = heatmap_figure_rgb(display_heatmap, colormap_name, cell_mask, scale, clip_min, clip_max)
+    fig_h = img_h * fig.shape[0] / fig.shape[1]
+    hm_buf = io.BytesIO(); Image.fromarray(fig).save(hm_buf, format="PNG", optimize=True); hm_buf.seek(0)
+    c.drawImage(ImageReader(hm_buf), hm_x, img_bottom + img_h - fig_h, width=img_w, height=fig_h, preserveAspectRatio=True)
+    hm_label = "Predicted traction stress (red = force region)" if cell_mask is not None and np.any(cell_mask > 0) \
+        else "Predicted traction stress"
+    c.drawCentredString(hm_x + img_w / 2, img_bottom + img_h - fig_h - 12, hm_label)
 
-    # Metrics section with spacing
-    row_height = 14
-    y = img_bottom - 14 - row_height
+    y = img_bottom + img_h - fig_h - 40
     c.setFont("Helvetica-Bold", 10)
     c.drawString(margin, y, "Metrics")
+    y -= 15
     c.setFont("Helvetica", 9)
-    y -= 18
-    if cell_pixel_sum is not None and cell_force is not None and cell_mean is not None:
-        metrics = [
-            ("Cell sum (estimated boundary)", f"{cell_pixel_sum:.2f}"),
-            ("Cell force (scaled)", f"{cell_force:.2f}"),
-            ("Heatmap max", f"{np.max(raw_heatmap):.4f}"),
-            ("Heatmap mean (estimated boundary)", f"{cell_mean:.4f}"),
-        ]
-    else:
-        metrics = [
-            ("Sum of all pixels", f"{pixel_sum:.2f}"),
-            ("Cell force (scaled)", f"{force:.2f}"),
-            ("Heatmap max", f"{np.max(raw_heatmap):.4f}"),
-            ("Heatmap mean", f"{np.mean(raw_heatmap):.4f}"),
-        ]
-    for label, val in metrics:
-        c.drawString(margin, y, f"{label}: {val}")
-        y -= 16
+    cols = [("Whole field of view", metrics_full)] + ([("Force region (red)", metrics_cell)] if metrics_cell else [])
+    x_cols = [margin + 170 + i * 150 for i in range(len(cols))]
+    for xc, (title, _) in zip(x_cols, cols):
+        c.setFont("Helvetica-Bold", 9); c.drawString(xc, y, title)
+    c.setFont("Helvetica", 9)
+    y -= 13
+    labels = [r[0] for r in metric_rows(metrics_full or {})]
+    for li, lab in enumerate(labels):
+        c.drawString(margin, y, lab)
+        for xc, (_, m) in zip(x_cols, cols):
+            c.drawString(xc, y, metric_rows(m or {})[li][1])
+        y -= 13
+    if scale is None or not scale.get("hm_px_area_um2"):
+        c.setFont("Helvetica-Oblique", 8)
+        c.drawString(margin, y, "Area and total force need the image pixel size (sidebar).")
+        y -= 12
+    c.setFont("Helvetica-Oblique", 8)
+    c.drawString(margin, y, "Total force = sum of traction stress x pixel area. S2F predicts magnitude only (no direction).")
+    y -= 20
+
+    c.setFont("Helvetica-Bold", 10)
+    c.drawString(margin, y, "Parameters (for reproducibility)")
+    y -= 14
+    c.setFont("Helvetica", 8)
+    for lab, val in info_rows(info):
+        c.drawString(margin, y, f"{lab}:")
+        for line in textwrap.wrap(str(val), 82) or ["–"]:
+            c.drawString(margin + 175, y, line)
+            y -= 11
+        if y < 70:
+            c.showPage(); _draw_pdf_footer(c, margin=margin, include_web_app=True); y = page_h_pt - 60; c.setFont("Helvetica", 8)
+
+
+def create_pdf_report(img, display_heatmap, raw_heatmap, base_name, colormap_name="Jet", cell_mask=None,
+                      metrics_full=None, metrics_cell=None, info=None, scale=None, clip_min=0.0, clip_max=1.0):
+    """
+    PDF report: bright field and predicted traction-stress map (with µm scale bar and Pa colourbar),
+    metrics with units, and every parameter needed to reproduce the prediction (Reviewer 1).
+    """
+    buf = io.BytesIO()
+    c = canvas.Canvas(buf, pagesize=A4)
+    c.setTitle("Shape2Force prediction report")
+    c.setAuthor("Angione-Lab")
+    _draw_prediction_page(c, img, display_heatmap, raw_heatmap, base_name, colormap_name, cell_mask,
+                          metrics_full, metrics_cell, info, scale, clip_min, clip_max)
+    c.save()
+    buf.seek(0)
+    return buf.getvalue()
+
+
+_SHARED_KEYS = ("Model type", "Architecture", "Checkpoint", "Checkpoint SHA-256", "Substrate setting (preset)",
+                "Substrate setting (manual)", "  pixel-size setting / Young's modulus",
+                "  model input channels (normalised)", "Image pixel size", "Stress scale", "Display", "Measure force region only",
+                "App version")
 
+
+def create_batch_pdf_report(items, colormap_name="Jet", clip_min=0.0, clip_max=1.0, auto_cell_boundary=False):
+    """
+    Batch PDF: page 1 = summary table of all images (metrics with units) and the shared parameters;
+    then one page per image with the same layout as the single-image report.
+    items: list of dicts with img, display_heatmap, raw_heatmap, base_name, cell_mask, metrics_full,
+           metrics_cell, info, scale.
+    """
+    from utils.units import fmt
+    buf = io.BytesIO()
+    c = canvas.Canvas(buf, pagesize=A4)
+    c.setTitle("Shape2Force batch report")
+    c.setAuthor("Angione-Lab")
+    page_w_pt, page_h_pt = A4
+    margin = 60
+    _draw_pdf_footer(c, margin=margin, include_web_app=True)
+    y = page_h_pt - 50
+    c.setFont("Helvetica-Bold", 15)
+    c.drawString(margin, y, "Shape2Force (S2F) - Batch Report")
+    y -= 16
+    c.setFont("Helvetica", 10)
+    region = "force region (red contour)" if auto_cell_boundary else "whole field of view"
+    c.drawString(margin, y, f"{len(items)} images; metrics over the {region}. One page per image follows.")
+    y -= 26
+    headers = ["#", "Image", "Mean stress (Pa)", "Max stress (Pa)", "Area (µm²)", "Total force (nN)"]
+    xs = [margin, margin + 22, margin + 210, margin + 290, margin + 370, margin + 440]
+    c.setFont("Helvetica-Bold", 9)
+    for x, h in zip(xs, headers):
+        c.drawString(x, y, h)
+    y -= 4
+    c.line(margin, y, page_w_pt - margin, y)
+    y -= 12
+    c.setFont("Helvetica", 9)
+    for i, it in enumerate(items, 1):
+        m = (it["metrics_cell"] if (auto_cell_boundary and it.get("metrics_cell")) else it["metrics_full"]) or {}
+        vals = [str(i), it["base_name"][:34], fmt(m.get("mean_pa"), nd=1), fmt(m.get("max_pa"), nd=1),
+                fmt(m.get("area_um2"), nd=0), fmt(m.get("total_force_nN"), nd=2)]
+        for x, v in zip(xs, vals):
+            c.drawString(x, y, v)
+        y -= 13
+    y -= 18
+    c.setFont("Helvetica-Bold", 10)
+    c.drawString(margin, y, "Parameters (shared by all images)")
+    y -= 14
+    c.setFont("Helvetica", 8)
+    for lab, val in info_rows(items[0]["info"] if items else None):
+        if lab in _SHARED_KEYS:
+            c.drawString(margin, y, f"{lab}:")
+            for line in textwrap.wrap(str(val), 82) or ["–"]:
+                c.drawString(margin + 175, y, line)
+                y -= 11
+    c.showPage()
+    for i, it in enumerate(items, 1):
+        _draw_prediction_page(c, it["img"], it["display_heatmap"], it["raw_heatmap"], it["base_name"], colormap_name,
+                              it.get("cell_mask"), it["metrics_full"], it.get("metrics_cell"), it["info"], it["scale"],
+                              clip_min, clip_max, page_label=f"image {i} of {len(items)}")
+        c.showPage()
     c.save()
     buf.seek(0)
     return buf.getvalue()

S2FApp/utils/substrate_settings.py

@@ -114,21 +114,8 @@ def compute_settings_normalization(config=None, config_path=None):
     Returns:
         dict: {'pixelsize': {'min', 'max'}, 'young': {'min', 'max'}}
     """
-    if config is None:
-        config = load_substrate_config(config_path)
-
-    substrates = config.get('substrates', {})
-    all_pixelsizes = [s['pixelsize'] for s in substrates.values()]
-    all_youngs = [s['young'] for s in substrates.values()]
-
-    if not all_pixelsizes or not all_youngs:
-        pixelsize_min, pixelsize_max = 3.0769, 9.8138
-        young_min, young_max = 1000.0, 10000.0
-    else:
-        pixelsize_min, pixelsize_max = min(all_pixelsizes), max(all_pixelsizes)
-        young_min, young_max = min(all_youngs), max(all_youngs)
-
-    return {
-        'pixelsize': {'min': pixelsize_min, 'max': pixelsize_max},
-        'young': {'min': young_min, 'max': young_max}
-    }
+    # The ranges must be those used in training (pixel size 3.0769-9.8138, Young's modulus 1-10 kPa),
+    # not the min/max of the presets listed by the app: previously the app normalised the pixel size over
+    # its own presets (3.0769-6.1538), which gave a different input for any pixel size other than 3.0769.
+    from config.constants import SETTINGS_NORMALIZATION
+    return {k: dict(v) for k, v in SETTINGS_NORMALIZATION.items()}

S2FApp/utils/units.py

@@ -0,0 +1,125 @@
+"""
+Physical units for S2F predictions.
+
+The network output is a normalised map y_hat in [0, 1]. The ground-truth traction-stress maps used for
+training were exported by the TFM software on a fixed colour scale, so
+
+    traction stress T [Pa] = y_hat * STRESS_MAX_PA[model_type]   (500 Pa single cells, 50 Pa spheroids).
+
+Areas and forces additionally need the pixel size of the bright-field image (µm per pixel, entered by the
+user). The prediction is made on a MODEL_INPUT_SIZE x MODEL_INPUT_SIZE grid, so one heatmap pixel covers
+(image width * pixel size / MODEL_INPUT_SIZE) µm in x, and likewise in y.
+
+    area  [µm²] = number of pixels * heatmap pixel area
+    force [nN]  = sum(T [Pa] * heatmap pixel area [µm²]) * 1e-3      (1 Pa · µm² = 1e-12 N = 1e-3 nN)
+"""
+import numpy as np
+
+from config.constants import MODEL_INPUT_SIZE, STRESS_MAX_PA
+
+
+def stress_max_pa(model_type):
+    return STRESS_MAX_PA["spheroid" if model_type == "spheroid" else "single_cell"]
+
+
+def make_scale(model_type, image_um_per_px=None, image_shape=None, heatmap_shape=(MODEL_INPUT_SIZE, MODEL_INPUT_SIZE)):
+    """
+    Physical scale of one prediction.
+
+    image_um_per_px: pixel size of the uploaded bright-field image (µm/px); None or <= 0 if unknown.
+    image_shape: (height, width) of the uploaded image, before resizing to the model input.
+    Returns a dict used by the display, report and measurement code.
+    """
+    smax = stress_max_pa(model_type)
+    s = {"stress_max_pa": smax, "image_um_per_px": None, "image_shape": None,
+         "hm_um_per_px_x": None, "hm_um_per_px_y": None, "hm_px_area_um2": None}
+    if image_shape is not None:
+        s["image_shape"] = (int(image_shape[0]), int(image_shape[1]))
+    if image_um_per_px and image_um_per_px > 0 and image_shape is not None:
+        h, w = image_shape[:2]
+        hh, hw = heatmap_shape[:2]
+        sx = image_um_per_px * w / hw
+        sy = image_um_per_px * h / hh
+        s.update(image_um_per_px=float(image_um_per_px), hm_um_per_px_x=sx, hm_um_per_px_y=sy, hm_px_area_um2=sx * sy)
+    return s
+
+
+def has_physical_size(scale):
+    return scale is not None and scale.get("hm_px_area_um2") is not None
+
+
+def to_pa(heatmap, scale):
+    """Normalised map -> traction stress in Pa."""
+    return np.clip(np.asarray(heatmap, dtype=np.float64), 0, 1) * scale["stress_max_pa"]
+
+
+def region_metrics(heatmap, mask, scale):
+    """
+    Metrics over a region (mask = 1) or the whole map (mask = None).
+    Keys: n_px, area_um2, mean_pa, max_pa, total_force_nN (area and force are None without a pixel size).
+    """
+    t = to_pa(heatmap, scale)
+    m = np.ones(t.shape, dtype=bool) if mask is None else (np.asarray(mask) > 0)
+    n = int(m.sum())
+    if n == 0:
+        return {"n_px": 0, "area_um2": None, "mean_pa": None, "max_pa": None, "total_force_nN": None}
+    vals = t[m]
+    out = {"n_px": n, "mean_pa": float(vals.mean()), "max_pa": float(vals.max()), "area_um2": None, "total_force_nN": None}
+    if has_physical_size(scale):
+        a = scale["hm_px_area_um2"]
+        out["area_um2"] = n * a
+        out["total_force_nN"] = float(vals.sum()) * a * 1e-3
+    return out
+
+
+def fmt(value, unit="", nd=1):
+    """Format a metric value; '–' when not available."""
+    if value is None:
+        return "–"
+    return f"{value:.{nd}f}{(' ' + unit) if unit else ''}"
+
+
+def metric_rows(metrics):
+    """(label, formatted value) pairs, in the order used everywhere in the app."""
+    return [
+        ("Mean traction stress", fmt(metrics.get("mean_pa"), "Pa")),
+        ("Max traction stress", fmt(metrics.get("max_pa"), "Pa")),
+        ("Area", fmt(metrics.get("area_um2"), "µm²", 0)),
+        ("Total force", fmt(metrics.get("total_force_nN"), "nN", 2)),
+    ]
+
+
+def nice_scale_bar_um(field_width_um, fraction=0.2):
+    """Scale-bar length (µm) from {1, 2, 5} x 10^k closest to `fraction` of the field width."""
+    target = field_width_um * fraction
+    if target <= 0:
+        return None
+    k = np.floor(np.log10(target))
+    candidates = [m * 10 ** k for m in (1, 2, 5, 10)]
+    return float(min(candidates, key=lambda c: abs(c - target)))
+
+
+def draw_scale_bar(rgb, um_per_px, color=(255, 255, 255), margin_frac=0.04):
+    """Draw a µm scale bar (bottom right) on an RGB uint8 image in place. Returns (rgb, length_um)."""
+    import cv2
+
+    if not um_per_px or um_per_px <= 0:
+        return rgb, None
+    h, w = rgb.shape[:2]
+    length_um = nice_scale_bar_um(w * um_per_px)
+    if length_um is None:
+        return rgb, None
+    length_px = int(round(length_um / um_per_px))
+    thick = max(2, h // 120)
+    m = int(margin_frac * w)
+    x1, y = w - m, h - m
+    x0 = x1 - length_px
+    cv2.rectangle(rgb, (x0 - 1, y - thick - 1), (x1 + 1, y + 1), (0, 0, 0), -1)
+    cv2.rectangle(rgb, (x0, y - thick), (x1, y), color, -1)
+    label = f"{length_um:g} um"   # OpenCV fonts have no µ glyph
+    font_scale = max(0.4, w / 1100)
+    (tw, th), _ = cv2.getTextSize(label, cv2.FONT_HERSHEY_SIMPLEX, font_scale, max(1, thick // 2))
+    tx, ty = x0 + (length_px - tw) // 2, y - thick - 6
+    cv2.putText(rgb, label, (tx, ty), cv2.FONT_HERSHEY_SIMPLEX, font_scale, (0, 0, 0), max(2, thick), cv2.LINE_AA)
+    cv2.putText(rgb, label, (tx, ty), cv2.FONT_HERSHEY_SIMPLEX, font_scale, color, max(1, thick // 2), cv2.LINE_AA)
+    return rgb, length_um