"""13장 · RF-DETR-Seg: 인스턴스 분할 — 미니 RF-DETR 에 분할 머리를 달아 객체마다 마스크를 낸다.

무엇을 하나
  1. 손계산 예: 질의 임베딩과 픽셀 임베딩의 내적으로 만드는 마스크, 다이스 계수와 IoU, 부드러운 다이스 손실,
     작은 객체에서의 BCE 와 다이스, 깊이별 분리 합성곱의 매개변수 수.
  2. MiniSegHead: 공식 SegmentationHead (rfdetr/models/heads/segmentation.py) 와 같은 구조를 크기만 줄인 분할 머리.
     프로젝터 출력(12×12)을 입력의 1/4(24×24)로 쌍선형 보간 → 깊이별 합성곱 블록(디코더 층마다 하나) → 픽셀 임베딩,
     디코더 층별 질의 임베딩 → MLP 블록 → 내적(einsum) + 편향 = 마스크 로짓.
  3. 손실 · 매칭: 뽑은 점에서만 계산하는 마스크 BCE + 다이스 손실(계수 5 · 5)과, 매칭 비용의 마스크 항.
  4. 본 실험: 11장의 체크포인트 ch11_rfdetr.pt 에서 출발해 분할 머리를 달고 30 에폭 함께 학습 → 박스 AP · 마스크 AP,
     디코더 층별 마스크 품질, 클래스 · 크기 · 가림별 마스크 IoU, 픽셀 임베딩(프로토타입)과 내적 지도 그림.
  5. 절제 실험 (--ablations, 각 4 에폭): BCE 만 / 다이스만 / 둘 다, 점 표본 추출 대 전체 픽셀, 매칭 비용의 마스크 항 유무,
     마스크 해상도 1/4 대 1/2, 분할 머리 없이 같은 만큼 더 학습(박스 AP 대조군). --seed 를 바꿔 여러 번 돌리면 시드별 요약 표가 함께 나온다.
  6. 체크포인트 ch13_seg.pt (일반 가중치 + EMA 가중치 + 설정) 를 실행 폴더에 저장한다.

실행 (시간은 노트북 GPU 한 장을 다른 실험과 나눠 쓰며 잰 값 — 혼자 돌리면 더 빠르다)
  python ch13_seg.py                # 본 실험 (약 10분: 학습 9분 20초 + 분석 20초)
  python ch13_seg.py --ablations    # 절제 실험 (약 8분 30초: 변형 7개 × 4 에폭). ch13_ablations_seed0.json 저장. --seed 1 처럼 시드를 바꿀 수 있다
  python ch13_seg.py --analyze      # 학습 없이, 저장된 ch13_seg.pt 로 분석 표와 그림만 다시 만든다 (약 35초)
  python ch13_seg.py --quick        # 연기 시험 (CPU 약 30초). --quick --ablations 도 된다
그림은 --fig-dir (기본 figures/) 에 저장된다. ch11_rfdetr.pt 가 실행 폴더에 없으면 무작위 초기화에서 시작한다
(먼저 python ch11_train.py 를 돌려 두는 것이 좋다). rfdetr 패키지가 있으면 공식 SegmentationHead · 손실 함수와 수치를 대조하고
RF-DETR-Seg Nano 의 모양을 잰다 (없으면 그 부분만 건너뛴다).

이 파일을 가져다 쓰는 뒤 장은 없다 (14장은 rfdetr 패키지의 분할 모델을 쓴다).
"""

from __future__ import annotations

import argparse
import glob
import json
import os
import time

import numpy as np
import torch
import torch.nn as nn
import torch.nn.functional as F

from ch02_boxes import box_cxcywh_to_xyxy, box_iou, paired_box_iou
from ch03_metrics import COCO_IOU_THRESHOLDS, average_precision, evaluate_ap, precision_recall_curve
from ch07_detr import get_device
from ch10_rfdetr_model import MiniRFDETR
from ch11_train import ModelEMA, RFDETRCriterion, build_optimizer
from rf_shapes import CLASS_NAMES, NUM_CLASSES, ShapesDataset, draw_boxes, make_loader, shape_mask

CHECKPOINT_IN = "ch11_rfdetr.pt"
CHECKPOINT_OUT = "ch13_seg.pt"
INSTANCE_COLORS = ["#E69F00", "#56B4E9", "#009E73", "#F0E442", "#CC79A7", "#D55E00", "#0072B2", "#BBBBBB"]


# ── 1. 분할 머리 ─────────────────────────────────────────────────────────────


# --8<-- [start:dw-block]
class DepthwiseConvBlock(nn.Module):
    """깊이별 분리 합성곱 블록 (공식 DepthwiseConvBlock 과 같다: "MLP 를 뺀 ConvNeXt 블록").

    x (B, C, H, W) → 깊이별 3×3 합성곱(채널마다 따로, groups=C) → 층 정규화 → 1×1 합성곱(Linear 로 구현) → GELU → + x
      깊이별 합성곱: 채널을 섞지 않고 이웃 3×3 칸만 본다.       매개변수 C·9 + C
      1×1 합성곱   : 이웃을 보지 않고 채널만 섞는다 (점별).     매개변수 C·C + C
    둘을 이으면 보통의 3×3 합성곱(C·C·9 + C)이 하는 일을 약 1/8 의 매개변수로 흉내 낸다.
    """

    def __init__(self, dim: int):
        super().__init__()
        self.dwconv = nn.Conv2d(dim, dim, kernel_size=3, padding=1, groups=dim)  # groups=dim: 채널마다 필터 하나
        self.norm = nn.LayerNorm(dim, eps=1e-6)
        self.pwconv1 = nn.Linear(dim, dim)  # 1×1 합성곱과 같은 계산 (칸마다 같은 Linear)
        self.act = nn.GELU()

    def forward(self, x):
        shortcut = x
        x = self.dwconv(x)  # (B, C, H, W)
        x = x.permute(0, 2, 3, 1)  # (B, H, W, C): LayerNorm · Linear 는 마지막 축에 작용한다
        x = self.act(self.pwconv1(self.norm(x)))
        return x.permute(0, 3, 1, 2) + shortcut  # 잔차 연결
# --8<-- [end:dw-block]


# --8<-- [start:seg-head]
class MLPBlock(nn.Module):
    """질의 임베딩용 FFN 블록 (공식 MLPBlock): 층 정규화 → Linear(D → 4D) → GELU → Linear(4D → D) → + 입력."""

    def __init__(self, dim: int):
        super().__init__()
        self.norm_in = nn.LayerNorm(dim)
        self.layers = nn.ModuleList([nn.Linear(dim, dim * 4), nn.GELU(), nn.Linear(dim * 4, dim)])

    def forward(self, x):
        shortcut = x
        x = self.norm_in(x)
        for layer in self.layers:
            x = layer(x)
        return x + shortcut


