pyPetrograph 0.0.5__py3-none-any.whl

pyPetrograph/__init__.py

@@ -0,0 +1,280 @@
+"""
+pyPetrograph: RGB pixel labeling plus a multimodal object pipeline.
+
+RGB notebook: wand/polygon labels → LightGBM class maps → area %.
+Multimodal notebook: align layers → physics channels → grain/pore outlines →
+object table → group/name → LightGBM names the rest → QFL / IGV / Folk & Ward.
+Mineral-map notebook: flat-color mineral maps → legend snap → grains → per-class counts with uncertainty.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.0.5"
+
+from pyPetrograph.common.constants import (
+    CACHE_SUBDIR,
+    DEFAULT_CLASSES,
+    DEFAULT_EMBED_FEATURE_TOGGLES,
+    DEFAULT_FEATURE_TOGGLES,
+    DEFAULT_FIGURE_DPI,
+    DEFAULT_METHOD,
+    DEFAULT_N_JOBS,
+    DEFAULT_PREVIEW_DPI,
+    DEFAULT_PREVIEW_TARGET_MP,
+    DEFAULT_SURE_PROBA,
+    DEFAULT_Y_TARGET,
+    LABELS_SUBDIR,
+    METHODS,
+    MODELS_SUBDIR,
+    PREDICTIONS_SUBDIR,
+    REQUIRED_PACKAGES,
+    SAM2_PACKAGES,
+    SEG_PACKAGES,
+    SUPPORTED_EXTENSIONS,
+    UNIVERSAL_MODEL_NAME,
+)
+from pyPetrograph.common.image_io import load_image
+from pyPetrograph.common.notebook_runners import (
+    print_label_summary,
+    print_train_metrics,
+    run_feature_preview,
+    run_predict_cell,
+    run_scene_feature_preview,
+    run_train_cell,
+)
+from pyPetrograph.common.paths import (
+    check_and_install_packages,
+    cleanup_legacy_outputs,
+    get_output_dir,
+    relpath_display,
+    set_output_dir,
+    stem_paths,
+)
+from pyPetrograph.common.session import Session
+from pyPetrograph.common.ui import (
+    build_ui,
+    launch_app,
+    select_images,
+    # private subprocess entrypoints re-exported for child processes
+    _run_label_gui_from_config,
+    _run_qt_picker_from_config,
+    launch_app_inplace,
+)
+from pyPetrograph.image_processing.brightness import normalize_brightness, relative_luminance
+from pyPetrograph.image_processing.features import (
+    build_feature_stack,
+    downsample_to_approx_mp,
+    resolve_view_target_mp,
+    screen_view_target_mp,
+)
+from pyPetrograph.image_processing.fractions import compute_fractions, compute_fractions_uncertain
+from pyPetrograph.labeling_ml.polygons import magic_wand_to_polygon
+from pyPetrograph.labeling_ml.predict import predict_image, predict_image_proba
+from pyPetrograph.align import (
+    Scene,
+    launch_align,
+    load_scene,
+    save_scene,
+    embed_scene,
+    stack_feature_slots,
+    slot_kind,
+    xpl_slot,
+)
+from pyPetrograph.fuse import (
+    fit_extinction,
+    phi_deg_from_cos_sin,
+    MIN_ANGLES,
+    ChannelStack,
+    DEFAULT_CHANNEL_TOGGLES,
+    build_channel_stack,
+    channel_set_id,
+    channels_paths,
+    save_channel_stack,
+    load_channel_stack,
+    iter_tiles,
+    apply_tiled,
+    axioscan_layers,
+    axioscan_scale_folder,
+    add_axioscan_layers,
+    run_channel_preview,
+)
+from pyPetrograph.objects import (
+    run_watershed,
+    watershed_labels,
+    init_grain_unet,
+    train_grain_unet,
+    predict_grain_unet,
+    grain_unet_path,
+    run_outlines,
+    compare_outlines,
+    launch_grain_qc,
+    launch_ppl_grain_qc,
+    load_grain_qc,
+    load_ppl_grain_qc,
+    grain_qc_paths,
+    load_grain_mask,
+    overlay_labels,
+    ensure_seg_weights,
+    seg_setup_hint,
+    build_object_table,
+    build_object_table_from_stack,
+    save_object_table,
+    load_object_table,
+    cluster_objects,
+    launch_montage_labeler,
+    load_object_labels,
+    apply_object_labels,
+    object_model_path,
+    train_object_classifier,
+    predict_object_classes,
+    save_classes,
+    load_classes,
+    compute_object_stats,
+    save_object_stats,
+    load_object_stats,
+)
+from pyPetrograph.mineral_map import (
+    read_legend_swatches,
+    legend_from_image,
+    check_legend,
+    snap_to_legend,
+    read_rgba,
+    absorb_specks,
+    label_grains,
+    grain_table,
+    grains_to_geojson,
+    class_rgb,
+    count_grains,
+    pivot_counts,
+    format_counts,
+    format_unlisted,
+    mineralmap_paths,
+    process_image,
+    process_folder,
+)
+
+__all__ = [
+    "SUPPORTED_EXTENSIONS",
+    "DEFAULT_Y_TARGET",
+    "DEFAULT_N_JOBS",
+    "DEFAULT_METHOD",
+    "METHODS",
+    "DEFAULT_CLASSES",
+    "REQUIRED_PACKAGES",
+    "SEG_PACKAGES",
+    "SAM2_PACKAGES",
+    "MODELS_SUBDIR",
+    "PREDICTIONS_SUBDIR",
+    "LABELS_SUBDIR",
+    "CACHE_SUBDIR",
+    "UNIVERSAL_MODEL_NAME",
+    "stem_paths",
+    "set_output_dir",
+    "get_output_dir",
+    "relpath_display",
+    "cleanup_legacy_outputs",
+    "load_image",
+    "normalize_brightness",
+    "relative_luminance",
+    "DEFAULT_FEATURE_TOGGLES",
+    "DEFAULT_EMBED_FEATURE_TOGGLES",
+    "DEFAULT_PREVIEW_TARGET_MP",
+    "DEFAULT_PREVIEW_DPI",
+    "DEFAULT_FIGURE_DPI",
+    "check_and_install_packages",
+    "magic_wand_to_polygon",
+    "build_feature_stack",
+    "downsample_to_approx_mp",
+    "screen_view_target_mp",
+    "resolve_view_target_mp",
+    "Session",
+    "select_images",
+    "build_ui",
+    "launch_app",
+    "print_label_summary",
+    "run_feature_preview",
+    "run_scene_feature_preview",
+    "run_train_cell",
+    "print_train_metrics",
+    "run_predict_cell",
+    "predict_image",
+    "predict_image_proba",
+    "compute_fractions",
+    "compute_fractions_uncertain",
+    "__version__",
+    "DEFAULT_SURE_PROBA",
+    "Scene",
+    "launch_align",
+    "save_scene",
+    "load_scene",
+    "embed_scene",
+    "stack_feature_slots",
+    "launch_ppl_grain_qc",
+    "load_ppl_grain_qc",
+    "grain_qc_paths",
+    "load_grain_mask",
+    "seg_setup_hint",
+    "slot_kind",
+    "xpl_slot",
+    "fit_extinction",
+    "phi_deg_from_cos_sin",
+    "MIN_ANGLES",
+    "ChannelStack",
+    "DEFAULT_CHANNEL_TOGGLES",
+    "build_channel_stack",
+    "channel_set_id",
+    "channels_paths",
+    "save_channel_stack",
+    "load_channel_stack",
+    "iter_tiles",
+    "apply_tiled",
+    "axioscan_layers",
+    "axioscan_scale_folder",
+    "add_axioscan_layers",
+    "run_channel_preview",
+    "run_watershed",
+    "watershed_labels",
+    "init_grain_unet",
+    "train_grain_unet",
+    "predict_grain_unet",
+    "grain_unet_path",
+    "run_outlines",
+    "compare_outlines",
+    "launch_grain_qc",
+    "load_grain_qc",
+    "overlay_labels",
+    "ensure_seg_weights",
+    "build_object_table",
+    "build_object_table_from_stack",
+    "save_object_table",
+    "load_object_table",
+    "cluster_objects",
+    "launch_montage_labeler",
+    "load_object_labels",
+    "apply_object_labels",
+    "object_model_path",
+    "train_object_classifier",
+    "predict_object_classes",
+    "save_classes",
+    "load_classes",
+    "compute_object_stats",
+    "save_object_stats",
+    "load_object_stats",
+    "read_legend_swatches",
+    "legend_from_image",
+    "check_legend",
+    "snap_to_legend",
+    "read_rgba",
+    "absorb_specks",
+    "label_grains",
+    "grain_table",
+    "grains_to_geojson",
+    "class_rgb",
+    "count_grains",
+    "pivot_counts",
+    "format_counts",
+    "format_unlisted",
+    "mineralmap_paths",
+    "process_image",
+    "process_folder",
+]

pyPetrograph/align/__init__.py

@@ -0,0 +1,38 @@
+"""Multi-layer lineup: register PPL / XPL / BSE onto one working grid."""
+
+from pyPetrograph.align.embed import embed_scene, stack_feature_slots
+from pyPetrograph.align.grains import (
+    grain_qc_paths,
+    launch_ppl_grain_qc,
+    load_grain_mask,
+    load_ppl_grain_qc,
+    overlay_labels,
+    seg_setup_hint,
+)
+from pyPetrograph.align.io import load_scene, save_scene
+from pyPetrograph.align.register import auto_register, refine_register
+from pyPetrograph.align.scene import Affine2D, Layer, Scene, slot_kind, xpl_slot
+from pyPetrograph.align.structure import structure_map
+from pyPetrograph.align.ui import launch_align
+
+__all__ = [
+    "Affine2D",
+    "Layer",
+    "Scene",
+    "slot_kind",
+    "xpl_slot",
+    "structure_map",
+    "auto_register",
+    "refine_register",
+    "save_scene",
+    "load_scene",
+    "launch_align",
+    "embed_scene",
+    "stack_feature_slots",
+    "launch_ppl_grain_qc",
+    "load_ppl_grain_qc",
+    "grain_qc_paths",
+    "load_grain_mask",
+    "overlay_labels",
+    "seg_setup_hint",
+]

pyPetrograph/align/embed.py

@@ -0,0 +1,281 @@
+"""Embedding field from an aligned Scene. Default C = small autoencoder; B = frozen net."""
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+from sklearn.decomposition import PCA
+from sklearn.neural_network import MLPRegressor
+
+from pyPetrograph.align.scene import Scene
+from pyPetrograph.common.constants import DEFAULT_EMBED_FEATURE_TOGGLES
+from pyPetrograph.image_processing.features import build_feature_stack, resolve_feature_toggles
+
+NAMED_SLOTS: Tuple[str, ...] = ("ppl", "xpl", "bse")
+
+
+def _ordered_slots(scene: Scene) -> List[str]:
+    slots = [s for s in NAMED_SLOTS if s in scene.layers]
+    if scene.working_slot not in slots:
+        slots = [scene.working_slot] + slots
+    seen = set()
+    ordered: List[str] = []
+    for s in slots:
+        if s not in seen and s in scene.layers:
+            seen.add(s)
+            ordered.append(s)
+    return ordered
+
+
+def stack_named_slots(scene: Scene) -> Tuple[np.ndarray, np.ndarray, List[str]]:
+    """
+    Working-grid RGB stack and per-slot coverage (legacy RGB-only helper).
+
+    Returns
+    -------
+    stack : float32 HxWx(3*n_slots), RGB in [0, 1]
+    valid : bool HxWx n_slots — False where that measurement is missing (skip, not fake)
+    names : slot names in order
+    """
+    h, w = scene.working_hw()
+    ordered = _ordered_slots(scene)
+    ch = np.zeros((h, w, 3 * len(ordered)), dtype=np.float32)
+    valid = np.zeros((h, w, len(ordered)), dtype=bool)
+    for i, slot in enumerate(ordered):
+        rgb, mask = scene.warp_layer(slot)
+        ch[:, :, i * 3 : (i + 1) * 3] = rgb.astype(np.float32) / 255.0
+        valid[:, :, i] = mask
+        ch[:, :, i * 3 : (i + 1) * 3][~mask] = 0.0
+    return ch, valid, ordered
+
+
+def stack_feature_slots(
+    scene: Scene,
+    *,
+    feature_toggles: Optional[Dict[str, bool]] = None,
+) -> Tuple[np.ndarray, np.ndarray, List[str], List[str]]:
+    """
+    Per-slot feature stacks on the working grid (shared with RGB notebook).
+
+    For each aligned slot, call ``build_feature_stack`` (Y-norm on RGB, then
+    toggled maps). Prefix channel names with ``ppl_``, ``xpl_``, ``bse_``.
+    Missing / out-of-window pixels are zeroed and marked invalid.
+
+    Returns
+    -------
+    stack : float32 HxWxC
+    valid : bool HxW — True if any slot covers the pixel
+    slot_names : slot order
+    input_names : channel names (e.g. ``ppl_r``, ``xpl_local_grad``)
+    """
+    toggles = resolve_feature_toggles(
+        feature_toggles if feature_toggles is not None else DEFAULT_EMBED_FEATURE_TOGGLES
+    )
+    # Embed never invents GLCM without polygons — force off.
+    toggles["glcm"] = False
+    ordered = _ordered_slots(scene)
+    h, w = scene.working_hw()
+    chunks: List[np.ndarray] = []
+    input_names: List[str] = []
+    any_valid = np.zeros((h, w), dtype=bool)
+    for slot in ordered:
+        rgb, mask = scene.warp_layer(slot)
+        feat, names = build_feature_stack(
+            rgb,
+            toggles=toggles,
+            apply_norm=True,
+            polygons=None,
+        )
+        feat = np.asarray(feat, dtype=np.float32)
+        feat[~mask] = 0.0
+        chunks.append(feat)
+        input_names.extend([f"{slot}_{n}" for n in names])
+        any_valid |= mask
+    if not chunks:
+        raise RuntimeError("No layers in scene to embed.")
+    stack = np.concatenate(chunks, axis=-1).astype(np.float32)
+    return stack, any_valid, ordered, input_names
+
+
+def _mlp_hidden(mlp: MLPRegressor, X: np.ndarray) -> np.ndarray:
+    a = X
+    # all hidden layers; last coefs_ map hidden → reconstruct
+    for i in range(len(mlp.coefs_) - 1):
+        a = np.maximum(0.0, a @ mlp.coefs_[i] + mlp.intercepts_[i])
+    return a.astype(np.float32)
+
+
+def embed_C(
+    scene: Scene,
+    *,
+    hidden: int = 16,
+    max_pixels: int = 80_000,
+    random_state: int = 42,
+    feature_toggles: Optional[Dict[str, bool]] = None,
+) -> Tuple[np.ndarray, Dict[str, object]]:
+    """
+    Small autoencoder on per-slot feature stacks (CPU MLP).
+
+    Inputs come from ``build_feature_stack`` (shared with the RGB notebook).
+    Default toggles: r/g/b + std 7/21/63 + grad + LBP r=1/3/5 + Gabor 0/45/90
+    + Hessian ridge + entropy 7/21/63; no Y, no GLCM.
+
+    Returns HxWxhidden float32 and a small info dict (includes ``input_names``).
+    """
+    stack, any_valid, slot_names, input_names = stack_feature_slots(
+        scene, feature_toggles=feature_toggles
+    )
+    h, w, c = stack.shape
+    X = stack.reshape(-1, c)
+    idx = np.where(any_valid.ravel())[0]
+    if len(idx) == 0:
+        raise RuntimeError("No valid pixels to embed.")
+    rng = np.random.RandomState(random_state)
+    if len(idx) > max_pixels:
+        idx = rng.choice(idx, size=max_pixels, replace=False)
+    # Scale inputs to similar ranges so LBP codes and RGB share the MLP.
+    mu = X[idx].mean(axis=0)
+    sd = X[idx].std(axis=0)
+    sd = np.where(sd < 1e-6, 1.0, sd).astype(np.float32)
+    mu = mu.astype(np.float32)
+
+    def _z(block: np.ndarray) -> np.ndarray:
+        return (block - mu) / sd
+
+    mlp = MLPRegressor(
+        hidden_layer_sizes=(int(hidden),),
+        activation="relu",
+        solver="adam",
+        max_iter=80,
+        random_state=random_state,
+        verbose=False,
+    )
+    mlp.fit(_z(X[idx]), _z(X[idx]))
+    emb = np.zeros((h * w, int(hidden)), dtype=np.float32)
+    step = 200_000
+    for s in range(0, h * w, step):
+        e = min(h * w, s + step)
+        emb[s:e] = _mlp_hidden(mlp, _z(X[s:e]))
+    emb[~any_valid.ravel()] = 0.0
+    field = emb.reshape(h, w, int(hidden))
+    info: Dict[str, object] = {
+        "method": "C",
+        "slots": slot_names,
+        "hidden": int(hidden),
+        "input_names": input_names,
+        "n_input": int(c),
+        "feature_toggles": resolve_feature_toggles(
+            feature_toggles if feature_toggles is not None else DEFAULT_EMBED_FEATURE_TOGGLES
+        ),
+    }
+    return field, info
+
+
+def embed_B(
+    scene: Scene,
+    *,
+    model_name: str = "dinov2_vits14",
+    feature_toggles: Optional[Dict[str, bool]] = None,  # unused; RGB-net path
+) -> Tuple[np.ndarray, Dict[str, object]]:
+    """
+    Frozen pretrained net per available layer; skip missing pixels (no fake BSE).
+
+    Requires ``torch``. Each available RGB layer is encoded; votes are summed
+    only where that layer is valid, then L2-normalized. Output length is fixed.
+    ``feature_toggles`` is accepted for API symmetry with ``embed_C`` but ignored
+    (DINOv2 expects RGB).
+    """
+    try:
+        import torch
+        import torch.nn.functional as F
+    except ImportError as exc:
+        raise ImportError(
+            "embed_B needs PyTorch. In conda env work: pip install torch --index-url "
+            "https://download.pytorch.org/whl/cpu"
+        ) from exc
+
+    stack, valid, names = stack_named_slots(scene)
+    h, w, _ = stack.shape
+    dinov2 = torch.hub.load("facebookresearch/dinov2", model_name, verbose=False)
+    dinov2.eval()
+    votes = None
+    weight = np.zeros((h, w), dtype=np.float32)
+    for i, slot in enumerate(names):
+        rgb = stack[:, :, i * 3 : (i + 1) * 3]
+        mask = valid[:, :, i]
+        if not mask.any():
+            continue
+        t = torch.from_numpy(np.transpose(rgb, (2, 0, 1))).unsqueeze(0).float()
+        # DINOv2 expects ImageNet-sized patches; interpolate to multiple of 14
+        ht = int(np.ceil(h / 14) * 14)
+        wt = int(np.ceil(w / 14) * 14)
+        t = F.interpolate(t, size=(ht, wt), mode="bilinear", align_corners=False)
+        mean = torch.tensor([0.485, 0.456, 0.406]).view(1, 3, 1, 1)
+        std = torch.tensor([0.229, 0.224, 0.225]).view(1, 3, 1, 1)
+        t = (t - mean) / std
+        with torch.no_grad():
+            out = dinov2.forward_features(t)
+            feat = out["x_norm_patchtokens"]  # 1, N, D
+            d = feat.shape[-1]
+            gh, gw = ht // 14, wt // 14
+            fmap = feat.reshape(1, gh, gw, d).permute(0, 3, 1, 2)
+            fmap = F.interpolate(fmap, size=(h, w), mode="bilinear", align_corners=False)
+            arr = fmap[0].permute(1, 2, 0).cpu().numpy().astype(np.float32)
+        if votes is None:
+            votes = np.zeros((h, w, d), dtype=np.float32)
+        votes[mask] += arr[mask]
+        weight[mask] += 1.0
+    if votes is None:
+        raise RuntimeError("No valid pixels to embed.")
+    w3 = np.maximum(weight, 1e-6)[:, :, None]
+    field = votes / w3
+    nrm = np.linalg.norm(field, axis=-1, keepdims=True) + 1e-6
+    field = field / nrm
+    return field, {
+        "method": "B",
+        "slots": names,
+        "model": model_name,
+        "input_names": [f"{s}_rgb" for s in names],
+    }
+
+
+def embedding_to_rgb(field: np.ndarray, *, max_fit: int = 40_000) -> np.ndarray:
+    """False-color view of an embedding field (first 3 PCA axes). Preview only."""
+    h, w, d = field.shape
+    x = np.asarray(field, dtype=np.float32).reshape(-1, d)
+    n = int(x.shape[0])
+    k = min(3, d)
+    rng = np.random.RandomState(0)
+    take = min(int(max_fit), n)
+    idx = rng.choice(n, size=take, replace=False) if n > take else np.arange(n)
+    pca = PCA(n_components=k, random_state=0)
+    try:
+        pca.set_params(svd_solver="covariance_eigh")
+    except ValueError:
+        pca.set_params(svd_solver="randomized")
+    pca.fit(x[idx])
+    vis = np.zeros((n, 3), dtype=np.float32)
+    step = 200_000
+    for s in range(0, n, step):
+        e = min(n, s + step)
+        vis[s:e, :k] = pca.transform(x[s:e]).astype(np.float32)
+    for c in range(k):
+        col = vis[:, c]
+        lo, hi = np.percentile(col, (2, 98))
+        if hi > lo:
+            vis[:, c] = np.clip((col - lo) / (hi - lo), 0, 1)
+    return np.clip(vis.reshape(h, w, 3) * 255.0, 0, 255).astype(np.uint8)
+
+
+def embed_scene(scene: Scene, method: str = "C", **kwargs) -> Tuple[np.ndarray, np.ndarray, Dict]:
+    """
+    Run embedding. ``method`` is ``C`` (default autoencoder) or ``B`` (frozen net).
+
+    Returns (field, rgb_view, info).
+    """
+    m = str(method).upper()
+    if m == "B":
+        field, info = embed_B(scene, **kwargs)
+    else:
+        field, info = embed_C(scene, **kwargs)
+    return field, embedding_to_rgb(field), info

pyPetrograph/align/grains.py

@@ -0,0 +1,22 @@
+"""PPL GrainPlot aliases for ``SegmentEveryGrain_PPL.ipynb``.
+
+Outlines live in ``pyPetrograph.objects.qc``. This module only re-exports the
+names that notebook still imports.
+"""
+from pyPetrograph.objects.qc import (
+    grain_qc_paths,
+    launch_ppl_grain_qc,
+    load_grain_mask,
+    load_ppl_grain_qc,
+    overlay_labels,
+    seg_setup_hint,
+)
+
+__all__ = [
+    "grain_qc_paths",
+    "launch_ppl_grain_qc",
+    "load_grain_mask",
+    "load_ppl_grain_qc",
+    "overlay_labels",
+    "seg_setup_hint",
+]

pyPetrograph/align/io.py

@@ -0,0 +1,77 @@
+"""Save / reload lineup JSON under {image_folder}/align/."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from pyPetrograph.align.scene import Affine2D, Layer, Scene
+from pyPetrograph.common.constants import ALIGN_SUBDIR, PathLike
+from pyPetrograph.common.paths import get_output_dir
+
+
+def align_dir_for(image_path: PathLike) -> Path:
+    p = Path(image_path).resolve()
+    base = get_output_dir() or p.parent
+    d = base / ALIGN_SUBDIR
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def default_json_path(scene: Scene) -> Path:
+    working = scene.working()
+    return align_dir_for(working.path) / f"{working.path.stem}_align.json"
+
+
+def scene_to_dict(scene: Scene) -> Dict[str, Any]:
+    layers = []
+    for slot, layer in scene.layers.items():
+        item: Dict[str, Any] = {
+            "slot": slot,
+            "path": str(layer.path),
+            "transform": layer.transform.as_dict(),
+        }
+        if layer.angle_deg is not None:
+            item["angle_deg"] = float(layer.angle_deg)
+        layers.append(item)
+    return {
+        "version": 1,
+        "working_slot": scene.working_slot,
+        "point_tolerance_px": float(scene.point_tolerance_px),
+        "scale_range": [float(scene.scale_range[0]), float(scene.scale_range[1])],
+        "click_pairs": list(scene.click_pairs),
+        "layers": layers,
+    }
+
+
+def save_scene(scene: Scene, path: Optional[PathLike] = None) -> Path:
+    out = Path(path) if path is not None else default_json_path(scene)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps(scene_to_dict(scene), indent=2), encoding="utf-8")
+    scene.json_path = out
+    return out
+
+
+def load_scene(path: PathLike) -> Scene:
+    p = Path(path)
+    data = json.loads(p.read_text(encoding="utf-8"))
+    scene = Scene(
+        working_slot=str(data.get("working_slot") or "ppl"),
+        point_tolerance_px=float(data.get("point_tolerance_px", 8.0)),
+        json_path=p,
+    )
+    sr = data.get("scale_range") or [0.5, 2.0]
+    scene.scale_range = (float(sr[0]), float(sr[1]))
+    scene.click_pairs = list(data.get("click_pairs") or [])
+    for item in data.get("layers") or []:
+        angle = item.get("angle_deg")
+        layer = Layer(
+            slot=str(item["slot"]),
+            path=Path(item["path"]),
+            transform=Affine2D.from_dict(item.get("transform") or {}),
+            angle_deg=None if angle is None else float(angle),
+        )
+        scene.layers[layer.slot] = layer
+    if scene.working_slot not in scene.layers and scene.layers:
+        scene.working_slot = next(iter(scene.layers))
+    return scene