class MiniSegHead(nn.Module):
    """분할 머리. 공식 SegmentationHead(in_dim, num_blocks, bottleneck_ratio=1, downsample_ratio=4) 와 같은 계산이다.

    픽셀 쪽   spatial (B, D, h, w) 프로젝터 출력
              → 쌍선형 보간으로 (H // r, W // r) 크기로 (r = downsample_ratio)
              → blocks[0] → blocks[1] → … (DepthwiseConvBlock, 디코더 층마다 하나씩 "쌓아" 간다)
              → spatial_features_proj (1×1 합성곱) = 픽셀 임베딩 맵 E_l (B, D, H/r, W/r)
    질의 쪽   디코더 l 번째 층의 질의 임베딩 q_l (B, Q, D)
              → query_features_block (MLPBlock) → query_features_proj (Linear) = f(q_l) (B, Q, D)
    마스크    로짓_l[b, n, y, x] = Σ_c E_l[b, c, y, x] · f(q_l)[b, n, c] + bias      (einsum "bchw,bnc->bnhw")
    블록만 층마다 따로 있고, 1×1 합성곱 · 질의 쪽 MLP · 편향은 모든 층이 함께 쓴다.
    매개변수 이름을 공식 구현과 똑같이 지어서, 공식 머리의 state_dict 를 그대로 실을 수 있다 (check 에서 확인한다).
    """

    def __init__(self, dim: int, num_blocks: int, downsample_ratio: int = 4):
        super().__init__()
        self.downsample_ratio = downsample_ratio
        self.blocks = nn.ModuleList(DepthwiseConvBlock(dim) for _ in range(num_blocks))
        self.spatial_features_proj = nn.Conv2d(dim, dim, kernel_size=1)
        self.query_features_block = MLPBlock(dim)
        self.query_features_proj = nn.Linear(dim, dim)
        self.bias = nn.Parameter(torch.zeros(1))

    def upsample(self, spatial, image_size):
        """프로젝터 출력을 (그림 높이 // r, 그림 너비 // r) 로 쌍선형 보간한다."""
        target = (image_size[0] // self.downsample_ratio, image_size[1] // self.downsample_ratio)
        return F.interpolate(spatial, size=target, mode="bilinear", align_corners=False)

    def pixel_embeddings(self, spatial, image_size, num_layers: int | None = None):
        """층마다의 픽셀 임베딩 맵 [E_1, E_2, …] (각각 (B, D, H/r, W/r)). 그림 그릴 때 쓴다."""
        x = self.upsample(spatial, image_size)
        maps = []
        for block in self.blocks[:num_layers]:
            x = block(x)
            maps.append(self.spatial_features_proj(x))
        return maps

    def query_embeddings(self, query):
        """질의 임베딩 (B, Q, D) → 마스크용 임베딩 f(q) (B, Q, D)."""
        return self.query_features_proj(self.query_features_block(query))

    def forward(self, spatial, query_features, image_size, skip_blocks: bool = False, final_layer_only: bool = False):
        """query_features: [(B, Q, D)] — 디코더 층마다 하나.  돌려주는 값: 마스크 로짓 [(B, Q, H/r, W/r)] 의 목록.

        skip_blocks=True      블록을 건너뛴다 (인코더 제안의 마스크: 질의 임베딩이 하나뿐일 때만).
        final_layer_only=True 블록은 모두 지나가되, 마지막 층의 마스크만 계산한다 (추론).
        질의 임베딩이 k 개면 블록도 앞의 k 개만 쓰인다 (zip) — 디코더 층을 떼면 분할 머리도 그만큼 얕아진다.
        """
        x = self.upsample(spatial, image_size)
        if skip_blocks:
            assert len(query_features) == 1
            embed = self.spatial_features_proj(x)
            return [torch.einsum("bchw,bnc->bnhw", embed, self.query_embeddings(query_features[0])) + self.bias]
        logits = []
        last = min(len(self.blocks), len(query_features)) - 1
        for layer, (block, query) in enumerate(zip(self.blocks, query_features)):
            x = block(x)  # 블록은 앞 층의 결과 위에 쌓인다
            if final_layer_only and layer < last:
                continue
            embed = self.spatial_features_proj(x)  # 픽셀 임베딩 맵 (B, D, H/r, W/r)
            logits.append(torch.einsum("bchw,bnc->bnhw", embed, self.query_embeddings(query)) + self.bias)
        return logits
# --8<-- [end:seg-head]


# --8<-- [start:seg-model]
class MiniRFDETRSeg(MiniRFDETR):
    """미니 RF-DETR-Seg = 10장의 MiniRFDETR + MiniSegHead. 탐지 쪽 계산은 한 줄도 바꾸지 않는다.

    출력에 "pred_masks" (B, Q, H/r, W/r) 마스크 로짓이 더해진다 (r = mask_downsample_ratio, 공식 기본값 4).
      학습 모드: 앞 디코더 층들(aux_outputs) 과 인코더 제안(enc_outputs) 에도 "pred_masks" 가 들어간다 (손실용).
      추론 모드: 마지막 층의 마스크만 (all_layer_masks=True 면 학습 모드처럼 전부).
      dec_layers=0 이면 인코더 제안의 마스크(블록을 건너뛴 것)가 곧 예측이다.
    분할 머리가 쓰는 것은 둘뿐이다: 프로젝터 출력 한 장(변형 교차 어텐션이 읽는 바로 그 맵)과 디코더 층별 질의 임베딩.
    """

    def __init__(self, mask_downsample_ratio: int = 4, **config):
        super().__init__(**config)
        self.config = dict(self.config, mask_downsample_ratio=mask_downsample_ratio)
        self.segmentation_head = MiniSegHead(self.hidden_dim, len(self.decoder), mask_downsample_ratio)

    def forward(self, images, num_windows=None, patch_size=None, dec_layers=None, num_queries=None,
                return_features: bool = False, all_layer_masks: bool = False):
        outputs = super().forward(images, num_windows, patch_size, dec_layers, num_queries, return_features=True)
        features = outputs["features"] if return_features else outputs.pop("features")
        spatial = features["projector"][0]  # (B, D, 12, 12)
        image_size = images.shape[-2:]
        head = self.segmentation_head
        aux_masks = self.training or all_layer_masks
        if "hs" not in features:  # 디코더가 없다: 인코더 제안의 특징으로 마스크를 만든다
            outputs["pred_masks"] = head(spatial, [features["enc_hs"]], image_size, skip_blocks=True)[0]
            return outputs
        masks = head(spatial, list(features["hs"]), image_size, final_layer_only=not aux_masks)
        outputs["pred_masks"] = masks[-1]
        if aux_masks:
            for layer, layer_masks in zip(outputs["aux_outputs"], masks[:-1]):
                layer["pred_masks"] = layer_masks
            outputs["enc_outputs"]["pred_masks"] = head(spatial, [features["enc_hs"]], image_size, skip_blocks=True)[0]
        return outputs
# --8<-- [end:seg-model]


# ── 2. 마스크 손실 ───────────────────────────────────────────────────────────


# --8<-- [start:point-sample]
def point_sample(maps, coords, mode: str = "bilinear"):
    """맵 (N, C, H, W) 을 정규화 좌표 coords (N, P, 2) — (x, y), 0 – 1 — 의 점들에서 읽는다 → (N, C, P).

    mode="bilinear" 는 8장의 쌍선형 보간 (예측 로짓용), "nearest" 는 가장 가까운 픽셀의 값 (0/1 정답 마스크용).
    좌표 약속: 픽셀 (행 i, 열 j) 의 중심이 ((j + 0.5) / W, (i + 0.5) / H) (align_corners=False).
    """
    grid = 2.0 * coords[:, :, None, :] - 1.0  # grid_sample 은 −1 … 1 좌표를 받는다. (N, P, 1, 2)
    return F.grid_sample(maps, grid, mode=mode, padding_mode="border", align_corners=False).squeeze(3)


@torch.no_grad()
def sample_uncertain_points(logits, num_points: int, oversample_ratio: int = 3, importance_ratio: float = 0.75):
    """마스크마다 손실을 계산할 점 num_points 개를 고른다 (공식 get_uncertain_point_coords_with_randomness).

    logits: (M, 1, h, w) 매칭된 예측 마스크의 로짓.  돌려주는 값: (M, num_points, 2) 정규화 (x, y).
      1) 균등하게 3·P 개의 후보 점을 뽑아 그 점의 로짓을 읽는다.
      2) "불확실성" = −|로짓| 이 큰 (로짓이 0 에 가까운 = 경계 근처) 순으로 0.75·P 개를 고른다.
      3) 나머지 0.25·P 개는 다시 균등하게 뽑는다 (쉬운 곳도 잊지 않게).
    """
    count = logits.shape[0]
    candidates = torch.rand(count, num_points * oversample_ratio, 2, device=logits.device)
    uncertainty = -point_sample(logits, candidates).abs()[:, 0]  # (M, 3P)
    num_uncertain = int(importance_ratio * num_points)
    top = uncertainty.topk(num_uncertain, dim=1).indices  # (M, 0.75P)
    chosen = torch.gather(candidates, 1, top[..., None].expand(-1, -1, 2))
    extra = torch.rand(count, num_points - num_uncertain, 2, device=logits.device)
    return torch.cat([chosen, extra], dim=1)


def pixel_center_points(height: int, width: int, device):
    """정답 마스크의 모든 픽셀 중심 (H·W, 2). "점 표본 추출 없이 전체 픽셀로" 계산할 때 쓴다."""
    ys = (torch.arange(height, device=device, dtype=torch.float32) + 0.5) / height
    xs = (torch.arange(width, device=device, dtype=torch.float32) + 0.5) / width
    return torch.stack(torch.meshgrid(xs, ys, indexing="xy"), dim=-1).reshape(-1, 2)
# --8<-- [end:point-sample]


# --8<-- [start:mask-loss]
def sigmoid_ce_loss(logits, labels, num_masks):
    """마스크 BCE (공식 sigmoid_ce_loss). logits · labels: (M, P) — 마스크 M 개, 점 P 개.

    점마다 BCE → 마스크 안에서 점 평균 → 마스크들을 더해 num_masks (= 정답 수 × 묶음 수) 로 나눈다.
    """
    loss = F.binary_cross_entropy_with_logits(logits, labels, reduction="none")
    return loss.mean(1).sum() / num_masks


def dice_loss(logits, labels, num_masks):
    """다이스 손실 (공식 dice_loss). 1 − (2·Σ p·t + 1) / (Σ p + Σ t + 1), p = σ(로짓). 분자 · 분모의 +1 이 평활 항."""
    prob = logits.sigmoid()
    numerator = 2 * (prob * labels).sum(-1)
    denominator = prob.sum(-1) + labels.sum(-1)
    loss = 1 - (numerator + 1) / (denominator + 1)
    return loss.sum() / num_masks


def pairwise_sigmoid_ce(logits, labels):
    """매칭 비용용: 예측 N 개 × 정답 T 개의 모든 쌍의 BCE (점 평균). logits (N, P), labels (T, P) → (N, T)."""
    pos = F.binary_cross_entropy_with_logits(logits, torch.ones_like(logits), reduction="none")  # 정답이 1 인 점의 손실
    neg = F.binary_cross_entropy_with_logits(logits, torch.zeros_like(logits), reduction="none")  # 정답이 0 인 점의 손실
    return (pos @ labels.T + neg @ (1 - labels).T) / logits.shape[1]


def pairwise_dice(logits, labels):
    """매칭 비용용: 모든 쌍의 다이스 손실 (N, T)."""
    prob = logits.sigmoid()
    numerator = 2 * prob @ labels.T
    denominator = prob.sum(-1)[:, None] + labels.sum(-1)[None, :]
    return 1 - (numerator + 1) / (denominator + 1)
# --8<-- [end:mask-loss]


# --8<-- [start:seg-criterion]
class SegCriterion(RFDETRCriterion):
    """11장의 RFDETRCriterion 에 마스크 항을 더한 것 (공식 SetCriterion.loss_masks · HungarianMatcher 의 마스크 비용).

    매칭 비용   2·C_cls + 5·C_L1 + 2·C_GIoU + mask_ce·C_maskBCE + mask_dice·C_maskDice
                마스크 비용은 (h·w) // point_sample_ratio 개의 "모두가 함께 쓰는" 균등 무작위 점에서 계산한다.
    손실        층마다 loss_ce + 5·loss_bbox + 2·loss_giou + mask_ce·loss_maskce + mask_dice·loss_maskdice
                마스크 손실은 매칭된 쌍마다 "불확실한 점 위주로" 뽑은 max(h, (h·w) // point_sample_ratio) 개의 점에서 계산한다.
    points="all" 이면 손실을 정답 마스크의 모든 픽셀에서 계산한다 (예측 로짓을 정답 해상도로 쌍선형 보간한 것과 같다).
    mask_cost=False 면 매칭 비용에 마스크 항을 넣지 않는다 (절제 실험용).
    정답은 t["masks"] (T_b, H, W) bool 을 더 가져야 한다.
    """

    def __init__(self, num_classes: int = NUM_CLASSES, group_detr: int = 4, mask_ce: float = 5.0, mask_dice: float = 5.0,
                 point_sample_ratio: int = 16, points: str = "uncertain", mask_cost: bool = True, **kwargs):
        super().__init__(num_classes, group_detr, **kwargs)
        assert points in ("uncertain", "all")
        self.weights.update({"loss_maskce": mask_ce, "loss_maskdice": mask_dice})
        self.point_sample_ratio, self.points, self.mask_cost = point_sample_ratio, points, mask_cost

    @torch.no_grad()
    def mask_cost_matrix(self, pred_masks, tgt_masks):
        """층 하나의 마스크 비용. pred_masks (B, Q, h, w) 로짓, tgt_masks (ΣT, H, W) 0/1 → (B·Q, ΣT)."""
        height, width = pred_masks.shape[-2:]
        num_points = height * width // self.point_sample_ratio
        coords = torch.rand(1, num_points, 2, device=pred_masks.device)  # 모든 예측 · 정답이 같은 점을 쓴다
        flat = pred_masks.flatten(0, 1)[:, None]  # (B·Q, 1, h, w)
        logits = point_sample(flat, coords.expand(flat.shape[0], -1, -1))[:, 0]  # (B·Q, P)
        labels = point_sample(tgt_masks[:, None], coords.expand(tgt_masks.shape[0], -1, -1), mode="nearest")[:, 0]
        return (self.weights["loss_maskce"] * pairwise_sigmoid_ce(logits, labels)
                + self.weights["loss_maskdice"] * pairwise_dice(logits, labels))

    @torch.no_grad()
    def match_layers(self, layers, targets, groups: int):
        """11장과 같은 묶음별 헝가리안 매칭. 비용에 마스크 항만 더한다."""
        logits = torch.stack([layer["pred_logits"] for layer in layers])  # (S, B, Q, K)
        boxes = torch.stack([layer["pred_boxes"] for layer in layers])
        num_layers, batch, total = logits.shape[:3]
        sizes = [len(t["labels"]) for t in targets]
        offsets = np.cumsum([0] + sizes)
        cost = self.matcher.cost_matrix(logits.flatten(0, 2), boxes.flatten(0, 2),
                                        torch.cat([t["labels"] for t in targets]),
                                        torch.cat([t["boxes"] for t in targets])).view(num_layers, batch * total, -1)
        if self.mask_cost:
            tgt_masks = torch.cat([t["masks"] for t in targets]).float()
            cost = cost + torch.stack([self.mask_cost_matrix(layer["pred_masks"], tgt_masks) for layer in layers])
        cost = cost.view(num_layers, batch, total, -1).cpu().numpy()  # (S, B, Q, ΣT)
        layer_ids, batch_ids, query_ids, target_ids = [], [], [], []
        for s in range(num_layers):
            for b in range(batch):
                if sizes[b] == 0:
                    continue
                rows, cols = self.matcher.assign_groups(cost[s, b, :, offsets[b]:offsets[b + 1]], groups)
                layer_ids.append(np.full(len(rows), s))
                batch_ids.append(np.full(len(rows), b))
                query_ids.append(rows)
                target_ids.append(cols + offsets[b])
        index = np.stack([np.concatenate(ids) for ids in (layer_ids, batch_ids, query_ids, target_ids)])
        index = torch.as_tensor(index, dtype=torch.long, device=logits.device)
        return [tuple(index[1:, index[0] == s]) for s in range(num_layers)]

    def mask_loss(self, pred_masks, matched, tgt_masks, num_boxes):
        """층 하나의 마스크 손실 둘. pred_masks (B, Q, h, w), tgt_masks (ΣT, H, W) float."""
        batch_idx, query_idx, tgt_idx = matched
        source = pred_masks[batch_idx, query_idx][:, None]  # (M, 1, h, w): 매칭된 예측 마스크의 로짓
        target = tgt_masks[tgt_idx][:, None]  # (M, 1, H, W): 그 짝인 정답 마스크
        if self.points == "uncertain":
            height, width = source.shape[-2:]
            num_points = max(height, height * width // self.point_sample_ratio)
            coords = sample_uncertain_points(source, num_points)  # (M, P, 2): 쌍마다 다른 점
        else:
            coords = pixel_center_points(*target.shape[-2:], source.device)[None].expand(len(source), -1, -1)
        point_logits = point_sample(source, coords)[:, 0]  # (M, P): 예측은 쌍선형 보간으로 — 기울기가 흐른다
        point_labels = point_sample(target, coords, mode="nearest")[:, 0]  # (M, P): 정답은 가장 가까운 픽셀의 0/1
        return {"loss_maskce": sigmoid_ce_loss(point_logits, point_labels, num_boxes),
                "loss_maskdice": dice_loss(point_logits, point_labels, num_boxes)}

    def forward(self, outputs, targets, return_matches: bool = False):
        """11장 forward 와 같은 흐름. 층마다 (탐지 손실 셋) + (마스크 손실 둘)."""
        groups = self.group_detr if self.training else 1
        layers = [outputs] + list(outputs.get("aux_outputs", []))
        suffixes = [""] + [f"_{i}" for i in range(len(layers) - 1)]
        if "enc_outputs" in outputs:
            layers.append(outputs["enc_outputs"])
            suffixes.append("_enc")
        tgt_labels = torch.cat([t["labels"] for t in targets])
        tgt_boxes = torch.cat([t["boxes"] for t in targets])
        tgt_masks = torch.cat([t["masks"] for t in targets]).float()
        num_boxes = max(len(tgt_labels) * groups, 1)
        matches = self.match_layers(layers, targets, groups)
        losses = {}
        for layer, suffix, matched in zip(layers, suffixes, matches):
            values = self.layer_loss(layer, matched, tgt_labels, tgt_boxes, num_boxes)  # 11장: loss_ce · loss_bbox · loss_giou
            values.update(self.mask_loss(layer["pred_masks"], matched, tgt_masks, num_boxes))
            for name, value in values.items():
                losses[name + suffix] = value
        losses["loss"] = sum(self.weights["_".join(k.split("_")[:2])] * v for k, v in losses.items())
        return (losses, matches) if return_matches else losses
# --8<-- [end:seg-criterion]


# ── 3. 후처리와 채점 ─────────────────────────────────────────────────────────


# --8<-- [start:postprocess]
@torch.no_grad()
def postprocess_seg(outputs, image_size, num_select: int | None = None):
    """탐지 후처리(10장) + 마스크. 공식 PostProcess._postprocess_masks 와 같은 순서다.

    1) (질의, 클래스) 쌍의 시그모이드 점수 상위 num_select 개를 고른다 (NMS 없음).
    2) 고른 질의의 마스크 로짓 (h, w) 을 그림 크기 (H, W) 로 쌍선형 보간한다.
    3) 로짓 > 0 (= 확률 > 0.5) 인 픽셀을 True 로.
    돌려주는 값: 그림마다 {"boxes" (S, 4), "scores" (S,), "labels" (S,), "masks" (S, H, W) bool}.
    """
    prob = outputs["pred_logits"].sigmoid()  # (B, Q, K)
    batch, num_queries, num_classes = prob.shape
    scores, index = prob.flatten(1).topk(num_select or num_queries, dim=1)
    query, labels = index // num_classes, index % num_classes
    boxes = torch.gather(outputs["pred_boxes"], 1, query[..., None].expand(-1, -1, 4))
    low = outputs["pred_masks"]  # (B, Q, h, w)
    low = torch.gather(low, 1, query[..., None, None].expand(-1, -1, *low.shape[-2:]))  # (B, S, h, w)
    masks = F.interpolate(low, size=tuple(image_size), mode="bilinear", align_corners=False) > 0.0
    return [{"boxes": b, "scores": s, "labels": c, "masks": m} for b, s, c, m in zip(boxes, scores, labels, masks)]
# --8<-- [end:postprocess]


# --8<-- [start:mask-ap]
def mask_iou(masks_a, masks_b):
    """마스크 IoU, 모든 쌍. masks_a (n, H, W) bool, masks_b (m, H, W) bool → (n, m). 박스 IoU 의 넓이를 픽셀 수로 바꾼 것."""
    a = masks_a.flatten(1)[:, None]  # (n, 1, H·W)
    b = masks_b.flatten(1)[None]  # (1, m, H·W)
    inter = (a & b).sum(-1).float()  # 둘 다 True 인 픽셀 수
    union = (a | b).sum(-1).float()  # 하나라도 True 인 픽셀 수
    return inter / union.clamp(min=1.0)


def match_by_iou(iou, iou_threshold: float):
    """3장 match_detections 와 같은 탐욕 매칭. iou: (예측 수, 정답 수) — 행이 이미 점수 내림차순."""
    is_tp = torch.zeros(iou.shape[0], dtype=torch.bool)
    if iou.numel() == 0:
        return is_tp
    used = torch.zeros(iou.shape[1], dtype=torch.bool)
    for rank in range(iou.shape[0]):
        candidate = iou[rank].clone()
        candidate[used] = -1.0
        best_iou, best_gt = candidate.max(dim=0)
        if best_iou >= iou_threshold:
            is_tp[rank] = True
            used[best_gt] = True
    return is_tp


def evaluate_ap_with(iou_fn, predictions, targets, num_classes: int, iou_thresholds=COCO_IOU_THRESHOLDS,
                     max_dets: int = 100):
    """3장 evaluate_ap 와 같은 채점. "예측과 정답이 얼마나 겹치는가" 를 재는 함수 iou_fn 만 갈아 끼운다.

    iou_fn(pred, target, pred_index, gt_index) → (예측 수, 정답 수) IoU.  돌려주는 값은 evaluate_ap 와 같은 사전.
    """
    table = np.full((len(iou_thresholds), num_classes), np.nan)
    for cls in range(num_classes):
        num_gt = sum(int((t["labels"] == cls).sum()) for t in targets)
        if num_gt == 0:
            continue
        scores_all, tp_all = [], [[] for _ in iou_thresholds]
        for pred, target in zip(predictions, targets):
            keep = torch.argsort(pred["scores"], descending=True)[:max_dets]  # 점수 내림차순
            keep = keep[pred["labels"][keep] == cls]
            gt_index = torch.nonzero(target["labels"] == cls)[:, 0]
            iou = iou_fn(pred, target, keep, gt_index)  # IoU 는 그림 · 클래스마다 한 번만 계산한다
            scores_all.append(pred["scores"][keep])
            for ti, threshold in enumerate(iou_thresholds):
                tp_all[ti].append(match_by_iou(iou, threshold))
        scores_all = torch.cat(scores_all).numpy()
        order = np.argsort(-scores_all, kind="stable")
        for ti in range(len(iou_thresholds)):
            precision, recall = precision_recall_curve(torch.cat(tp_all[ti]).numpy()[order], num_gt)
            table[ti, cls] = average_precision(precision, recall)
    per_threshold = np.nanmean(table, axis=1)
    result = {"AP": float(np.nanmean(per_threshold)), "per_class": np.nanmean(table, axis=0), "table": table}
    for name, value in (("AP50", 0.5), ("AP75", 0.75)):
        if value in iou_thresholds:
            result[name] = float(per_threshold[iou_thresholds.index(value)])
    return result


def evaluate_mask_ap(predictions, targets, num_classes: int = NUM_CLASSES, **kwargs):
    """마스크 AP: 박스 AP 와 똑같이 채점하되 IoU 를 마스크끼리 잰다.

    predictions[i]["masks"] (n, H, W) bool, targets[i]["masks"] (m, H, W) bool.
    """
    def iou_fn(pred, target, pred_index, gt_index):
        return mask_iou(pred["masks"][pred_index], target["masks"][gt_index])
    return evaluate_ap_with(iou_fn, predictions, targets, num_classes, **kwargs)


def evaluate_box_ap(predictions, targets, num_classes: int = NUM_CLASSES, **kwargs):
    """같은 틀에 박스 IoU 를 끼운 것. 3장 evaluate_ap 와 값이 같아야 한다 (check)."""
    def iou_fn(pred, target, pred_index, gt_index):
        return box_iou(box_cxcywh_to_xyxy(pred["boxes"][pred_index]), box_cxcywh_to_xyxy(target["boxes"][gt_index]))[0]
    return evaluate_ap_with(iou_fn, predictions, targets, num_classes, **kwargs)
# --8<-- [end:mask-ap]


# ── 4. 학습 ──────────────────────────────────────────────────────────────────


# --8<-- [start:train]
def seg_targets_to(targets, device):
    """정답 목록(박스 · 클래스 · 마스크)을 장치로 옮긴다. 이어 붙여 한 번에 옮긴 뒤 다시 나눈다."""
    sizes = [len(t["labels"]) for t in targets]
    boxes = torch.cat([t["boxes"] for t in targets]).to(device).split(sizes)
    labels = torch.cat([t["labels"] for t in targets]).to(device).split(sizes)
    masks = torch.cat([t["masks"] for t in targets]).to(device).split(sizes)
    return [{"boxes": b, "labels": c, "masks": m} for b, c, m in zip(boxes, labels, masks)]


def train_one_epoch(model, criterion, loader, optimizer, device, ema: ModelEMA | None = None, max_norm: float = 0.1):
    """한 에폭 학습 (11장과 같은 고리: 기울기 자르기 0.1, 스텝마다 EMA). 돌려주는 값: 손실 이름 → 에폭 평균."""
    model.train()
    criterion.train()
    sums, steps = {}, 0
    for images, targets in loader:
        losses = criterion(model(images.to(device)), seg_targets_to(targets, device))
        optimizer.zero_grad(set_to_none=True)
        losses["loss"].backward()
        nn.utils.clip_grad_norm_(model.parameters(), max_norm)
        optimizer.step()
        if ema is not None:
            ema.update(model)
        for k, v in losses.items():
            sums[k] = sums.get(k, 0.0) + v.detach()
        steps += 1
    return {k: float(v) / steps for k, v in sums.items()}


@torch.no_grad()
def predict_seg(model, dataset, device, batch_size: int = 250, **forward_kwargs):
    """데이터셋 전체를 추론 모드로 순전파 → 후처리한 예측 목록 (CPU). 분할 머리가 없는 모델이면 "masks" 가 없다."""
    model.eval()
    size = dataset.images.shape[-2:]
    predictions = []
    for start in range(0, len(dataset), batch_size):
        images = dataset.images[start:start + batch_size].to(device).float() / 255.0
        outputs = model(images, **forward_kwargs)
        if "pred_masks" in outputs:
            batch_predictions = postprocess_seg(outputs, size)
        else:
            from ch10_rfdetr_model import postprocess
            batch_predictions = postprocess(outputs)
        predictions.extend({k: v.cpu() for k, v in p.items()} for p in batch_predictions)
    return predictions


def evaluate_seg(model, dataset, device, **forward_kwargs):
    """돌려주는 값: (박스 AP 결과, 마스크 AP 결과 또는 None, 예측 목록)."""
    predictions = predict_seg(model, dataset, device, **forward_kwargs)
    box = evaluate_box_ap(predictions, dataset.targets)  # 3장 evaluate_ap 와 같은 값 (check), 더 빠르다
    mask = evaluate_mask_ap(predictions, dataset.targets) if "masks" in predictions[0] else None
    return box, mask, predictions


def build_model(device, seed: int = 0, with_head: bool = True, mask_downsample_ratio: int = 4, verbose: bool = True):
    """ch11_rfdetr.pt 의 EMA 가중치(11장에서 평가에 쓴 가중치)에서 출발하는 모델. 분할 머리만 새로 초기화된다.

    체크포인트가 없으면 전부 무작위 초기화. 돌려주는 값: (모델, 체크포인트를 실었는지).
    """
    torch.manual_seed(seed)
    config, state = {}, None
    if os.path.exists(CHECKPOINT_IN):
        checkpoint = torch.load(CHECKPOINT_IN, map_location="cpu")
        config, state = checkpoint["config"], checkpoint["ema"]
    model = MiniRFDETRSeg(mask_downsample_ratio, **config) if with_head else MiniRFDETR(**config)
    if state is not None:
        missing, unexpected = model.load_state_dict(state, strict=False)
        assert not unexpected and all(k.startswith("segmentation_head.") for k in missing)
        if verbose:
            print(f"  {CHECKPOINT_IN} 의 EMA 가중치를 실었다. 새로 초기화된 텐서 {len(missing)}개 (모두 segmentation_head.*)")
    elif verbose:
        print(f"  ({CHECKPOINT_IN} 가 없어 무작위 초기화에서 시작한다 — 11장을 먼저 돌리면 거기서 이어 학습한다)")
    return model.to(device), state is not None


def fit(model, criterion, optimizer, loader, val_set, epochs: int, device, ema: ModelEMA, verbose: bool = True):
    """epochs 에폭 학습하며 에폭마다 EMA 모델을 채점한다. 돌려주는 값: 기록 사전 (에폭 0 = 학습 전)."""
    keys = ("epoch", "loss", "loss_ce", "loss_bbox", "loss_giou", "loss_maskce", "loss_maskdice", "time",
            "box_AP", "mask_AP", "mask_AP50", "mask_AP75")
    history = {k: [] for k in keys}
    box, mask, _ = evaluate_seg(ema.module, val_set, device)
    history["epoch"].append(0)
    history["box_AP"].append(box["AP"])
    for k in ("AP", "AP50", "AP75"):
        history["mask_" + k].append(mask[k] if mask else float("nan"))
    if verbose:
        print(f"에폭   0 | (학습 전) 박스 AP {box['AP']:.4f}" + (f" | 마스크 AP {mask['AP']:.4f}" if mask else ""))
    start = time.time()
    for epoch in range(1, epochs + 1):
        losses = train_one_epoch(model, criterion, loader, optimizer, device, ema)
        history["epoch"].append(epoch)
        history["time"].append(time.time() - start)
        for k in keys[1:7]:
            history[k].append(losses.get(k, float("nan")))
        box, mask, _ = evaluate_seg(ema.module, val_set, device)
        history["box_AP"].append(box["AP"])
        for k in ("AP", "AP50", "AP75"):
            history["mask_" + k].append(mask[k] if mask else float("nan"))
        if verbose:
            text = (f"maskce {losses['loss_maskce']:.4f} maskdice {losses['loss_maskdice']:.4f}) | 박스 AP {box['AP']:.4f} | "
                    f"마스크 AP {mask['AP']:.4f} AP50 {mask['AP50']:.4f} AP75 {mask['AP75']:.4f}" if mask else
                    f") | 박스 AP {box['AP']:.4f}")
            print(f"에폭 {epoch:3d} | 손실 {losses['loss']:7.4f} (ce {losses['loss_ce']:.4f} bbox {losses['loss_bbox']:.4f} "
                  f"giou {losses['loss_giou']:.4f} {text} | {time.time() - start:4.0f}초", flush=True)
    return history


def run_experiment(name, train_set, val_set, epochs, device, seed: int = 0, with_head: bool = True,
                   mask_downsample_ratio: int = 4, batch_size: int = 32, lr: float = 2e-4, verbose: bool = True,
                   **criterion_kwargs):
    """모델(체크포인트에서) · 손실 · 옵티마이저 · EMA 를 만들어 학습한다. 돌려주는 값: (model, ema, history).

    옵티마이저는 11장 build_optimizer 그대로다 (분할 머리는 "그 밖" 그룹: 기본 학습률 2e-4, 감쇠 없음).
    """
    print(f"\n[{name}]")
    model, _ = build_model(device, seed, with_head, mask_downsample_ratio, verbose)
    if with_head:
        criterion = SegCriterion(NUM_CLASSES, group_detr=model.group_detr, **criterion_kwargs).to(device)
    else:
        criterion = RFDETRCriterion(NUM_CLASSES, group_detr=model.group_detr).to(device)
    optimizer, _ = build_optimizer(model, lr)
    ema = ModelEMA(model)
    loader = make_loader(train_set, batch_size, shuffle=True, seed=seed)
    if verbose:
        head = sum(p.numel() for p in model.segmentation_head.parameters()) if with_head else 0
        print(f"  매개변수 {sum(p.numel() for p in model.parameters()):,}개 (분할 머리 {head:,}개), 에폭 {epochs}, "
              f"에폭당 {len(loader)} 스텝, 학습 그림 {len(train_set)}장")
    history = fit(model, criterion, optimizer, loader, val_set, epochs, device, ema, verbose)
    return model, ema, history
# --8<-- [end:train]


# ── 5. 손계산 예와 check ─────────────────────────────────────────────────────


def hand_examples():
    """본문의 손계산을 코드로 다시 계산해 보인다."""
    print("[손계산 1] 내적으로 만드는 마스크: 2×2 픽셀, 임베딩 2차원, 질의 2개")
    pixels = torch.tensor([[[2.0, 0.0], [1.0, 1.0]], [[0.0, 2.0], [-1.0, -1.0]]])  # (행, 열, 2): e(x, y)
    queries = torch.tensor([[2.0, -1.0], [-1.0, 1.5]])  # f(q_1), f(q_2)
    logits = torch.einsum("hwc,nc->nhw", pixels, queries)
    for n in range(2):
        print(f"  질의 {n + 1} f(q) = {queries[n].tolist()}: 로짓 {logits[n].tolist()} → 확률 "
              f"{[[round(v, 3) for v in row] for row in logits[n].sigmoid().tolist()]} → 마스크 {(logits[n] > 0).int().tolist()}")

    print("[손계산 2] 다이스 계수와 IoU: |A| = 6, |B| = 4, |A∩B| = 3")
    inter, area_a, area_b = 3, 6, 4
    iou = inter / (area_a + area_b - inter)
    dice = 2 * inter / (area_a + area_b)
    print(f"  IoU = 3/7 = {iou:.4f}, 다이스 = 6/10 = {dice:.4f}, 2·IoU/(1 + IoU) = {2 * iou / (1 + iou):.4f}")
    print("  IoU  → 다이스: " + ", ".join(f"{v:.2f} → {2 * v / (1 + v):.4f}" for v in (0.1, 0.25, 0.5, 0.75, 0.9)))

    print("[손계산 3] 부드러운 다이스 손실 (+1 평활): p = (0.9, 0.8, 0.3, 0.1), t = (1, 1, 0, 0)")
    prob = torch.tensor([[0.9, 0.8, 0.3, 0.1]])
    label = torch.tensor([[1.0, 1.0, 0.0, 0.0]])
    logit = torch.logit(prob)
    numerator, denominator = 2 * (prob * label).sum(), prob.sum() + label.sum()
    print(f"  분자 2·Σpt = {numerator:.2f}, 분모 Σp + Σt = {denominator:.2f}, 손실 = 1 − ({numerator:.2f} + 1)/({denominator:.2f} + 1) "
          f"= {1 - (numerator + 1) / (denominator + 1):.4f}  (dice_loss 함수: {dice_loss(logit, label, 1):.4f})")
    print(f"  평활 없이: 1 − {numerator:.2f}/{denominator:.2f} = {1 - numerator / denominator:.4f}. "
          f"같은 점들의 BCE 평균 = {sigmoid_ce_loss(logit, label, 1):.4f}")
    prob_g = prob.clone().requires_grad_(True)
    soft = 1 - (2 * (prob_g * label).sum() + 1) / (prob_g.sum() + label.sum() + 1)
    bce = F.binary_cross_entropy(prob_g, label)
    grad_dice, grad_bce = torch.autograd.grad(soft, prob_g, retain_graph=True)[0][0], torch.autograd.grad(bce, prob_g)[0][0]
    by_hand = [-(2 * 5.1 - 4.4) / 5.1**2, 4.4 / 5.1**2]
    print(f"  ∂(다이스 손실)/∂p_i (autograd): {[round(v, 4) for v in grad_dice.tolist()]}  손계산: t = 1 인 점 "
          f"−(2·5.1 − 4.4)/5.1² = {by_hand[0]:.4f}, t = 0 인 점 4.4/5.1² = {by_hand[1]:.4f}")
    print(f"  ∂(BCE 평균)/∂p_i (autograd): {[round(v, 4) for v in grad_bce.tolist()]}")
    empty = torch.zeros(1, 4)
    print(f"  정답이 빈 마스크이고 p = (0.01, 0.01, 0.01, 0.01) 이면: 평활 없이 1 − 0/0.04 = 1.0000, "
          f"+1 평활이면 {dice_loss(torch.logit(torch.full((1, 4), 0.01)), empty, 1):.4f}")

    print("[손계산 4] 작은 객체와 큰 객체: 24×24 = 576 픽셀, 모든 픽셀에 p = 0.01 (전부 배경이라고 답한 예측)")
    for area in (9, 288):
        label = torch.zeros(1, 576)
        label[0, :area] = 1.0
        logit = torch.logit(torch.full((1, 576), 0.01))
        print(f"  객체 {area:3d} 픽셀 ({area / 576:.1%}): BCE = {sigmoid_ce_loss(logit, label, 1):.4f}, "
              f"다이스 손실 = {dice_loss(logit, label, 1):.4f}")
    print(f"  −log 0.01 = {-np.log(0.01):.4f}, −log 0.99 = {-np.log(0.99):.5f}")

    print("[손계산 5] 깊이별 분리 합성곱의 매개변수 수 (C = 128, 3×3)")
    dim = 128
    full = nn.Conv2d(dim, dim, 3, padding=1)
    block = DepthwiseConvBlock(dim)
    count = lambda m: sum(p.numel() for p in m.parameters())
    print(f"  보통의 3×3 합성곱: {dim}·{dim}·9 + {dim} = {count(full):,}")
    print(f"  깊이별 3×3: {dim}·9 + {dim} = {count(block.dwconv):,}, 1×1(점별): {dim}·{dim} + {dim} = {count(block.pwconv1):,}, "
          f"합 {count(block.dwconv) + count(block.pwconv1):,} ({count(full) / (count(block.dwconv) + count(block.pwconv1)):.1f}배 적다)")
    print(f"  DepthwiseConvBlock 전체 (층 정규화 {count(block.norm)} 포함): {count(block):,}")
    for name, d, layers in (("미니 (D = 128, 블록 3개)", 128, 3), ("RF-DETR-Seg Nano (D = 256, 블록 4개)", 256, 4)):
        head = MiniSegHead(d, layers)
        parts = [count(head.blocks), count(head.spatial_features_proj), count(head.query_features_block),
                 count(head.query_features_proj), 1]
        print(f"  분할 머리 {name}: 블록 {parts[0]:,} + 1×1 합성곱 {parts[1]:,} + 질의 MLP {parts[2]:,} "
              f"+ 질의 Linear {parts[3]:,} + 편향 1 = {count(head):,}")

    print("[손계산 6] 점 표본 추출의 점 수 (mask_point_sample_ratio = 16)")
    for name, size in (("미니, 마스크 24×24", 24), ("Seg Nano, 마스크 78×78", 78), ("Seg 2XLarge, 마스크 192×192", 192)):
        points = max(size, size * size // 16)
        print(f"  {name}: 손실 max({size}, {size * size} // 16) = {points}개 (불확실한 점 {int(0.75 * points)} + 균등 "
              f"{points - int(0.75 * points)}, 후보 {3 * points}), 매칭 비용 {size * size // 16}개")


def checks(device):
    """직접 구현한 것을 PyTorch 내장 · 공식 구현과 대조한다."""
    print("[check]")
    torch.manual_seed(0)
    # (1) 점 읽기: 모든 픽셀 중심에서 읽으면 F.interpolate 로 키운 것과 같다
    low = torch.randn(3, 1, 24, 24)
    points = pixel_center_points(96, 96, "cpu")[None].expand(3, -1, -1)
    read = point_sample(low, points).view(3, 1, 96, 96)
    up = F.interpolate(low, size=(96, 96), mode="bilinear", align_corners=False)
    print(f"  point_sample(픽셀 중심 전부) vs F.interpolate(쌍선형): 최대 차이 {(read - up).abs().max():.2e}")
    mask = torch.rand(3, 1, 96, 96) > 0.5
    same = point_sample(mask.float(), points, mode="nearest").view(3, 1, 96, 96)
    print(f"  point_sample(nearest, 픽셀 중심 전부) 이 원래 마스크와 같은가: {bool((same == mask.float()).all())}")
    # (2) 쌍별 비용 = 쌍마다 손실 함수를 부른 것
    logits, labels = torch.randn(5, 36), (torch.rand(4, 36) > 0.6).float()
    ce = torch.tensor([[sigmoid_ce_loss(logits[i:i + 1], labels[j:j + 1], 1) for j in range(4)] for i in range(5)])
    dc = torch.tensor([[dice_loss(logits[i:i + 1], labels[j:j + 1], 1) for j in range(4)] for i in range(5)])
    print(f"  pairwise_sigmoid_ce / pairwise_dice vs 쌍마다 따로 계산: 최대 차이 "
          f"{(pairwise_sigmoid_ce(logits, labels) - ce).abs().max():.2e} / {(pairwise_dice(logits, labels) - dc).abs().max():.2e}")
    # (3) 다이스 = 2·IoU / (1 + IoU) (0/1 마스크에서)
    a, b = torch.rand(200, 96, 96) > 0.5, torch.rand(200, 96, 96) > 0.7
    iou = torch.stack([mask_iou(a[i:i + 1], b[i:i + 1])[0, 0] for i in range(200)])
    dice = 2 * (a & b).flatten(1).sum(1) / (a.flatten(1).sum(1) + b.flatten(1).sum(1))
    print(f"  무작위 마스크 200쌍에서 |다이스 − 2·IoU/(1 + IoU)| 의 최댓값: {(dice - 2 * iou / (1 + iou)).abs().max():.2e}")
    # (4) 채점 틀: 박스 IoU 를 끼우면 3장 evaluate_ap 와 같다
    rng = np.random.default_rng(0)
    data = ShapesDataset(60, seed=5, with_masks=True)
    predictions = []
    for target in data.targets:
        n = len(target["labels"])
        boxes = torch.cat([target["boxes"] + torch.from_numpy(rng.normal(0, 0.03, (n, 4))).float(),
                           torch.from_numpy(rng.uniform(0.2, 0.8, (2, 4))).float()])
        labels = torch.cat([target["labels"], torch.from_numpy(rng.integers(0, 3, 2))])
        predictions.append({"boxes": boxes, "scores": torch.from_numpy(rng.uniform(0, 1, n + 2)).float(), "labels": labels})
    ours, reference = evaluate_box_ap(predictions, data.targets), evaluate_ap(predictions, data.targets, NUM_CLASSES)
    print(f"  evaluate_ap_with(박스 IoU) vs ch03 evaluate_ap: AP {ours['AP']:.6f} vs {reference['AP']:.6f}, "
          f"표의 최대 차이 {np.abs(ours['table'] - reference['table']).max():.2e}")
    perfect = [{"boxes": t["boxes"], "scores": torch.ones(len(t["labels"])), "labels": t["labels"], "masks": t["masks"]}
               for t in data.targets]
    print(f"  정답 마스크를 그대로 예측으로 넣은 마스크 AP: {evaluate_mask_ap(perfect, data.targets)['AP']:.4f}")
    # (5) 모델: 추론 출력 = 학습 출력의 마지막 층, 층을 뗀 출력 = 보조 출력
    model = MiniRFDETRSeg().to(device).eval()
    images = data.images[:4].to(device).float() / 255.0
    with torch.no_grad():
        full = model(images, all_layer_masks=True)
        last = model(images)
        diffs = [(model(images, dec_layers=k)["pred_masks"] - full["aux_outputs"][k - 1]["pred_masks"]).abs().max()
                 for k in (1, 2)]
        zero = (model(images, dec_layers=0)["pred_masks"] - full["enc_outputs"]["pred_masks"]).abs().max()
    print(f"  모양: pred_masks {tuple(last['pred_masks'].shape)}, 보조 출력 {[tuple(a['pred_masks'].shape) for a in full['aux_outputs']]}, "
          f"인코더 제안 {tuple(full['enc_outputs']['pred_masks'].shape)}")
    print(f"  final_layer_only 의 마스크 = 전 층 계산의 마지막 층: 최대 차이 {(last['pred_masks'] - full['pred_masks']).abs().max():.2e}")
    print(f"  dec_layers=1 / 2 의 마스크 = 보조 출력 0 / 1: 최대 차이 {diffs[0]:.2e} / {diffs[1]:.2e}, "
          f"dec_layers=0 = 인코더 제안의 마스크: {zero:.2e}")


def official_checks():
    """공식 구현(rfdetr 패키지)과 수치 대조. 패키지가 없으면 건너뛴다.

    rfdetr 를 불러오면 PyTorch 의 전역 연산 설정이 바뀌어 같은 모델의 AP 가 소수 넷째 자리에서 달라질 수 있으므로,
    본 실험이 끝난 뒤에 부른다.
    """
    print("[check: 공식 구현과 대조]")
    low = torch.randn(3, 1, 24, 24)
    mask = torch.rand(3, 1, 96, 96) > 0.5
    try:
        import logging
        import warnings
        warnings.filterwarnings("ignore")
        logging.disable(logging.WARNING)
        from rfdetr.models import criterion as official_criterion
        from rfdetr.models.heads.segmentation import SegmentationHead
        from rfdetr.models.heads.segmentation import point_sample as official_point_sample
        from rfdetr.utilities.box_ops import batch_dice_loss, batch_sigmoid_ce_loss
        logging.disable(logging.NOTSET)
    except ImportError:
        print("  (rfdetr 패키지가 없어 공식 구현과의 대조는 건너뜀)")
        return
    torch.manual_seed(1)
    mine, official = MiniSegHead(128, 3).eval(), SegmentationHead(128, 3, downsample_ratio=4).eval()
    official.load_state_dict(mine.state_dict())  # 이름 · 모양이 같아 그대로 실린다
    with torch.no_grad():
        nn.init.normal_(mine.bias, std=0.5)
        official.bias.copy_(mine.bias)
        spatial, queries = torch.randn(2, 128, 12, 12), [torch.randn(2, 12, 128) for _ in range(3)]
        out_mine, out_official = mine(spatial, queries, (96, 96)), official(spatial, queries, (96, 96))
        diff = max((a - b).abs().max() for a, b in zip(out_mine, out_official))
        diff_last = (mine(spatial, queries, (96, 96), final_layer_only=True)[0] - out_official[-1]).abs().max()
        diff_enc = (mine(spatial, queries[:1], (96, 96), skip_blocks=True)[0]
                    - official(spatial, queries[:1], (96, 96), skip_blocks=True)[0]).abs().max()
    print(f"  MiniSegHead vs 공식 SegmentationHead (같은 가중치): 층별 마스크 로짓 {[tuple(o.shape) for o in out_mine]}, "
          f"최대 차이 {diff:.2e} (마지막 층만 {diff_last:.2e}, skip_blocks {diff_enc:.2e})")
    logits, labels = torch.randn(7, 36), (torch.rand(7, 36) > 0.6).float()
    print(f"  sigmoid_ce_loss / dice_loss vs 공식: 최대 차이 "
          f"{abs(float(sigmoid_ce_loss(logits, labels, 3.0) - official_criterion.sigmoid_ce_loss(logits, labels, 3.0))):.2e} / "
          f"{abs(float(dice_loss(logits, labels, 3.0) - official_criterion.dice_loss(logits, labels, 3.0))):.2e}")
    print(f"  pairwise_sigmoid_ce / pairwise_dice vs 공식 batch_*: 최대 차이 "
          f"{(pairwise_sigmoid_ce(logits, labels) - batch_sigmoid_ce_loss(logits, labels)).abs().max():.2e} / "
          f"{(pairwise_dice(logits, labels) - batch_dice_loss(logits, labels)).abs().max():.2e}")
    coords = torch.rand(3, 50, 2)
    print(f"  point_sample vs 공식 point_sample: 쌍선형 {(point_sample(low, coords) - official_point_sample(low, coords, align_corners=False)).abs().max():.2e}, "
          f"nearest {(point_sample(mask.float(), coords, mode='nearest') - official_point_sample(mask.float(), coords, align_corners=False, mode='nearest')).abs().max():.2e}")


def seg_nano_trace():
    """설치된 rfdetr 의 RF-DETR-Seg Nano 를 (가중치 없이) 만들어 312×312 입력의 모양과 매개변수 수를 잰다."""
    try:
        import logging
        import warnings
        warnings.filterwarnings("ignore")
        logging.disable(logging.WARNING)
        from rfdetr import RFDETRSegNano
        wrapper = RFDETRSegNano(pretrain_weights=None, device="cpu")
        logging.disable(logging.NOTSET)
    except Exception as error:  # 패키지가 없거나 백본을 내려받지 못한 경우
        print(f"[RF-DETR-Seg Nano 모양 추적] 건너뜀 ({type(error).__name__})")
        return
    core, args = wrapper.model.model.eval(), wrapper.model.args
    head = core.segmentation_head
    print(f"[RF-DETR-Seg Nano 모양 추적] 설정: resolution {args.resolution}, patch_size {args.patch_size}, "
          f"num_windows {args.num_windows}, dec_layers {args.dec_layers}, num_queries {args.num_queries}, "
          f"hidden_dim {args.hidden_dim}, mask_downsample_ratio {args.mask_downsample_ratio} (학습된 가중치는 싣지 않았다)")
    records = {}

    def watch(name, module):
        def hook(_module, inputs, output):
            records.setdefault(name, []).append((tuple(inputs[0].shape) if torch.is_tensor(inputs[0]) else None,
                                                 tuple(output.shape) if torch.is_tensor(output) else
                                                 [tuple(o.shape) for o in output]))
        module.register_forward_hook(hook)

    watch("projector", core.backbone[0].projector)
    for i, block in enumerate(head.blocks):
        watch(f"block{i}", block)
    watch("spatial_proj", head.spatial_features_proj)
    watch("query_block", head.query_features_block)
    watch("query_proj", head.query_features_proj)
    with torch.no_grad():
        out = core(torch.rand(1, 3, args.resolution, args.resolution))
    rows = [("그림", (1, 3, args.resolution, args.resolution)),
            ("프로젝터 출력", records["projector"][0][1][0]),
            ("쌍선형 보간 뒤 = 블록 1 의 입력", records["block0"][0][0]),
            (f"블록 1 … {len(head.blocks)} 의 출력 (각각)", records[f"block{len(head.blocks) - 1}"][0][1]),
            (f"1×1 합성곱 → 픽셀 임베딩 맵 (추론 때 {len(records['spatial_proj'])}번 계산)", records["spatial_proj"][0][1]),
            ("질의 임베딩 → MLPBlock → Linear", records["query_proj"][0][1]),
            ("pred_masks (마스크 로짓)", tuple(out["pred_masks"].shape)),
            ("pred_logits / pred_boxes", (tuple(out["pred_logits"].shape), tuple(out["pred_boxes"].shape)))]
    for name, shape in rows:
        print(f"  {name:48s} {shape}")
    print(f"  추론 모드의 보조 출력 키: {sorted(out['aux_outputs'][0].keys())} × {len(out['aux_outputs'])} (마스크는 마지막 층만 계산)")
    total = sum(p.numel() for p in core.parameters())
    seg = sum(p.numel() for p in head.parameters())
    print(f"  매개변수: 전체 {total:,}개, 그 가운데 분할 머리 {seg:,}개 ({seg / total:.1%})")


# ── 6. 분석 ──────────────────────────────────────────────────────────────────


def box_to_mask(box, size: int):
    """정규화 (cx, cy, w, h) 박스 안에 중심이 놓인 픽셀을 True 로 한 (size, size) 마스크."""
    cx, cy, w, h = [float(v) for v in box]
    coords = (torch.arange(size, dtype=torch.float32) + 0.5) / size
    inside_x = (coords >= cx - w / 2) & (coords <= cx + w / 2)
    inside_y = (coords >= cy - h / 2) & (coords <= cy + h / 2)
    return inside_y[:, None] & inside_x[None, :]


def object_table(predictions, dataset, score_threshold: float = 0.5):
    """정답 객체마다: 같은 클래스 · 점수 ≥ 문턱값인 예측 가운데 마스크 IoU 가 가장 큰 것을 그 객체의 예측으로 본다.

    그런 예측이 없거나 하나도 겹치지 않으면 "못 찾은 객체" 로 치고 IoU 를 0 으로 둔다.

    돌려주는 값: 사전의 목록 (객체마다) — 클래스, 보이는 넓이(픽셀), 가려졌는지, 마스크 IoU, 박스 IoU,
    "박스를 마스크로 쓴 것" 의 IoU (정답 박스 / 예측 박스), 그림 번호 · 객체 번호 · 예측 번호.
    """
    size = dataset.size
    rows = []
    for i, (pred, target) in enumerate(zip(predictions, dataset.targets)):
        strong = pred["scores"] >= score_threshold
        for j in range(len(target["labels"])):
            cls = int(target["labels"][j])
            gt = target["masks"][j]
            full = torch.from_numpy(shape_mask(cls, dataset.scenes[i][j]["box"], size))
            row = {"image": i, "object": j, "cls": cls, "area": int(gt.sum()), "occluded": bool(gt.sum() < full.sum()),
                   "visible": float(gt.sum() / full.sum()),
                   "gt_box_as_mask": float(mask_iou(box_to_mask(target["boxes"][j], size)[None], gt[None])),
                   "found": False, "mask_iou": 0.0, "box_iou": 0.0, "pred_box_as_mask": 0.0, "pred": -1}
            candidates = torch.nonzero(strong & (pred["labels"] == cls))[:, 0]
            ious = mask_iou(pred["masks"][candidates], gt[None])[:, 0] if len(candidates) else torch.zeros(0)
            if len(ious) and ious.max() > 0:  # 겹치는 예측이 하나도 없으면 "못 찾은 객체"
                k = int(candidates[ious.argmax()])
                row.update(found=True, mask_iou=float(ious.max()), pred=k,
                           box_iou=float(paired_box_iou(box_cxcywh_to_xyxy(pred["boxes"][k:k + 1]),
                                                        box_cxcywh_to_xyxy(target["boxes"][j:j + 1]))),
                           pred_box_as_mask=float(mask_iou(box_to_mask(pred["boxes"][k], size)[None], gt[None])))
            rows.append(row)
    return rows


def resolution_ceiling(dataset, ratio: int):
    """정답 마스크를 1/ratio 해상도로 줄였다가(넓이 평균) 쌍선형으로 되키워 0.5 에서 자른 것과 원래 마스크의 IoU.

    "마스크를 1/ratio 해상도로만 그릴 수 있을 때 얼마나 잘할 수 있는가" 의 기준선이다. 돌려주는 값: 객체마다의 IoU.
    """
    size = dataset.size
    values = []
    for target in dataset.targets:
        gt = target["masks"].float()[:, None]
        low = F.interpolate(gt, size=(size // ratio, size // ratio), mode="area")
        back = F.interpolate(low, size=(size, size), mode="bilinear", align_corners=False) > 0.5
        values.extend(float(mask_iou(back[k], target["masks"][k:k + 1])) for k in range(len(gt)))
    return np.array(values)


def report_objects(rows, ceiling4, ceiling2):
    """객체 표를 클래스 · 크기 · 가림으로 나눠 평균을 낸다."""
    get = lambda key, subset: np.mean([r[key] for r in subset]) if subset else float("nan")
    found = [r for r in rows if r["found"]]
    print(f"[객체별 분석] 정답 객체 {len(rows)}개 가운데 점수 ≥ 0.5 · 같은 클래스 · 겹치는 예측이 있는 것 {len(found)}개. "
          f"마스크 IoU 평균 {get('mask_iou', rows):.4f} (찾은 것만 {get('mask_iou', found):.4f}), "
          f"박스 IoU 평균 {get('box_iou', rows):.4f}")
    print("  클래스      | 객체 수 | 정답 박스를 마스크로 | 예측 박스를 마스크로 | 예측 마스크 | 박스 IoU | 1/4 기준선 | 1/2 기준선")
    index = {id(r): n for n, r in enumerate(rows)}
    summary = {}
    for cls, name in enumerate(CLASS_NAMES):
        subset = [r for r in rows if r["cls"] == cls]
        c4 = np.mean([ceiling4[index[id(r)]] for r in subset])
        c2 = np.mean([ceiling2[index[id(r)]] for r in subset])
        summary[name] = [get("gt_box_as_mask", subset), get("pred_box_as_mask", subset), get("mask_iou", subset), c4]
        print(f"  {name:11s} | {len(subset):7d} | {summary[name][0]:20.4f} | {summary[name][1]:20.4f} | "
              f"{summary[name][2]:11.4f} | {get('box_iou', subset):8.4f} | {c4:10.4f} | {c2:10.4f}")
    print("  보이는 넓이(픽셀) | 객체 수 | 예측 마스크 IoU | 박스 IoU | 1/4 기준선 | 1/2 기준선")
    for low, high in ((0, 300), (300, 700), (700, 10**6)):
        subset = [r for r in rows if low <= r["area"] < high]
        c4 = np.mean([ceiling4[index[id(r)]] for r in subset])
        c2 = np.mean([ceiling2[index[id(r)]] for r in subset])
        label = f"{low} – {high}" if high < 10**6 else f"{low} 이상"
        print(f"  {label:17s} | {len(subset):7d} | {get('mask_iou', subset):15.4f} | {get('box_iou', subset):8.4f} | "
              f"{c4:10.4f} | {c2:10.4f}")
    print("  가림 (보이는 비율)            | 객체 수 | 예측 마스크 IoU | 박스 IoU | 정답 박스를 마스크로 | 예측 박스를 마스크로")
    for label, subset in (("가려지지 않음 (1.0)", [r for r in rows if not r["occluded"]]),
                          ("조금 가려짐 (0.9 이상)", [r for r in rows if r["occluded"] and r["visible"] >= 0.9]),
                          ("많이 가려짐 (0.9 미만)", [r for r in rows if r["visible"] < 0.9])):
        print(f"  {label:22s} | {len(subset):7d} | {get('mask_iou', subset):15.4f} | {get('box_iou', subset):8.4f} | "
              f"{get('gt_box_as_mask', subset):20.4f} | {get('pred_box_as_mask', subset):20.4f}")
    occluded = [r for r in rows if r["occluded"]]
    if occluded:
        print(f"  가려진 객체 {len(occluded)}개의 보이는 비율: 평균 {np.mean([r['visible'] for r in occluded]):.3f}, "
              f"최소 {np.min([r['visible'] for r in occluded]):.3f}")
    return summary


@torch.no_grad()
def forward_time(model, images, repeats: int, **kwargs):
    """추론 순전파 시간 (그림 한 장당 ms). repeats 번 가운데 최솟값."""
    model.eval()
    best = float("inf")
    for _ in range(repeats):
        if images.is_cuda:
            torch.cuda.synchronize()
        start = time.perf_counter()
        model(images, **kwargs)
        if images.is_cuda:
            torch.cuda.synchronize()
        best = min(best, time.perf_counter() - start)
    return best / len(images) * 1000


# ── 7. 그림 ──────────────────────────────────────────────────────────────────


def to_rgb(color: str):
    import matplotlib.colors as mcolors
    return np.array(mcolors.to_rgb(color), dtype=np.float32)


def instance_map(masks, size: int, order=None):
    """마스크 (n, H, W) 를 인스턴스마다 다른 색으로 칠한 (H, W, 3) 그림 (검은 바탕). order 순서로 덧칠한다."""
    canvas = np.zeros((size, size, 3), dtype=np.float32)
    for k in (range(len(masks)) if order is None else order):
        canvas[np.asarray(masks[k])] = to_rgb(INSTANCE_COLORS[k % len(INSTANCE_COLORS)])
    return canvas


def show_instances(ax, masks, size, boxes=None, order=None, title=None):
    import matplotlib.patches as patches
    ax.imshow(instance_map(masks, size, order), interpolation="nearest")
    ax.set_xticks([])
    ax.set_yticks([])
    if boxes is not None:
        for k, (cx, cy, w, h) in enumerate(np.asarray(boxes, dtype=np.float32).reshape(-1, 4)):
            ax.add_patch(patches.Rectangle(((cx - w / 2) * size - 0.5, (cy - h / 2) * size - 0.5), w * size, h * size,
                                           fill=False, linestyle="--", linewidth=1.2,
                                           edgecolor=INSTANCE_COLORS[k % len(INSTANCE_COLORS)]))
    if title:
        ax.set_title(title, fontsize=8)


def plot_box_vs_mask(dataset, rows, path, count: int = 4):
    """정답만: 박스(점선)와 마스크(색). 가려진 객체가 있는 그림을 고른다."""
    import matplotlib.pyplot as plt

    chosen = []
    for r in sorted((r for r in rows if r["occluded"]), key=lambda r: r["visible"]):  # 많이 가려진 객체가 있는 그림부터
        if r["image"] not in chosen:
            chosen.append(r["image"])
    chosen = (chosen + [i for i in range(len(dataset)) if i not in chosen])[:count]
    import matplotlib.patches as patches

    size = dataset.size
    fig, axes = plt.subplots(2, count, figsize=(count * 2.7, 6.1))
    for column, i in enumerate(chosen):
        image, target = dataset[i]
        draw_boxes(axes[0, column], image)
        for k, (cx, cy, w, h) in enumerate(target["boxes"].numpy()):
            axes[0, column].add_patch(patches.Rectangle(((cx - w / 2) * size - 0.5, (cy - h / 2) * size - 0.5), w * size,
                                                        h * size, fill=False, linestyle="--", linewidth=1.4,
                                                        edgecolor=INSTANCE_COLORS[k % len(INSTANCE_COLORS)]))
        axes[0, column].set_title(f"val #{i}: image + ground-truth boxes", fontsize=8)
        text = ", ".join(f"{r['gt_box_as_mask']:.2f}" for r in rows if r["image"] == i)
        show_instances(axes[1, column], target["masks"].numpy(), size, target["boxes"].numpy(),
                       title=f"IoU(box, mask): {text}")
    fig.suptitle("ground truth: boxes (dashed) on the image (top) and visible masks (bottom). "
                 "Occluded objects lose the hidden pixels", fontsize=10)
    fig.tight_layout()
    fig.subplots_adjust(hspace=0.16)
    fig.savefig(path, dpi=120)
    plt.close(fig)


def plot_curves(history, path):
    import matplotlib.pyplot as plt

    fig, axes = plt.subplots(1, 2, figsize=(11, 3.9))
    epochs = history["epoch"][1:]
    for key, label, style in (("loss_maskce", "mask BCE (last layer)", "-o"), ("loss_maskdice", "mask Dice (last layer)", "-s"),
                              ("loss_ce", "class IA-BCE", "--^"), ("loss_giou", "box GIoU", ":v")):
        axes[0].plot(epochs, history[key], style, markersize=4, label=label)
    axes[0].set_xlabel("epoch")
    axes[0].set_ylabel("training loss (before weighting)")
    axes[0].set_yscale("log")
    axes[0].legend(fontsize=8)
    axes[0].grid(alpha=0.3)
    axes[0].set_title("training losses", fontsize=10)
    axes[1].plot(history["epoch"], history["box_AP"], "-o", markersize=4, color="#0072B2", label="box AP (EMA)")
    axes[1].plot(history["epoch"], history["mask_AP"], "-s", markersize=4, color="#D55E00", label="mask AP (EMA)")
    axes[1].plot(history["epoch"], history["mask_AP50"], "--", color="#E69F00", label="mask AP50")
    axes[1].plot(history["epoch"], history["mask_AP75"], ":", color="#CC79A7", label="mask AP75")
    axes[1].axhline(history["box_AP"][0], color="gray", linewidth=0.8, linestyle="-.", label="box AP before (ch11)")
    axes[1].set_xlabel("epoch (0 = before fine-tuning)")
    axes[1].set_ylabel("validation AP")
    axes[1].set_ylim(0, 1.02)
    axes[1].legend(fontsize=8, loc="lower right")
    axes[1].grid(alpha=0.3)
    axes[1].set_title("validation AP of the EMA model", fontsize=10)
    fig.tight_layout()
    fig.savefig(path, dpi=120)
    plt.close(fig)


def plot_predictions(dataset, predictions, path, indices, score_threshold: float = 0.5):
    """위: 그림, 가운데: 정답 마스크, 아래: 예측 마스크 (점수 ≥ 문턱값, 점수가 높은 것이 위에 칠해진다) + 예측 박스."""
    import matplotlib.pyplot as plt

    fig, axes = plt.subplots(3, len(indices), figsize=(len(indices) * 2.3, 7.7))
    for column, i in enumerate(indices):
        image, target = dataset[i]
        pred = predictions[i]
        keep = torch.nonzero(pred["scores"] >= score_threshold)[:, 0]
        keep = keep[torch.argsort(pred["scores"][keep])]  # 점수 오름차순 → 높은 점수가 나중에(위에) 칠해진다
        draw_boxes(axes[0, column], image)
        axes[0, column].set_title(f"val #{i}", fontsize=8)
        show_instances(axes[1, column], target["masks"].numpy(), dataset.size, title=f"ground truth: {len(target['labels'])}")
        iou = mask_iou(pred["masks"][keep], target["masks"]) if len(keep) else torch.zeros(0, len(target["labels"]))
        best = iou.max(0).values.mean() if len(keep) else 0.0
        show_instances(axes[2, column], pred["masks"][keep].numpy(), dataset.size, pred["boxes"][keep].numpy(),
                       title=f"predicted: {len(keep)}, mean mask IoU {float(best):.2f}")
    fig.suptitle(f"top: image, middle: ground-truth masks, bottom: predicted masks (score >= {score_threshold}) and boxes (dashed)",
                 fontsize=10)
    fig.tight_layout(h_pad=1.2)
    fig.savefig(path, dpi=120)
    plt.close(fig)


@torch.no_grad()
def plot_dot_product(model, dataset, index, path, device, score_threshold: float = 0.5):
    """질의 하나하나의 내적 지도(시그모이드 전의 로짓, 24×24)와 그것을 키워 0 에서 자른 마스크."""
    import matplotlib.pyplot as plt

    model.eval()
    image, target = dataset[index]
    out = model(image[None].to(device))
    prob = out["pred_logits"][0].sigmoid().cpu()  # (Q, K)
    scores, labels = prob.max(-1)
    order = torch.argsort(scores, descending=True)
    strong = [int(q) for q in order if scores[q] >= score_threshold][:4]
    chosen = strong + [int(order[-1])]  # 점수가 가장 낮은 질의 하나도 함께
    logits = out["pred_masks"][0].cpu()  # (Q, h, w)
    limit = float(logits[chosen].abs().max())
    fig, axes = plt.subplots(2, len(chosen) + 1, figsize=((len(chosen) + 1) * 2.35, 5.4), layout="constrained")
    draw_boxes(axes[0, 0], image)
    axes[0, 0].set_title(f"val #{index}: image", fontsize=8)
    show_instances(axes[1, 0], target["masks"].numpy(), dataset.size, title="ground-truth masks")
    for column, q in enumerate(chosen, start=1):
        shown = axes[0, column].imshow(logits[q].numpy(), cmap="RdBu_r", vmin=-limit, vmax=limit, interpolation="nearest")
        axes[0, column].contour(logits[q].numpy(), levels=[0.0], colors="black", linewidths=1.0)
        axes[0, column].set_xticks([])
        axes[0, column].set_yticks([])
        axes[0, column].set_title(f"query {q}: {CLASS_NAMES[int(labels[q])]} {float(scores[q]):.2f}\n"
                                  f"logit min {float(logits[q].min()):.1f}, max {float(logits[q].max()):.1f}", fontsize=7.5)
        up = F.interpolate(logits[q][None, None], size=(dataset.size, dataset.size), mode="bilinear", align_corners=False)[0, 0]
        draw_boxes(axes[1, column], image)
        axes[1, column].contour((up > 0).numpy().astype(float), levels=[0.5], colors="#39ff14", linewidths=1.6)
        iou = mask_iou((up > 0)[None], target["masks"])[0]
        axes[1, column].set_title(f"logit > 0 after resizing (green)\nbest mask IoU {float(iou.max()):.2f}", fontsize=7.5)
    fig.colorbar(shown, ax=axes[0, :].tolist(), shrink=0.85, pad=0.01, label="mask logit")
    fig.suptitle(f"top: dot product of one query embedding with every pixel embedding ({logits.shape[-1]}x{logits.shape[-2]}, "
                 "black line = 0). bottom: the resulting mask", fontsize=10)
    fig.savefig(path, dpi=120)
    plt.close(fig)


@torch.no_grad()
def pixel_embedding_maps(model, images, device):
    """그림들의 (마지막 블록까지 거친) 픽셀 임베딩 맵 (n, D, h, w) 을 CPU 로."""
    model.eval()
    out = model(images.to(device), return_features=True)
    return model.segmentation_head.pixel_embeddings(out["features"]["projector"][0], images.shape[-2:])[-1].cpu()


def plot_pixel_embedding(model, dataset, indices, path, device):
    """픽셀 임베딩 맵의 주성분 3개를 RGB 로. 같은 색 = 비슷한 임베딩. 돌려주는 값: 주성분의 분산 비율."""
    import matplotlib.pyplot as plt

    images = torch.stack([dataset[i][0] for i in indices])
    embed = pixel_embedding_maps(model, images, device)  # (n, D, h, w)
    n, dim, height, width = embed.shape
    flat = embed.permute(0, 2, 3, 1).reshape(-1, dim)
    centered = flat - flat.mean(0)
    _, singular, basis = torch.linalg.svd(centered, full_matrices=False)
    ratio = (singular**2 / (singular**2).sum()).numpy()
    projected = (centered @ basis[:3].T).reshape(n, height, width, 3)
    low, high = projected.reshape(-1, 3).quantile(0.01, dim=0), projected.reshape(-1, 3).quantile(0.99, dim=0)
    colors = ((projected - low) / (high - low)).clamp(0, 1).numpy()
    fig, axes = plt.subplots(2, n, figsize=(n * 2.5, 5.4))
    for column, i in enumerate(indices):
        draw_boxes(axes[0, column], dataset[i][0])
        axes[0, column].set_title(f"val #{i}", fontsize=8)
        axes[1, column].imshow(colors[column], interpolation="nearest")
        axes[1, column].set_xticks([])
        axes[1, column].set_yticks([])
        axes[1, column].set_xlabel(f"pixel embedding {height}x{width}, PCA -> RGB", fontsize=8)
    fig.suptitle(f"pixel embedding map ({dim} channels) projected on its first 3 principal components "
                 f"({ratio[0]:.0%}, {ratio[1]:.0%}, {ratio[2]:.0%} of variance)", fontsize=10)
    fig.tight_layout(h_pad=1.2)
    fig.savefig(path, dpi=120)
    plt.close(fig)
    return ratio


def plot_prototypes(model, dataset, indices, path, device, channels: int = 8):
    """픽셀 임베딩 맵의 채널 몇 장을 그대로 본다 ("프로토타입"). 분산이 큰 채널부터."""
    import matplotlib.pyplot as plt

    images = torch.stack([dataset[i][0] for i in indices])
    embed = pixel_embedding_maps(model, images, device)
    variance = embed.permute(1, 0, 2, 3).flatten(1).var(dim=1)
    top = torch.argsort(variance, descending=True)[:channels]
    fig, axes = plt.subplots(len(indices), channels + 1, figsize=((channels + 1) * 1.55, len(indices) * 1.75))
    for row, i in enumerate(indices):
        draw_boxes(axes[row, 0], dataset[i][0])
        axes[row, 0].set_ylabel(f"val #{i}", fontsize=8)
        for column, channel in enumerate(top, start=1):
            values = embed[row, channel].numpy()
            limit = float(embed[:, channel].abs().max())
            axes[row, column].imshow(values, cmap="RdBu_r", vmin=-limit, vmax=limit, interpolation="nearest")
            axes[row, column].set_xticks([])
            axes[row, column].set_yticks([])
            if row == 0:
                axes[row, column].set_title(f"channel {int(channel)}", fontsize=7)
    fig.suptitle(f"{channels} highest-variance channels of the pixel embedding map (red = positive, blue = negative)", fontsize=10)
    fig.tight_layout(h_pad=1.0)
    fig.savefig(path, dpi=120)
    plt.close(fig)
    return [int(c) for c in top]


def plot_layers(layer_rows, layer_predictions, dataset, index, path, score_threshold: float = 0.5):
    """왼쪽: 디코더 층 수별 박스 AP · 마스크 AP. 오른쪽: 같은 그림의 층 수별 예측 마스크."""
    import matplotlib.pyplot as plt

    count = len(layer_rows)
    fig = plt.figure(figsize=(4.6 + count * 2.2, 3.5))
    grid = fig.add_gridspec(1, count + 2, width_ratios=[2.2] + [1] * (count + 1))
    ax = fig.add_subplot(grid[0, 0])
    layers = [r[0] for r in layer_rows]
    ax.plot(layers, [r[1] for r in layer_rows], "-o", color="#0072B2", label="box AP")
    ax.plot(layers, [r[2] for r in layer_rows], "-s", color="#D55E00", label="mask AP")
    ax.plot(layers, [r[4] for r in layer_rows], "--^", color="#009E73", label="mean mask IoU")
    ax.set_xticks(layers)
    ax.set_xlabel("decoder layers kept (= seg-head blocks used)")
    ax.set_ylabel("validation metric")
    ax.set_ylim(0, 1.02)
    ax.grid(alpha=0.3)
    ax.legend(fontsize=8, loc="lower right")
    image, target = dataset[index]
    ax = fig.add_subplot(grid[0, 1])
    show_instances(ax, target["masks"].numpy(), dataset.size, title=f"val #{index}: ground truth")
    for column, (k, predictions) in enumerate(zip(layers, layer_predictions)):
        pred = predictions[index]
        keep = torch.nonzero(pred["scores"] >= score_threshold)[:, 0]
        keep = keep[torch.argsort(pred["scores"][keep])]
        ax = fig.add_subplot(grid[0, column + 2])
        show_instances(ax, pred["masks"][keep].numpy(), dataset.size, title=f"{k} layer(s): {len(keep)} masks")
    fig.tight_layout()
    fig.savefig(path, dpi=120)
    plt.close(fig)


def plot_iou_by_class(summary, path):
    import matplotlib.pyplot as plt

    labels = ["GT box used as mask", "predicted box used as mask", "predicted mask", "GT mask at 1/4 resolution"]
    colors = ["#BBBBBB", "#56B4E9", "#D55E00", "#009E73"]
    hatches = ["", "//", "", ".."]
    fig, ax = plt.subplots(figsize=(7.6, 3.8))
    width = 0.2
    for k, (label, color, hatch) in enumerate(zip(labels, colors, hatches)):
        values = [summary[name][k] for name in CLASS_NAMES]
        bars = ax.bar(np.arange(len(CLASS_NAMES)) + (k - 1.5) * width, values, width, label=label, color=color,
                      hatch=hatch, edgecolor="black", linewidth=0.5)
        for bar, value in zip(bars, values):
            ax.text(bar.get_x() + bar.get_width() / 2, value + 0.01, f"{value:.2f}", ha="center", fontsize=7)
    ax.set_xticks(np.arange(len(CLASS_NAMES)))
    ax.set_xticklabels(CLASS_NAMES)
    ax.set_ylabel("mean IoU with the ground-truth mask")
    ax.set_ylim(0, 1.3)
    ax.set_yticks(np.arange(0, 1.01, 0.2))
    ax.legend(fontsize=8, ncol=2, loc="upper center")
    ax.grid(axis="y", alpha=0.3)
    fig.tight_layout()
    fig.savefig(path, dpi=120)
    plt.close(fig)


def plot_overlap(dataset, predictions, rows, path, count: int = 4, score_threshold: float = 0.5):
    """많이 가려진 객체(보이는 비율 0.9 미만) 가운데 마스크 IoU 가 가장 높은 것(위)과 가장 낮은 것(아래).

    흰 점선 = 그 객체의 정답 마스크, 초록 실선 = 그 그림의 모든 예측 마스크 (점수 ≥ 문턱값).
    """
    import matplotlib.pyplot as plt

    occluded = sorted((r for r in rows if r["visible"] < 0.9), key=lambda r: r["mask_iou"])
    if len(occluded) < 2 * count:
        print("  (많이 가려진 객체가 적어 ch13-overlap 그림은 건너뜀)")
        return
    fig, axes = plt.subplots(2, count, figsize=(count * 2.7, 6.2))
    for row, group in enumerate((occluded[::-1][:count], occluded[:count])):
        for column, r in enumerate(group):
            image, target = dataset[r["image"]]
            pred = predictions[r["image"]]
            ax = axes[row, column]
            draw_boxes(ax, image)
            for k in torch.nonzero(pred["scores"] >= score_threshold)[:, 0]:
                ax.contour(pred["masks"][k].numpy().astype(float), levels=[0.5], colors="#39ff14", linewidths=1.2)
            ax.contour(target["masks"][r["object"]].numpy().astype(float), levels=[0.5], colors="white", linewidths=1.8,
                       linestyles="--")
            status = f"mask IoU {r['mask_iou']:.2f}, box IoU {r['box_iou']:.2f}" if r["found"] else "missed (no overlapping mask)"
            ax.set_title(f"val #{r['image']} {CLASS_NAMES[r['cls']]}: visible {r['visible']:.0%}\n{status}", fontsize=8)
    fig.suptitle("heavily occluded objects (visible < 90%): best (top) and worst (bottom). white dashed = the object's "
                 "ground truth, green = all predicted masks", fontsize=9.5)
    fig.tight_layout()
    fig.subplots_adjust(hspace=0.22)
    fig.savefig(path, dpi=120)
    plt.close(fig)


def plot_ablation(results, path):
    """절제 실험: 변형마다 마스크 AP 와 박스 AP (시드 평균 막대 + 시드별 점)."""
    import matplotlib.pyplot as plt

    names = list(results[0]["runs"].keys())
    positions = np.arange(len(names))[::-1]
    fig, axes = plt.subplots(1, 2, figsize=(11.5, 4.2), sharey=True)
    for ax, key, title, color in ((axes[0], "mask_AP", "mask AP", "#D55E00"), (axes[1], "box_AP", "box AP", "#0072B2")):
        values = np.array([[np.nan if r["runs"][name][key] is None else r["runs"][name][key] for name in names]
                           for r in results])  # (시드, 변형). 분할 머리가 없는 변형의 마스크 AP 는 nan
        low, high = np.nanmin(values), np.nanmax(values)
        for position, column in zip(positions, values.T):
            if np.isnan(column).all():
                ax.text(low - 0.03, position, "(no masks)", va="center", fontsize=8, color="gray")
                continue
            ax.barh(position, column.mean(), color=color, alpha=0.55, edgecolor="black", linewidth=0.5)
            ax.plot(column, np.full(len(column), position), "k.", markersize=6)
            ax.text(column.max() + 0.006 * (high - low + 0.1) / 0.1 * 0.3, position, f"{column.mean():.3f}", va="center",
                    fontsize=8)
        ax.set_xlim(low - 0.04, high + 0.04)
        ax.set_yticks(positions)
        ax.set_yticklabels(names, fontsize=8)
        ax.set_xlabel(f"validation {title} after {results[0]['epochs']} epochs (EMA)")
        ax.grid(axis="x", alpha=0.3)
        ax.set_title(f"{title}: bars = mean over {len(results)} seed(s), dots = each seed", fontsize=9)
    fig.tight_layout()
    fig.savefig(path, dpi=120)
    plt.close(fig)


# ── 8. 본 실험 · 절제 실험 ───────────────────────────────────────────────────


def main_experiment(args, device, train_set, val_set):
    start = time.time()
    epochs = 2 if args.quick else 30
    model, ema, history = run_experiment("미니 RF-DETR-Seg (본 실험): BCE + 다이스, 점 표본 추출, 마스크 1/4 해상도",
                                         train_set, val_set, epochs, device, args.seed)
    train_seconds = history["time"][-1]
    torch.save({"model": model.state_dict(), "ema": ema.module.state_dict(), "config": model.config,
                "history": history, "epochs": epochs}, CHECKPOINT_OUT)
    print(f"저장: {CHECKPOINT_OUT} (model · ema · config · history). 학습 {train_seconds:.0f}초 ({epochs * len(train_set) // 32} 스텝)")
    analyze(args, device, val_set, ema.module, history)
    print(f"본 실험 전체 {time.time() - start:.0f}초")


def analyze(args, device, val_set, seg, history):
    """학습된 EMA 모델 seg 를 채점하고 뜯어 본다 (표 출력 + 그림). --analyze 로 이 부분만 다시 돌릴 수 있다."""
    fig = lambda name: os.path.join(args.fig_dir, name)
    plot_curves(history, fig("ch13-curves.png"))

    box, mask, predictions = evaluate_seg(seg, val_set, device)
    print(f"[최종] EMA 모델, 검증 {len(val_set)}장")
    print(f"  박스 AP {box['AP']:.4f} AP50 {box['AP50']:.4f} AP75 {box['AP75']:.4f}  (학습 전 {history['box_AP'][0]:.4f})")
    print(f"  마스크 AP {mask['AP']:.4f} AP50 {mask['AP50']:.4f} AP75 {mask['AP75']:.4f}")
    print("  클래스별 박스 AP: " + ", ".join(f"{CLASS_NAMES[c]} {ap:.4f}" for c, ap in enumerate(box["per_class"])))
    print("  클래스별 마스크 AP: " + ", ".join(f"{CLASS_NAMES[c]} {ap:.4f}" for c, ap in enumerate(mask["per_class"])))
    print("  IoU 문턱값별 AP (클래스 평균):")
    print("    문턱값  | " + " | ".join(f"{t:.2f}" for t in COCO_IOU_THRESHOLDS))
    print("    박스    | " + " | ".join(f"{v:.2f}" for v in np.nanmean(box["table"], axis=1)))
    print("    마스크  | " + " | ".join(f"{v:.2f}" for v in np.nanmean(mask["table"], axis=1)))
    perfect = [{"boxes": t["boxes"], "scores": torch.ones(len(t["labels"])), "labels": t["labels"],
                "masks": F.interpolate(F.interpolate(t["masks"].float()[None], size=(24, 24), mode="area"),
                                       size=(96, 96), mode="bilinear", align_corners=False)[0] > 0.5}
               for t in val_set.targets]
    ceiling = evaluate_mask_ap(perfect, val_set.targets)
    print(f"  기준선 (정답 마스크를 24×24 로 줄였다가 되키운 것을 예측으로): 마스크 AP {ceiling['AP']:.4f} "
          f"AP50 {ceiling['AP50']:.4f} AP75 {ceiling['AP75']:.4f}")

    rows = object_table(predictions, val_set)
    summary = report_objects(rows, resolution_ceiling(val_set, 4), resolution_ceiling(val_set, 2))
    plot_iou_by_class(summary, fig("ch13-iou-by-class.png"))
    plot_box_vs_mask(val_set, rows, fig("ch13-box-vs-mask.png"))
    plot_predictions(val_set, predictions, fig("ch13-predictions.png"), list(range(6)))
    plot_overlap(val_set, predictions, rows, fig("ch13-overlap.png"))

    print("[디코더 층 수별] dec_layers = k 로 추론 (k 층만 쓰면 분할 머리의 블록도 k 개만 쓰인다; 0 = 인코더 제안, 블록 없음)")
    print("  층 수 | 박스 AP | 마스크 AP | 마스크 AP50 | 마스크 AP75 | 마스크 IoU 평균")
    layer_rows, layer_predictions = [], []
    for k in range(len(seg.decoder) + 1):
        box_k, mask_k, predictions_k = evaluate_seg(seg, val_set, device, dec_layers=k)
        mean_iou = float(np.mean([r["mask_iou"] for r in object_table(predictions_k, val_set)]))
        layer_rows.append((k, box_k["AP"], mask_k["AP"], mask_k["AP50"], mean_iou))
        layer_predictions.append(predictions_k)
        print(f"  {k:5d} | {box_k['AP']:.4f}  | {mask_k['AP']:.4f}    | {mask_k['AP50']:.4f}      | {mask_k['AP75']:.4f}      | {mean_iou:.4f}")
    crowded = max(range(min(len(val_set), 60)), key=lambda i: (len(val_set.targets[i]["labels"]),
                                                               sum(r["occluded"] for r in rows if r["image"] == i)))
    plot_layers(layer_rows, layer_predictions, val_set, crowded, fig("ch13-layers.png"))
    plot_dot_product(seg, val_set, crowded, fig("ch13-dot-product.png"), device)
    ratio = plot_pixel_embedding(seg, val_set, [crowded, 0, 1, 2, 3], fig("ch13-pixel-embedding.png"), device)
    print(f"[픽셀 임베딩] 검증 그림 5장의 픽셀 임베딩 (5·24·24 = 2,880개, 128차원): 주성분 분산 비율 "
          f"{', '.join(f'{v:.3f}' for v in ratio[:6])}, 앞 3개 합 {ratio[:3].sum():.3f}, 앞 10개 합 {ratio[:10].sum():.3f}")
    top = plot_prototypes(seg, val_set, [crowded, 0, 1], fig("ch13-prototypes.png"), device)
    print(f"  분산이 큰 채널 8개: {top}. 그림에 쓴 검증 그림: #{crowded} (객체 {len(val_set.targets[crowded]['labels'])}개), #0 – #3")

    head_params = sum(p.numel() for p in seg.segmentation_head.parameters())
    total_params = sum(p.numel() for p in seg.parameters())
    images = val_set.images[:64].to(device).float() / 255.0
    plain = MiniRFDETR(**{k: v for k, v in seg.config.items() if k != "mask_downsample_ratio"}).to(device)
    repeats = 3 if args.quick else 30
    times = [forward_time(plain, images, repeats), forward_time(seg, images, repeats),
             forward_time(seg, images, repeats, all_layer_masks=True)]
    print(f"[분할 머리의 값] 매개변수 {head_params:,} / {total_params:,} ({head_params / total_params:.1%}). "
          f"추론 순전파 (배치 64, 그림 한 장당, {repeats}번 가운데 최솟값): 분할 머리 없이 {times[0]:.3f} ms, "
          f"있을 때 {times[1]:.3f} ms, 모든 층의 마스크까지 {times[2]:.3f} ms")


def analyze_checkpoint(args, device, val_set):
    """저장해 둔 ch13_seg.pt 를 읽어 분석과 그림만 다시 만든다 (학습하지 않는다)."""
    checkpoint = torch.load(CHECKPOINT_OUT, map_location="cpu")
    seg = MiniRFDETRSeg(**checkpoint["config"])
    seg.load_state_dict(checkpoint["ema"])
    print(f"[분석만] {CHECKPOINT_OUT} 의 EMA 가중치 ({checkpoint['epochs']} 에폭 학습한 것) 를 읽었다")
    analyze(args, device, val_set, seg.to(device).eval(), checkpoint["history"])
    summarize_ablations(sorted(glob.glob("ch13_ablations_seed*.json")), 4, args.fig_dir)  # 절제 결과가 있으면 표 · 그림도


ABLATIONS = [
    ("BCE + Dice, uncertain points (official)", dict()),
    ("BCE only", dict(mask_dice=0.0)),
    ("Dice only", dict(mask_ce=0.0)),
    ("BCE + Dice, all pixels", dict(points="all")),
    ("BCE + Dice, no mask term in matching", dict(mask_cost=False)),
    ("BCE + Dice, masks at 1/2 resolution", dict(mask_downsample_ratio=2)),
    ("no segmentation head (detection only)", dict(with_head=False)),
]


def summarize_ablations(paths, epochs: int, fig_dir: str):
    """저장된 절제 결과(시드마다 JSON 하나)를 모아 평균 (최소 – 최대) 표를 출력하고 그림을 그린다."""
    results = []
    for path in paths:
        with open(path) as f:
            results.append(json.load(f))
    results = [r for r in results if r["epochs"] == epochs and list(r["runs"]) == [n for n, _ in ABLATIONS]]
    if not results:
        return
    seeds = [r["seed"] for r in results]
    print(f"[절제 요약] {epochs} 에폭 뒤의 EMA 모델, 시드 {seeds} ({len(seeds)}개). 평균 (최소 – 최대)")
    print(f"  {'변형':40s} | 박스 AP                  | 마스크 AP                | 마스크 AP75              | 마스크 IoU 평균")
    for name, _ in ABLATIONS:
        cells = []
        for key in ("box_AP", "mask_AP", "mask_AP75", "mask_iou"):
            values = [r["runs"][name][key] for r in results]
            cells.append(f"{np.mean(values):.4f} ({min(values):.4f} – {max(values):.4f})" if values[0] is not None
                         else "—".ljust(24))
        print(f"  {name:40s} | " + " | ".join(cells))
    plot_ablation(results, os.path.join(fig_dir, "ch13-ablation.png"))


def ablation_experiments(args, device, train_set, val_set):
    start = time.time()
    epochs = 1 if args.quick else 4
    runs = {}
    for name, options in ABLATIONS:
        began = time.time()
        _, ema, history = run_experiment(name, train_set, val_set, epochs, device, args.seed, verbose=False, **options)
        box, mask, predictions = evaluate_seg(ema.module, val_set, device)
        runs[name] = {"box_AP": box["AP"], "box_AP75": box["AP75"], "seconds": time.time() - began,
                      "mask_AP": mask["AP"] if mask else None, "mask_AP50": mask["AP50"] if mask else None,
                      "mask_AP75": mask["AP75"] if mask else None,
                      "mask_iou": float(np.mean([r["mask_iou"] for r in object_table(predictions, val_set)])) if mask else None,
                      "history": history}
        r = runs[name]
        text = (f"마스크 AP {r['mask_AP']:.4f} AP50 {r['mask_AP50']:.4f} AP75 {r['mask_AP75']:.4f} IoU 평균 {r['mask_iou']:.4f}"
                if mask else "마스크 없음")
        print(f"  → 박스 AP {r['box_AP']:.4f} | {text} | {r['seconds']:.0f}초", flush=True)
    path = "ch13_ablations_quick.json" if args.quick else f"ch13_ablations_seed{args.seed}.json"
    with open(path, "w") as f:
        json.dump({"seed": args.seed, "epochs": epochs, "runs": runs}, f)
    print(f"저장: {path}")
    summarize_ablations([path] if args.quick else sorted(glob.glob("ch13_ablations_seed*.json")), epochs, args.fig_dir)
    print(f"절제 실험 전체 {time.time() - start:.0f}초")


# --8<-- [start:main]
def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--quick", action="store_true")
    parser.add_argument("--ablations", action="store_true", help="본 실험 대신 절제 실험을 돌린다")
    parser.add_argument("--analyze", action="store_true", help="학습 없이 ch13_seg.pt 로 분석 · 그림만 다시 만든다")
    parser.add_argument("--fig-dir", default="figures")
    parser.add_argument("--seed", type=int, default=0)
    args = parser.parse_args()
    import matplotlib
    matplotlib.use("Agg")
    os.makedirs(args.fig_dir, exist_ok=True)
    device = get_device()
    torch.set_num_threads(min(4, torch.get_num_threads()))  # 작은 연산뿐이라 CPU 스레드가 많으면 오히려 느리다
    print(f"장치: {device}")
    small = args.quick and args.ablations
    train_set = ShapesDataset((64 if small else 256) if args.quick else 4000, seed=0, with_masks=True)
    val_set = ShapesDataset((32 if small else 64) if args.quick else 500, seed=1, with_masks=True)
    occluded = sum(int(m.sum()) < int(shape_mask(int(c), o["box"], val_set.size).sum())
                   for t, scene in zip(val_set.targets, val_set.scenes) for m, c, o in zip(t["masks"], t["labels"], scene))
    print(f"학습 {len(train_set)}장, 검증 {len(val_set)}장 (정답 객체 {sum(len(t['labels']) for t in val_set.targets)}개, "
          f"그 가운데 다른 객체에 일부 가려진 것 {occluded}개)")
    if args.ablations:
        ablation_experiments(args, device, train_set, val_set)
    elif args.analyze:
        analyze_checkpoint(args, device, val_set)
    else:
        hand_examples()
        checks(device)
        main_experiment(args, device, train_set, val_set)
        if not args.quick:
            official_checks()
            seg_nano_trace()
# --8<-- [end:main]


if __name__ == "__main__":
    main()
