Release v3.0: selected sub-4M semantic colorizer, inference and verified ONNX

DEPLOYMENT.md

@@ -1,80 +1,34 @@
-# Colorizer deployment
+# v3 deployment
 
-Use the release's inference wrapper or its ONNX graph to obtain the complete
-improvement. The `.safetensors` file contains the learned colorizer; guided
-decoding is implemented by `spatial.py` and is included in the ONNX graph.
+## Local Python
 
-## Python / PyTorch
-
-Run from the extracted release directory:
-
-```bash
-python -m pip install -r requirements.txt
-python inference.py --model . --output-dir colorized photo.jpg
-```
-
-The default guided radius is 8 at the model's input resolution. Use
-`--guided-radius 0` for raw predictions or `--guided-radius 16` for stronger
-smoothing. Stronger smoothing can remove legitimate small color details.
-`--flip-tta --guided-radius 4` is an optional two-pass mode. The released
-ONNX graph is the single-pass radius-8 mode.
+Use Python 3.10 or 3.11 with the supplied requirements. CPU inference works without a GPU. Install a CUDA-compatible PyTorch build for GPU execution. Load once, put the model in evaluation mode, and reuse it across requests. The supplied loader does this automatically.
 
 ```python
-from PIL import Image
-from model import load_model
-from inference import colorize
-
-model = load_model('.')
-result = colorize(model, Image.open('photo.jpg'))
-result.save('colorized.png')
+from inference import load_colorizer, colorize
+model = load_colorizer('.', 'cpu')
 ```
 
-The wrapper handles EXIF orientation, preserves aspect ratio, bounds the
-longest network-input side to 256 pixels, upsamples chroma to the original
-oriented image dimensions and combines it with the original Lab luminance.
-Final RGB conversion can clip colors outside the display gamut. Very large
-inputs still require memory for full-resolution color conversion. There is
-no video temporal-consistency guarantee.
+The runtime loads a single 3,994,676-parameter network. The training-only teacher and discriminator are not required or downloaded.
 
-## ONNX without PyTorch
+## Hugging Face Space
 
-```bash
-python -m pip install -r requirements-onnx.txt
-python colorize_onnx.py --model colorizer.onnx --output-dir colorized photo.jpg
-```
+Copy `app.py`, `inference.py`, `semantic_model.py`, and `requirements-space.txt` into a Gradio Space. Rename the latter to `requirements.txt`. Use Gradio 6.28.0 in the Space README and choose ZeroGPU hardware.
 
-Input name: `luminance`, float32, shape `N x 1 x H x W`, values `L*/50 - 1`.
-Output name: `chroma`, float32, shape `N x 2 x H x W`, Lab a and b values.
-Height and width must each be at least 8. Dynamic shapes and batches are
-supported. Prefer a longest input side of 256 to match the evaluated
-operating point. Ordinary RGB values are not valid graph inputs.
+The released app pins `MODEL_REVISION` to the verified model commit. Setting this environment variable deliberately overrides that pin. `MODEL_ID` can be a local directory for offline use or a Hub repository ID.
 
-The graph includes temperature-0.38 decoding and radius-8 guided filtering
-with epsilon 0.001. It does not include file loading, EXIF handling, Lab
-conversion, aspect-ratio resizing or final chroma upsampling; these are
-implemented in `colorize_onnx.py`. The ONNX wrapper uses Pillow resizing,
-whereas the PyTorch wrapper uses PyTorch interpolation. Their image-level
-comparison is recorded in the release checks.
+Import `spaces` before PyTorch. The model is placed on CUDA once at startup, and only the network stage is inside `@spaces.GPU`. Image preparation and full-resolution rendering happen on CPU. `ZEROGPU_CPU_TEST=1` enables the local CPU path for verification.
 
-## Publish to main
+## Input handling
 
-Authenticate normally on your own computer with repository write access:
+The image pipeline applies EXIF orientation, preserves alpha, rejects images over 12 megapixels, and restores colour at the original output dimensions. Network processing preserves aspect ratio with a maximum 256-pixel side. Errors are returned explicitly rather than replaced by a blank image.
 
-```bash
-hf auth login
-python upload_main.py --folder . --repo User-2468/mini-unet-colorizer
-```
+The default API `/colorize` takes an image, colour strength (0–1.5), and smoothing (`Gentle`, `Balanced`, or `Strong`). It returns a PNG. Requests are serialized to bound memory usage.
+
+## Versioning and rollback
 
-This performs one upload to `main` with an optimistic-concurrency guard.
-It also verifies that `stable` retains its pre-upload revision. The app can
-keep using `stable` until you choose to switch it to the tested release.
-The current chat connection has Jobs/read access but no repository write
-scope; the downloadable release is the publication fallback.
+Model and source are committed atomically. The app pins the model commit rather than following moving main. `RELEASE_MANIFEST.json` records selection and previous commits. To roll back, use the recorded prior Space commit and model revision. The user-managed stable branch is not modified.
 
-## Deployment limits
+## Verification scope
 
-This is a measured app-testing candidate. Semantic color mistakes remain,
-and smoothing cannot infer an object's unknown original color. Review the
-included failure examples on your app's real input photos before describing
-it as generally production-ready. Browser/mobile performance and real-time
-video have not been validated.
+`QA.json` records tests for strict reload, parameter count, finite outputs, dimensions, transparency, black/white inputs, grayscale strength zero, input validation, a Gradio HTTP request, and ONNX parity. `RELEASE_REPORT.md` records visual selection and the separate live Space check. These checks do not imply factual colour reconstruction or eliminate every visual failure case.

PIPELINE_EVAL.json

@@ -0,0 +1,1196 @@
+{
+  "n_color": 78,
+  "n_total": 80,
+  "pipeline": "actual aspect-preserving release vs prior Space 256/radius8/temp0.38; metrics measured after output resize to256",
+  "summary": {
+    "old_space": {
+      "ab_error": 16.144625015747852,
+      "patch_excess": 1.8169478370020022,
+      "color_coverage": 0.47298392271384215,
+      "missed_color": 0.24084079671968467
+    },
+    "release": {
+      "ab_error": 14.243927399317423,
+      "patch_excess": 0.6932277647444071,
+      "color_coverage": 0.479247068747496,
+      "missed_color": 0.1663338435453805
+    }
+  },
+  "rows": [
+    {
+      "index": 1616,
+      "old_space": {
+        "ab_error": 26.323200225830078,
+        "patch_excess": 4.660755157470703,
+        "color_coverage": 0.823211669921875,
+        "missed_color": 0.00838758732119945
+      },
+      "release": {
+        "ab_error": 16.94342803955078,
+        "patch_excess": 0.8918601274490356,
+        "color_coverage": 0.4547271728515625,
+        "missed_color": 0.1244119184526921
+      }
+    },
+    {
+      "index": 1890,
+      "old_space": {
+        "ab_error": 8.562353134155273,
+        "patch_excess": 0.4099482297897339,
+        "color_coverage": 0.081634521484375,
+        "missed_color": 0.5827405612444305
+      },
+      "release": {
+        "ab_error": 8.610569953918457,
+        "patch_excess": 0.49974769353866577,
+        "color_coverage": 0.0383148193359375,
+        "missed_color": 0.44008442116782615
+      }
+    },
+    {
+      "index": 801,
+      "old_space": {
+        "ab_error": 22.603069305419922,
+        "patch_excess": 2.7419018745422363,
+        "color_coverage": 0.364776611328125,
+        "missed_color": 0.3159938757982001
+      },
+      "release": {
+        "ab_error": 16.933408737182617,
+        "patch_excess": 0.5424809455871582,
+        "color_coverage": 0.7138671875,
+        "missed_color": 0.01211770417117891
+      }
+    },
+    {
+      "index": 1350,
+      "old_space": {
+        "ab_error": 19.007339477539062,
+        "patch_excess": 1.4587503671646118,
+        "color_coverage": 0.2160186767578125,
+        "missed_color": 0.8389771099393459
+      },
+      "release": {
+        "ab_error": 16.581514358520508,
+        "patch_excess": 0.950056791305542,
+        "color_coverage": 0.64739990234375,
+        "missed_color": 0.000883903806882258
+      }
+    },
+    {
+      "index": 1452,
+      "old_space": {
+        "ab_error": 11.529170036315918,
+        "patch_excess": 1.2069720029830933,
+        "color_coverage": 0.402740478515625,
+        "missed_color": 0.35575881190643127
+      },
+      "release": {
+        "ab_error": 9.721474647521973,
+        "patch_excess": 0.5086259245872498,
+        "color_coverage": 0.2576904296875,
+        "missed_color": 0.18481101408630252
+      }
+    },
+    {
+      "index": 2287,
+      "old_space": {
+        "ab_error": 15.350773811340332,
+        "patch_excess": 1.9994475841522217,
+        "color_coverage": 0.5487213134765625,
+        "missed_color": 0.08166368855263659
+      },
+      "release": {
+        "ab_error": 14.244087219238281,
+        "patch_excess": 1.2213833332061768,
+        "color_coverage": 0.6115264892578125,
+        "missed_color": 0.009846785537771357
+      }
+    },
+    {
+      "index": 1064,
+      "old_space": {
+        "ab_error": 21.012693405151367,
+        "patch_excess": 1.974622130393982,
+        "color_coverage": 0.4133453369140625,
+        "missed_color": 0.06151211801896733
+      },
+      "release": {
+        "ab_error": 15.226168632507324,
+        "patch_excess": 0.29835397005081177,
+        "color_coverage": 0.716217041015625,
+        "missed_color": 0.0
+      }
+    },
+    {
+      "index": 1342,
+      "old_space": {
+        "ab_error": 25.887615203857422,
+        "patch_excess": 2.6944580078125,
+        "color_coverage": 0.3334808349609375,
+        "missed_color": 0.17779714872198635
+      },
+      "release": {
+        "ab_error": 29.920133590698242,
+        "patch_excess": 0.9985980987548828,
+        "color_coverage": 0.80023193359375,
+        "missed_color": 0.01242864775187695
+      }
+    },
+    {
+      "index": 1974,
+      "old_space": {
+        "ab_error": 9.522749900817871,
+        "patch_excess": 1.2533193826675415,
+        "color_coverage": 0.207183837890625,
+        "missed_color": 0.5120499211017071
+      },
+      "release": {
+        "ab_error": 10.576430320739746,
+        "patch_excess": 2.0199408531188965,
+        "color_coverage": 0.503326416015625,
+        "missed_color": 0.03285038014632047
+      }
+    },
+    {
+      "index": 1324,
+      "old_space": {
+        "ab_error": 26.204675674438477,
+        "patch_excess": 2.7856273651123047,
+        "color_coverage": 0.9070587158203125,
+        "missed_color": 0.0
+      },
+      "release": {
+        "ab_error": 33.15073776245117,
+        "patch_excess": 1.4181828498840332,
+        "color_coverage": 0.987152099609375,
+        "missed_color": 0.0
+      }
+    },
+    {
+      "index": 1241,
+      "old_space": {
+        "ab_error": 12.267753601074219,
+        "patch_excess": 2.981765031814575,
+        "color_coverage": 0.386505126953125,
+        "missed_color": 0.2614813208263298
+      },
+      "release": {
+        "ab_error": 10.905852317810059,
+        "patch_excess": 1.2132973670959473,
+        "color_coverage": 0.6724700927734375,
+        "missed_color": 0.052052269153608416
+      }
+    },
+    {
+      "index": 1076,
+      "old_space": {
+        "ab_error": 32.03386306762695,
+        "patch_excess": 1.8285555839538574,
+        "color_coverage": 0.5383453369140625,
+        "missed_color": 0.18550559192337193
+      },
+      "release": {
+        "ab_error": 25.441709518432617,
+        "patch_excess": 0.3919871747493744,
+        "color_coverage": 0.240875244140625,
+        "missed_color": 0.4045627240782691
+      }
+    },
+    {
+      "index": 1592,
+      "old_space": {
+        "ab_error": 14.867029190063477,
+        "patch_excess": 1.3357399702072144,
+        "color_coverage": 0.639739990234375,
+        "missed_color": 0.15845956598129066
+      },
+      "release": {
+        "ab_error": 14.02211856842041,
+        "patch_excess": 0.548101544380188,
+        "color_coverage": 0.6025848388671875,
+        "missed_color": 0.09786789496177406
+      }
+    },
+    {
+      "index": 894,
+      "old_space": {
+        "ab_error": 19.769493103027344,
+        "patch_excess": 1.7964528799057007,
+        "color_coverage": 0.419647216796875,
+        "missed_color": 0.21247737003936895
+      },
+      "release": {
+        "ab_error": 18.06083106994629,
+        "patch_excess": 0.9287981390953064,
+        "color_coverage": 0.205474853515625,
+        "missed_color": 0.29653150952613583
+      }
+    },
+    {
+      "index": 2148,
+      "old_space": {
+        "ab_error": 7.6851372718811035,
+        "patch_excess": 0.2038302719593048,
+        "color_coverage": 0.357147216796875,
+        "missed_color": 0.06188071827189552
+      },
+      "release": {
+        "ab_error": 8.425639152526855,
+        "patch_excess": 0.2777884006500244,
+        "color_coverage": 0.5030364990234375,
+        "missed_color": 0.029231995748073347
+      }
+    },
+    {
+      "index": 499,
+      "old_space": {
+        "ab_error": 12.139986038208008,
+        "patch_excess": 2.4101762771606445,
+        "color_coverage": 0.259033203125,
+        "missed_color": 0.5720882503848127
+      },
+      "release": {
+        "ab_error": 10.870327949523926,
+        "patch_excess": 1.7260417938232422,
+        "color_coverage": 0.6872406005859375,
+        "missed_color": 0.028860954335556695
+      }
+    },
+    {
+      "index": 1091,
+      "old_space": {
+        "ab_error": 7.706239700317383,
+        "patch_excess": 0.9490010738372803,
+        "color_coverage": 0.70660400390625,
+        "missed_color": 0.04750045695485286
+      },
+      "release": {
+        "ab_error": 8.351296424865723,
+        "patch_excess": 0.41664353013038635,
+        "color_coverage": 0.585662841796875,
+        "missed_color": 0.03813288247121185
+      }
+    },
+    {
+      "index": 643,
+      "old_space": {
+        "ab_error": 12.94747543334961,
+        "patch_excess": 1.5321152210235596,
+        "color_coverage": 0.28607177734375,
+        "missed_color": 0.27395094734394976
+      },
+      "release": {
+        "ab_error": 10.66858959197998,
+        "patch_excess": 0.8456946015357971,
+        "color_coverage": 0.5540924072265625,
+        "missed_color": 0.05258630710217366
+      }
+    },
+    {
+      "index": 2199,
+      "old_space": {
+        "ab_error": 30.45133399963379,
+        "patch_excess": 0.11608487367630005,
+        "color_coverage": 0.0208892822265625,
+        "missed_color": 0.9190106905012267
+      },
+      "release": {
+        "ab_error": 20.48551368713379,
+        "patch_excess": 0.5652980804443359,
+        "color_coverage": 0.413116455078125,
+        "missed_color": 0.29834822993340343
+      }
+    },
+    {
+      "index": 28,
+      "old_space": {
+        "ab_error": 9.457603454589844,
+        "patch_excess": 0.390183687210083,
+        "color_coverage": 0.058074951171875,
+        "missed_color": 0.667576025034101
+      },
+      "release": {
+        "ab_error": 15.951315879821777,
+        "patch_excess": 0.9229965209960938,
+        "color_coverage": 0.7261199951171875,
+        "missed_color": 0.0
+      }
+    },
+    {
+      "index": 193,
+      "old_space": {
+        "ab_error": 8.022804260253906,
+        "patch_excess": 0.6247572898864746,
+        "color_coverage": 0.52301025390625,
+        "missed_color": 0.018376565601259325
+      },
+      "release": {
+        "ab_error": 10.262919425964355,
+        "patch_excess": 0.3918754458427429,
+        "color_coverage": 0.5903778076171875,
+        "missed_color": 0.0
+      }
+    },
+    {
+      "index": 1572,
+      "old_space": {
+        "ab_error": 13.333690643310547,
+        "patch_excess": 0.11408320814371109,
+        "color_coverage": 0.109130859375,
+        "missed_color": 0.43947592309001193
+      },
+      "release": {
+        "ab_error": 12.270377159118652,
+        "patch_excess": 0.104813352227211,
+        "color_coverage": 0.170135498046875,
+        "missed_color": 0.3524247064828994
+      }
+    },
+    {
+      "index": 2130,
+      "old_space": {
+        "ab_error": 16.954084396362305,
+        "patch_excess": 1.4006093740463257,
+        "color_coverage": 0.595916748046875,
+        "missed_color": 0.25908369733414294
+      },
+      "release": {
+        "ab_error": 9.94679069519043,
+        "patch_excess": 0.05882778391242027,
+        "color_coverage": 0.43670654296875,
+        "missed_color": 0.13325367755078057
+      }
+    },
+    {
+      "index": 1865,
+      "old_space": {
+        "ab_error": 7.544837951660156,
+        "patch_excess": 0.5778899788856506,
+        "color_coverage": 0.1146240234375,
+        "missed_color": 0.33362932893568437
+      },
+      "release": {
+        "ab_error": 8.306941986083984,
+        "patch_excess": 0.6006697416305542,
+        "color_coverage": 0.4653778076171875,
+        "missed_color": 0.30293035646327543
+      }
+    },
+    {
+      "index": 1802,
+      "old_space": {
+        "ab_error": 18.950891494750977,
+        "patch_excess": 2.2092673778533936,
+        "color_coverage": 0.5519561767578125,
+        "missed_color": 0.18835859782093795
+      },
+      "release": {
+        "ab_error": 15.6486177444458,
+        "patch_excess": 0.3804606795310974,
+        "color_coverage": 0.32672119140625,
+        "missed_color": 0.17589412600663193
+      }
+    },
+    {
+      "index": 1843,
+      "old_space": {
+        "ab_error": 11.737858772277832,
+        "patch_excess": 1.105494499206543,
+        "color_coverage": 0.6038665771484375,
+        "missed_color": 0.02552606103836552
+      },
+      "release": {
+        "ab_error": 14.591524124145508,
+        "patch_excess": 0.31478655338287354,
+        "color_coverage": 0.5148162841796875,
+        "missed_color": 0.10567075966780455
+      }
+    },
+    {
+      "index": 1310,
+      "old_space": {
+        "ab_error": 23.062294006347656,
+        "patch_excess": 0.9265129566192627,
+        "color_coverage": 0.88275146484375,
+        "missed_color": 0.007003060940543549
+      },
+      "release": {
+        "ab_error": 8.736886024475098,
+        "patch_excess": 0.38463208079338074,
+        "color_coverage": 0.2847442626953125,
+        "missed_color": 0.11650125220294963
+      }
+    },
+    {
+      "index": 760,
+      "old_space": {
+        "ab_error": 13.43350601196289,
+        "patch_excess": 0.9921309947967529,
+        "color_coverage": 0.2053070068359375,
+        "missed_color": 0.9260222323343951
+      },
+      "release": {
+        "ab_error": 16.876251220703125,
+        "patch_excess": 1.1696078777313232,
+        "color_coverage": 0.6178131103515625,
+        "missed_color": 0.44172138074497824
+      }
+    },
+    {
+      "index": 1547,
+      "old_space": {
+        "ab_error": 10.504715919494629,
+        "patch_excess": 0.8381835222244263,
+        "color_coverage": 0.14837646484375,
+        "missed_color": 0.39370380186706716
+      },
+      "release": {
+        "ab_error": 8.540243148803711,
+        "patch_excess": 0.3024168610572815,
+        "color_coverage": 0.0621490478515625,
+        "missed_color": 0.17516270577495066
+      }
+    },
+    {
+      "index": 1984,
+      "old_space": {
+        "ab_error": 27.105270385742188,
+        "patch_excess": 3.5282702445983887,
+        "color_coverage": 0.7821044921875,
+        "missed_color": 0.013363312404547769
+      },
+      "release": {
+        "ab_error": 28.28919792175293,
+        "patch_excess": 0.48088812828063965,
+        "color_coverage": 0.1480865478515625,
+        "missed_color": 0.258590700831495
+      }
+    },
+    {
+      "index": 20,
+      "old_space": {
+        "ab_error": 15.894635200500488,
+        "patch_excess": 1.3054187297821045,
+        "color_coverage": 0.531951904296875,
+        "missed_color": 0.07939068100358423
+      },
+      "release": {
+        "ab_error": 17.26842498779297,
+        "patch_excess": 0.5532290935516357,
+        "color_coverage": 0.55316162109375,
+        "missed_color": 0.08535586277521762
+      }
+    },
+    {
+      "index": 995,
+      "old_space": {
+        "ab_error": 15.624862670898438,
+        "patch_excess": 2.2529406547546387,
+        "color_coverage": 0.259613037109375,
+        "missed_color": 0.4021378891845213
+      },
+      "release": {
+        "ab_error": 13.449739456176758,
+        "patch_excess": 0.6617642641067505,
+        "color_coverage": 0.57403564453125,
+        "missed_color": 0.05704149745600523
+      }
+    },
+    {
+      "index": 719,
+      "old_space": {
+        "ab_error": 17.673622131347656,
+        "patch_excess": 6.900073051452637,
+        "color_coverage": 0.7959136962890625,
+        "missed_color": 0.03709780024776509
+      },
+      "release": {
+        "ab_error": 10.906693458557129,
+        "patch_excess": 0.8480014801025391,
+        "color_coverage": 0.5038604736328125,
+        "missed_color": 0.0922087923125858
+      }
+    },
+    {
+      "index": 1494,
+      "old_space": {
+        "ab_error": 8.360665321350098,
+        "patch_excess": 0.411716490983963,
+        "color_coverage": 0.1339569091796875,
+        "missed_color": 0.5299967917869747
+      },
+      "release": {
+        "ab_error": 7.159595966339111,
+        "patch_excess": 0.266187459230423,
+        "color_coverage": 0.0975189208984375,
+        "missed_color": 0.6700352903432788
+      }
+    },
+    {
+      "index": 842,
+      "old_space": {
+        "ab_error": 11.821839332580566,
+        "patch_excess": 2.703233003616333,
+        "color_coverage": 0.928680419921875,
+        "missed_color": 0.0
+      },
+      "release": {
+        "ab_error": 11.372722625732422,
+        "patch_excess": 0.5155807137489319,
+        "color_coverage": 0.907684326171875,
+        "missed_color": 7.853608733212911e-05
+      }
+    },
+    {
+      "index": 514,
+      "old_space": {
+        "ab_error": 9.687101364135742,
+        "patch_excess": 0.6117255687713623,
+        "color_coverage": 0.211181640625,
+        "missed_color": 0.5444506483032446
+      },
+      "release": {
+        "ab_error": 9.208121299743652,
+        "patch_excess": 0.18699583411216736,
+        "color_coverage": 0.1870574951171875,
+        "missed_color": 0.7229356659842422
+      }
+    },
+    {
+      "index": 1700,
+      "old_space": {
+        "ab_error": 15.625609397888184,
+        "patch_excess": 2.0040969848632812,
+        "color_coverage": 0.3100738525390625,
+        "missed_color": 0.4106577942620268
+      },
+      "release": {
+        "ab_error": 12.55972957611084,
+        "patch_excess": 0.6425396203994751,
+        "color_coverage": 0.3192138671875,
+        "missed_color": 0.323370059270572
+      }
+    },
+    {
+      "index": 81,
+      "old_space": {
+        "ab_error": 16.702062606811523,
+        "patch_excess": 3.883439064025879,
+        "color_coverage": 0.579315185546875,
+        "missed_color": 0.027358006001459816
+      },
+      "release": {
+        "ab_error": 16.94745445251465,
+        "patch_excess": 0.9333924651145935,
+        "color_coverage": 0.3153076171875,
+        "missed_color": 0.003919872401394934
+      }
+    },
+    {
+      "index": 669,
+      "old_space": {
+        "ab_error": 16.509859085083008,
+        "patch_excess": 0.4290950298309326,
+        "color_coverage": 0.1493682861328125,
+        "missed_color": 0.43240032314784016
+      },
+      "release": {
+        "ab_error": 15.242349624633789,
+        "patch_excess": 0.8886958360671997,
+        "color_coverage": 0.548095703125,
+        "missed_color": 0.007888609038635176
+      }
+    },
+    {
+      "index": 1863,
+      "old_space": {
+        "ab_error": 14.619690895080566,
+        "patch_excess": 1.6612411737442017,
+        "color_coverage": 0.47161865234375,
+        "missed_color": 0.12886517030293518
+      },
+      "release": {
+        "ab_error": 15.573603630065918,
+        "patch_excess": 2.386152505874634,
+        "color_coverage": 0.613861083984375,
+        "missed_color": 0.11965677810914038
+      }
+    },
+    {
+      "index": 118,
+      "old_space": {
+        "ab_error": 12.41354751586914,
+        "patch_excess": 2.3019068241119385,
+        "color_coverage": 0.42901611328125,
+        "missed_color": 0.13236981670440096
+      },
+      "release": {
+        "ab_error": 9.036662101745605,
+        "patch_excess": 1.469712257385254,
+        "color_coverage": 0.6489715576171875,
+        "missed_color": 0.0034115932140309523
+      }
+    },
+    {
+      "index": 247,
+      "old_space": {
+        "ab_error": 22.328853607177734,
+        "patch_excess": 1.0756666660308838,
+        "color_coverage": 0.4027252197265625,
+        "missed_color": 0.29081412325978323
+      },
+      "release": {
+        "ab_error": 23.825349807739258,
+        "patch_excess": 0.08932070434093475,
+        "color_coverage": 0.217254638671875,
+        "missed_color": 0.20771556067367208
+      }
+    },
+    {
+      "index": 718,
+      "old_space": {
+        "ab_error": 14.24968433380127,
+        "patch_excess": 1.4334428310394287,
+        "color_coverage": 0.6019744873046875,
+        "missed_color": 0.1952375935096407
+      },
+      "release": {
+        "ab_error": 9.221932411193848,
+        "patch_excess": 0.7787426114082336,
+        "color_coverage": 0.536376953125,
+        "missed_color": 0.23814666526182698
+      }
+    },
+    {
+      "index": 875,
+      "old_space": {
+        "ab_error": 12.56160831451416,
+        "patch_excess": 0.5671428442001343,
+        "color_coverage": 0.9713592529296875,
+        "missed_color": 0.003802414009628131
+      },
+      "release": {
+        "ab_error": 14.186704635620117,
+        "patch_excess": 0.3387293219566345,
+        "color_coverage": 0.8649749755859375,
+        "missed_color": 0.03068094606851322
+      }
+    },
+    {
+      "index": 2311,
+      "old_space": {
+        "ab_error": 22.329435348510742,
+        "patch_excess": 0.5803585052490234,
+        "color_coverage": 0.1852569580078125,
+        "missed_color": 0.4449274087109547
+      },
+      "release": {
+        "ab_error": 23.35008430480957,
+        "patch_excess": 0.3492544889450073,
+        "color_coverage": 0.12896728515625,
+        "missed_color": 0.3160756709194897
+      }
+    },
+    {
+      "index": 272,
+      "old_space": {
+        "ab_error": 50.092628479003906,
+        "patch_excess": 2.4126620292663574,
+        "color_coverage": 0.942230224609375,
+        "missed_color": 0.01947199203006838
+      },
+      "release": {
+        "ab_error": 13.429896354675293,
+        "patch_excess": 0.572797417640686,
+        "color_coverage": 0.0374298095703125,
+        "missed_color": 0.5612462074899244
+      }
+    },
+    {
+      "index": 1947,
+      "old_space": {
+        "ab_error": 13.949646949768066,
+        "patch_excess": 1.9255857467651367,
+        "color_coverage": 0.27593994140625,
+        "missed_color": 0.4522735813603908
+      },
+      "release": {
+        "ab_error": 14.641658782958984,
+        "patch_excess": 0.21683070063591003,
+        "color_coverage": 0.1020965576171875,
+        "missed_color": 0.6970526654855854
+      }
+    },
+    {
+      "index": 2307,
+      "old_space": {
+        "ab_error": 14.67344856262207,
+        "patch_excess": 1.292840838432312,
+        "color_coverage": 0.1552886962890625,
+        "missed_color": 0.40270344180958706
+      },
+      "release": {
+        "ab_error": 13.693403244018555,
+        "patch_excess": 0.16015203297138214,
+        "color_coverage": 0.4368133544921875,
+        "missed_color": 0.07055514318084151
+      }
+    },
+    {
+      "index": 1936,
+      "old_space": {
+        "ab_error": 6.898637771606445,
+        "patch_excess": 0.40601056814193726,
+        "color_coverage": 0.3411102294921875,
+        "missed_color": 0.24669745462356352
+      },
+      "release": {
+        "ab_error": 7.870009422302246,
+        "patch_excess": 0.27915287017822266,
+        "color_coverage": 0.320526123046875,
+        "missed_color": 0.16385637060108116
+      }
+    },
+    {
+      "index": 1935,
+      "old_space": {
+        "ab_error": 19.05333137512207,
+        "patch_excess": 0.9947030544281006,
+        "color_coverage": 0.8654022216796875,
+        "missed_color": 0.010393743440430646
+      },
+      "release": {
+        "ab_error": 21.285797119140625,
+        "patch_excess": 1.0532053709030151,
+        "color_coverage": 0.874114990234375,
+        "missed_color": 0.01535362426786742
+      }
+    },
+    {
+      "index": 406,
+      "old_space": {
+        "ab_error": 11.752641677856445,
+        "patch_excess": 2.6542296409606934,
+        "color_coverage": 0.50799560546875,
+        "missed_color": 0.2511842190643047
+      },
+      "release": {
+        "ab_error": 14.617018699645996,
+        "patch_excess": 1.5975663661956787,
+        "color_coverage": 0.750701904296875,
+        "missed_color": 0.01739017584841996
+      }
+    },
+    {
+      "index": 630,
+      "old_space": {
+        "ab_error": 9.711251258850098,
+        "patch_excess": 0.9617525339126587,
+        "color_coverage": 0.1025543212890625,
+        "missed_color": 0.411119306656832
+      },
+      "release": {
+        "ab_error": 7.769914627075195,
+        "patch_excess": 0.10242865979671478,
+        "color_coverage": 0.0,
+        "missed_color": 0.8865019361976766
+      }
+    },
+    {
+      "index": 1023,
+      "old_space": {
+        "ab_error": 12.51215934753418,
+        "patch_excess": 3.8293511867523193,
+        "color_coverage": 0.8065338134765625,
+        "missed_color": 0.0007825250966977441
+      },
+      "release": {
+        "ab_error": 12.0440673828125,
+        "patch_excess": 0.339896023273468,
+        "color_coverage": 0.067352294921875,
+        "missed_color": 0.3461667449191763
+      }
+    },
+    {
+      "index": 941,
+      "old_space": {
+        "ab_error": 11.803794860839844,
+        "patch_excess": 1.020538091659546,
+        "color_coverage": 0.15338134765625,
+        "missed_color": 0.613625304136253
+      },
+      "release": {
+        "ab_error": 11.58432674407959,
+        "patch_excess": 0.5445202589035034,
+        "color_coverage": 0.40020751953125,
+        "missed_color": 0.032907542579075424
+      }
+    },
+    {
+      "index": 1746,
+      "old_space": {
+        "ab_error": 21.40471076965332,
+        "patch_excess": 2.445641279220581,
+        "color_coverage": 0.553466796875,
+        "missed_color": 0.26700241575564015
+      },
+      "release": {
+        "ab_error": 16.30540657043457,
+        "patch_excess": 0.5714777708053589,
+        "color_coverage": 0.1327056884765625,
+        "missed_color": 0.39769889039020595
+      }
+    },
+    {
+      "index": 584,
+      "old_space": {
+        "ab_error": 20.1906681060791,
+        "patch_excess": 1.2620389461517334,
+        "color_coverage": 0.69354248046875,
+        "missed_color": 0.09630933556105857
+      },
+      "release": {
+        "ab_error": 22.57025909423828,
+        "patch_excess": 1.746338963508606,
+        "color_coverage": 0.646820068359375,
+        "missed_color": 0.1843243727063878
+      }
+    },
+    {
+      "index": 1435,
+      "old_space": {
+        "ab_error": 21.27211570739746,
+        "patch_excess": 5.1058244705200195,
+        "color_coverage": 0.6849822998046875,
+        "missed_color": 0.35429673620628394
+      },
+      "release": {
+        "ab_error": 11.184368133544922,
+        "patch_excess": 0.9250662922859192,
+        "color_coverage": 0.50732421875,
+        "missed_color": 0.014263235368763007
+      }
+    },
+    {
+      "index": 1955,
+      "old_space": {
+        "ab_error": 7.787717819213867,
+        "patch_excess": 1.0435097217559814,
+        "color_coverage": 0.270172119140625,
+        "missed_color": 0.2432694031188385
+      },
+      "release": {
+        "ab_error": 12.496732711791992,
+        "patch_excess": 0.31601670384407043,
+        "color_coverage": 0.7804718017578125,
+        "missed_color": 0.0
+      }
+    },
+    {
+      "index": 1047,
+      "old_space": {
+        "ab_error": 12.725871086120605,
+        "patch_excess": 1.604668140411377,
+        "color_coverage": 0.195526123046875,
+        "missed_color": 0.4522170570355802
+      },
+      "release": {
+        "ab_error": 12.001117706298828,
+        "patch_excess": 0.2767108678817749,
+        "color_coverage": 0.17236328125,
+        "missed_color": 0.46093330949401035
+      }
+    },
+    {
+      "index": 1689,
+      "old_space": {
+        "ab_error": 26.23225212097168,
+        "patch_excess": 1.7044408321380615,
+        "color_coverage": 0.58978271484375,
+        "missed_color": 0.15641351282702565
+      },
+      "release": {
+        "ab_error": 17.07444953918457,
+        "patch_excess": 0.4091215431690216,
+        "color_coverage": 0.90069580078125,
+        "missed_color": 0.0014901363136059606
+      }
+    },
+    {
+      "index": 772,
+      "old_space": {
+        "ab_error": 6.426523208618164,
+        "patch_excess": 0.38687315583229065,
+        "color_coverage": 0.258514404296875,
+        "missed_color": 0.26649261974093785
+      },
+      "release": {
+        "ab_error": 6.300887107849121,
+        "patch_excess": 0.348586767911911,
+        "color_coverage": 0.2451171875,
+        "missed_color": 0.32392810523144894
+      }
+    },
+    {
+      "index": 618,
+      "old_space": {
+        "ab_error": 13.832884788513184,
+        "patch_excess": 1.9853154420852661,
+        "color_coverage": 0.485137939453125,
+        "missed_color": 0.20293154973672975
+      },
+      "release": {
+        "ab_error": 14.936275482177734,
+        "patch_excess": 0.5301600694656372,
+        "color_coverage": 0.8293914794921875,
+        "missed_color": 0.0007115411982353779
+      }
+    },
+    {
+      "index": 336,
+      "old_space": {
+        "ab_error": 16.60566520690918,
+        "patch_excess": 1.2380704879760742,
+        "color_coverage": 0.4294891357421875,
+        "missed_color": 0.08609339996553507
+      },
+      "release": {
+        "ab_error": 14.536388397216797,
+        "patch_excess": 1.1959733963012695,
+        "color_coverage": 0.43182373046875,
+        "missed_color": 0.1851456143374117
+      }
+    },
+    {
+      "index": 1086,
+      "old_space": {
+        "ab_error": 17.58598518371582,
+        "patch_excess": 1.7815990447998047,
+        "color_coverage": 0.70526123046875,
+        "missed_color": 0.0451198129748685
+      },
+      "release": {
+        "ab_error": 8.847654342651367,
+        "patch_excess": 0.4222590923309326,
+        "color_coverage": 0.053924560546875,
+        "missed_color": 0.43115137346580945
+      }
+    },
+    {
+      "index": 2140,
+      "old_space": {
+        "ab_error": 7.6119256019592285,
+        "patch_excess": 0.15633070468902588,
+        "color_coverage": 0.7803955078125,
+        "missed_color": 0.0044853635505193576
+      },
+      "release": {
+        "ab_error": 9.672757148742676,
+        "patch_excess": 0.08361931890249252,
+        "color_coverage": 0.7842254638671875,
+        "missed_color": 0.001731192949323261
+      }
+    },
+    {
+      "index": 1994,
+      "old_space": {
+        "ab_error": 23.052637100219727,
+        "patch_excess": 4.873438835144043,
+        "color_coverage": 0.569427490234375,
+        "missed_color": 0.049524982406755805
+      },
+      "release": {
+        "ab_error": 17.308002471923828,
+        "patch_excess": 1.5104169845581055,
+        "color_coverage": 0.5511016845703125,
+        "missed_color": 0.014250527797325828
+      }
+    },
+    {
+      "index": 451,
+      "old_space": {
+        "ab_error": 10.520956993103027,
+        "patch_excess": 1.2838455438613892,
+        "color_coverage": 0.65618896484375,
+        "missed_color": 0.016560718085831993
+      },
+      "release": {
+        "ab_error": 9.030373573303223,
+        "patch_excess": 0.754244327545166,
+        "color_coverage": 0.6208953857421875,
+        "missed_color": 0.035385916568902956
+      }
+    },
+    {
+      "index": 1807,
+      "old_space": {
+        "ab_error": 17.55420684814453,
+        "patch_excess": 3.6267919540405273,
+        "color_coverage": 0.8811798095703125,
+        "missed_color": 0.03126752664049355
+      },
+      "release": {
+        "ab_error": 16.857818603515625,
+        "patch_excess": 0.4508571922779083,
+        "color_coverage": 0.965179443359375,
+        "missed_color": 0.0
+      }
+    },
+    {
+      "index": 194,
+      "old_space": {
+        "ab_error": 21.62356185913086,
+        "patch_excess": 3.4757049083709717,
+        "color_coverage": 0.4154815673828125,
+        "missed_color": 0.3036251799502683
+      },
+      "release": {
+        "ab_error": 17.168527603149414,
+        "patch_excess": 1.7961444854736328,
+        "color_coverage": 0.7869110107421875,
+        "missed_color": 0.006255725690354666
+      }
+    },
+    {
+      "index": 1636,
+      "old_space": {
+        "ab_error": 18.11170768737793,
+        "patch_excess": 2.316526174545288,
+        "color_coverage": 0.4608001708984375,
+        "missed_color": 0.2738500960922486
+      },
+      "release": {
+        "ab_error": 17.05701446533203,
+        "patch_excess": 0.8802337646484375,
+        "color_coverage": 0.3453216552734375,
+        "missed_color": 0.262780269058296
+      }
+    },
+    {
+      "index": 409,
+      "old_space": {
+        "ab_error": 21.841514587402344,
+        "patch_excess": 2.8149540424346924,
+        "color_coverage": 0.5799102783203125,
+        "missed_color": 0.07750204292288504
+      },
+      "release": {
+        "ab_error": 21.5656795501709,
+        "patch_excess": 0.5761880278587341,
+        "color_coverage": 0.636871337890625,
+        "missed_color": 0.043051911745731364
+      }
+    },
+    {
+      "index": 2471,
+      "old_space": {
+        "ab_error": 16.08145523071289,
+        "patch_excess": 2.2105460166931152,
+        "color_coverage": 0.7911224365234375,
+        "missed_color": 0.02534622878306507
+      },
+      "release": {
+        "ab_error": 17.141895294189453,
+        "patch_excess": 0.7329339981079102,
+        "color_coverage": 0.7151947021484375,
+        "missed_color": 0.037562970634182305
+      }
+    },
+    {
+      "index": 665,
+      "old_space": {
+        "ab_error": 19.746185302734375,
+        "patch_excess": 2.317701578140259,
+        "color_coverage": 0.7936553955078125,
+        "missed_color": 0.09188258199790325
+      },
+      "release": {
+        "ab_error": 14.18701457977295,
+        "patch_excess": 0.9515336751937866,
+        "color_coverage": 0.8133697509765625,
+        "missed_color": 0.05256851879586641
+      }
+    },
+    {
+      "index": 2151,
+      "old_space": {
+        "ab_error": 17.301462173461914,
+        "patch_excess": 0.5416412353515625,
+        "color_coverage": 0.3140869140625,
+        "missed_color": 0.5995582777385642
+      },
+      "release": {
+        "ab_error": 22.86566162109375,
+        "patch_excess": 0.31695353984832764,
+        "color_coverage": 0.8281402587890625,
+        "missed_color": 0.020811038502698147
+      }
+    },
+    {
+      "index": 1377,
+      "old_space": {
+        "ab_error": 12.53142261505127,
+        "patch_excess": 2.1505064964294434,
+        "color_coverage": 0.8076019287109375,
+        "missed_color": 0.01162006310521162
+      },
+      "release": {
+        "ab_error": 14.857101440429688,
+        "patch_excess": 1.1797388792037964,
+        "color_coverage": 0.5686492919921875,
+        "missed_color": 0.08688934827548689
+      }
+    },
+    {
+      "index": 246,
+      "old_space": {
+        "ab_error": 16.83350372314453,
+        "patch_excess": 1.9284921884536743,
+        "color_coverage": 0.5128631591796875,
+        "missed_color": 0.0004520182615377661
+      },
+      "release": {
+        "ab_error": 9.959344863891602,
+        "patch_excess": 0.281173974275589,
+        "color_coverage": 0.2016754150390625,
+        "missed_color": 0.1439678162997785
+      }
+    },
+    {
+      "index": 1679,
+      "old_space": {
+        "ab_error": 5.608643531799316,
+        "patch_excess": 1.0197176933288574,
+        "color_coverage": 0.28912353515625,
+        "missed_color": 0.13227684346701166
+      },
+      "release": {
+        "ab_error": 4.4221906661987305,
+        "patch_excess": 0.4705710709095001,
+        "color_coverage": 0.210845947265625,
+        "missed_color": 0.023673997412677877
+      }
+    },
+    {
+      "index": 2332,
+      "old_space": {
+        "ab_error": 13.967047691345215,
+        "patch_excess": 3.781674861907959,
+        "color_coverage": 0.5753173828125,
+        "missed_color": 0.03037200832466181
+      },
+      "release": {
+        "ab_error": 7.873258590698242,
+        "patch_excess": 0.19574034214019775,
+        "color_coverage": 0.108612060546875,
+        "missed_color": 0.39815296566077
+      }
+    }
+  ],
+  "median_pipeline_seconds": 0.06851194500001156,
+  "torch": "2.8.0+cu128",
+  "device": "NVIDIA L4",
+  "checkpoint": "round6 palette9000",
+  "limitations": "Previously inspected development/reporting set, no independent human ratings. Exact hue error is auxiliary."
+}

QA.json

@@ -0,0 +1,55 @@
+{
+  "parameters": 3994676,
+  "torch": "2.8.0+cu128",
+  "tests": [
+    {
+      "size": [
+        1,
+        1
+      ],
+      "alpha": "exact",
+      "max_L_error": 0.0753021240234375,
+      "seconds": 0.03764470492023975
+    },
+    {
+      "size": [
+        17,
+        23
+      ],
+      "alpha": "exact",
+      "max_L_error": 0.17739105224609375,
+      "seconds": 0.019733823952265084
+    },
+    {
+      "size": [
+        320,
+        191
+      ],
+      "alpha": "exact",
+      "max_L_error": 0.2049694061279297,
+      "seconds": 0.15181890805251896
+    },
+    {
+      "size": [
+        193,
+        320
+      ],
+      "alpha": "exact",
+      "max_L_error": 0.21184539794921875,
+      "seconds": 0.20581824099645019
+    },
+    {
+      "size": [
+        1024,
+        768
+      ],
+      "alpha": "exact",
+      "max_L_error": 0.2049694061279297,
+      "seconds": 1.8695425690384582
+    }
+  ],
+  "gradio_config_components": 11,
+  "ui_function_all_modes": "passed",
+  "gradio_http_request": "passed",
+  "onnx_max_abs_error": 0.000911712646484375
+}

README.md

@@ -3,78 +3,75 @@ license: apache-2.0
 pipeline_tag: image-to-image
 tags:
 - colorization
-- unet
+- image-colorization
 - pytorch
-- safetensors
 - onnx
-datasets:
-- johnowhitaker/imagenette2-320
-- detection-datasets/coco
+- mobilenet-v3
+- small-model
+library_name: pytorch
 ---
-# Mini U-Net Colorizer — broader-data trained candidate
 
-**Status: evaluated app-testing candidate.** Some broad color patches and
-incorrect object hues remain. Predicted colors are not evidence of original
-historical colors.
+# Mini Photo Colorizer — v3.0
 
-This checkpoint has 3,968,892 learned parameters and 236 fixed color bins.
-It starts from the audited bin-mapping repair of main commit
-`6c47ea40724d8fcd67d4f36ce837dc1cb5b1b2a8` and changes all 65 learned parameter
-tensors. The color vocabulary is unchanged. The selected weights are update
-748 of a completed 1,122-update BF16 L4 run using a 17,325-photo mixed training
-pool (11,943 Imagenette plus 5,382 COCO), batch 32, initial learning rate 1e-5,
-weighted classification loss and frozen BatchNorm running statistics.
+A compact automatic photo colouriser with **3,994,676 learned parameters in total**, including the complete deployed MobileNetV3 encoder. It predicts plausible colours from grayscale photographs. No teacher, critic, external semantic model, retrieval service or ensemble is needed at inference.
 
-Selection compared Imagenette50 and reserved COCO200 validation images.
-The selected model retained color strength better than spatial-loss candidates.
-It was then scored on separate Imagenette200 and COCO-val100 checks.
+## Release contents
 
-| Test sample | Previous repaired error | This release error | Fine excess-edge reduction |
-|---|---:|---:|---:|
-| Imagenette 200 | 13.318 | 12.847 | 85.8% |
-| COCO-val 100 | 15.266 | 14.532 | 84.3% |
+- `model.safetensors` and `config.json`: the selected checkpoint.
+- `semantic_model.py`: the complete architecture and strict checkpoint loader.
+- `inference.py`: Python API and command-line image colourisation.
+- `colorizer.onnx`: equivalent fixed 256×256 network graph, with float Lab `ab` output.
+- `app.py` and `requirements-space.txt`: the tested Gradio / ZeroGPU application.
+- `RELEASE_REPORT.md`, `QA.json` and `SHA256SUMS.json`: selection evidence, runtime checks and file hashes.
 
-Error is mean Lab chroma distance. The release includes guided8 decoding;
-raw learned weights alone improve error by 1.97% and 3.25%, respectively.
-Excess-edge reductions are proxies, not counts of visible blotches removed.
-COCO is a convenience sample; older upstream training exposure is unknown.
+## Use
 
-## Use the complete pipeline
+Download this repository, then:
 
 ```bash
-python -m pip install -r requirements.txt
-python inference.py --model . --output-dir colorized photo.jpg
+pip install -r requirements.txt
+python inference.py input.jpg output.png --model . --device cpu
 ```
 
+For CUDA, use `--device cuda`. Python API:
+
 ```python
 from PIL import Image
-from model import load_model
-from inference import colorize
-model = load_model('.')
-colorize(model, Image.open('photo.jpg')).save('colorized.png')
+from inference import load_colorizer, colorize
+
+model = load_colorizer('.', 'cpu')
+output = colorize(model, Image.open('input.jpg'))
+output.save('output.png')
 ```
 
-Defaults: temperature 0.38, guided radius 8, epsilon 0.001, one network pass.
-The wrapper preserves aspect ratio and original luminance. Old app code that
-only loads safetensors will not automatically gain guided filtering.
+Default processing uses a 256-pixel maximum network side and retains aspect ratio. The output keeps the input resolution, orientation and alpha, up to 12 megapixels. Original Lab lightness is retained; colour is upsampled with a lightness-guided local linear model and compressed into the sRGB gamut. Quantisation can cause small lightness differences.
 
-For ONNX without PyTorch:
+`saturation=1.0` is the default. Values between 0 and 1.5 are supported. Smoothing radius defaults to 8 at network resolution; 4 and 16 are available for gentler or stronger smoothing.
 
-```bash
-python -m pip install -r requirements-onnx.txt
-python colorize_onnx.py --model colorizer.onnx --output-dir colorized photo.jpg
-```
+## Architecture and training
+
+MobileNetV3 Large feature encoder, 128-channel feature pyramid, 16 colour queries and two attention blocks. The decoder produces a shared palette and spatial assignment masks with a bounded local residual. The ImageNet classifier is discarded, and every remaining learned parameter is included in the count above. There are 5,324 parameters of headroom below the strict four-million limit.
+
+Training uses 16,230 filtered photographs from pinned Imagenette and COCO parquet files, with ImageNet pretrained encoder features and DDColor artistic targets. The final selection and any fine-tuning are documented in `RELEASE_REPORT.md`. Data revisions, training scripts and historical experiments are retained under `experiments/`.
+
+Teacher source and checkpoint references:
+
+- [DDColor](https://arxiv.org/abs/2212.11613), artistic checkpoint revision `aa10f72fffc89a6658e37b48556050b4d9a26f63`.
+- [TorchVision MobileNetV3 Large](https://docs.pytorch.org/vision/0.21/models/generated/torchvision.models.mobilenet_v3_large.html), ImageNet V2 encoder initialization.
+- [PalGAN](https://arxiv.org/abs/2210.11204) informed palette and realism experiments; this implementation is not a reproduction.
+
+## Intended use and limits
+
+Intended for adding plausible colour to ordinary photographs and consumer photo applications. A grayscale image can admit several equally plausible colours. Outputs must not be presented as recovered historical fact.
+
+Known limitations include muted or warm/sepia colour choices, incorrect clothing and object hues, residual colour bleeding around small objects, and poor results on unusual surfaces or scenes. Severe scan damage, astronomical images and illustrations are outside the principal evaluation domain. The model does not repair scratches or reconstruct lost detail. Surface consistency is not the same as assigning a uniform colour to an entire patterned object.
+
+Metrics against an original colour image are auxiliary because that original may not be inferable. The report includes visual review and colour-retention diagnostics. Upstream pretraining overlap is possible; the evaluation is not a guarantee of unseen content or universal quality. No claim is made that further improvements below four million parameters are impossible.
+
+## Migration from the old U-Net
 
-The 15.9MB ONNX graph includes the model and guided decoder, with dynamic
-batch/spatial sizes and verified PyTorch parity. See `DEPLOYMENT.md` for the
-Lab input contract, CPU timings, publication commands and integration limits.
-See `RESEARCH_ROUND2.md` and `reports/round2/` for complete measured evidence.
+This release changes the architecture. The old U-Net class and colour-bin decoder cannot load these weights. Use `semantic_model.py` and `inference.py` together with the new checkpoint. The network directly returns Lab `ab`; do not apply the old bin softmax or temperature decoder. Prior main commits and the user-managed `stable` branch remain available. Old root-level training and ONNX helpers are archived under `legacy/v2/` to avoid silently mixing architectures.
 
-## Limitations
+## ONNX
 
-Smoothing removes fine color fluctuations but can suppress true small color
-details, especially without luminance boundaries. Semantically wrong hues
-remain. The coffee and rocket failure examples are retained. Browser/mobile
-performance, video consistency and general production quality are unvalidated.
-The separate experiment bundle contains all runs and reproduction code; GPU
-optimizer state is not included. This is a weights-only continuation point.
+The ONNX graph accepts float32 `L` shaped `[1,1,256,256]`, normalized as `L_lab / 50 - 1`, and returns float32 Lab `ab` shaped `[1,2,256,256]`. It contains only the compact network. Image loading, resizing, guided upsampling and gamut compression are handled by the Python pipeline, not embedded in the graph. See `colorizer.json` for its contract. The fixed-size export is numerically compared with PyTorch before release.

RELEASE_MANIFEST.json

@@ -0,0 +1,16 @@
+{
+  "release": "v3.0.0",
+  "selected": "round6 palette step9000",
+  "selected_source_revision": "7b10485ee9d205ce2f7b660dfc6a90012d78b1cb",
+  "parameters": 3994676,
+  "previous_main_commit": "45011cd907b845d44f627db4e387678800261257",
+  "previous_space_commit": "ab8faf4771154605d5dbecf084f2a01f32704efb",
+  "model_sha256": "ec1f27d74533adc83f7ab3639a091fc4d8738a434dafc7d172c7873c28a9e715",
+  "engineering_qa": "QA.json",
+  "pipeline_eval": "PIPELINE_EVAL.json",
+  "critic_runs_rejected": [
+    "realism_low_v2",
+    "realism_high_v2"
+  ],
+  "scope": "Final tested release from this project; not a proof of optimality or historical colour truth."
+}

RELEASE_REPORT.md

@@ -0,0 +1,63 @@
+# Final selection — Mini Photo Colorizer v3.0
+
+## Decision
+Release the round6 palette checkpoint at step9000 with the new, verified image pipeline. All 3,994,676 learned parameters, including the encoder, are in model.safetensors. No discriminator, teacher, second model or weight ensemble is loaded in production.
+
+The final two training runs tested conditional colour critics with strengths0.04 and0.12. Both completed 2,500 fine-tuning updates, with checkpoints saved and verified every500 updates. They produced stronger colours in some images but reintroduced local colour patches. They were rejected after visual review and matched reporting. Two earlier startup attempts failed on a typed optimiser argument before training; that argument was corrected. Every successful run is retained under experiments/final-20260928.
+
+## Matched 80-image reporting set
+78 images had appreciable original colour. These are repeated reporting/development images, not an independent unseen benchmark.
+
+| Checkpoint | Blotch proxy (lower) | Missed colour (lower) | Colour coverage |
+|---|---:|---:|---:|
+| Selected round6 palette9000 | 0.779 | 0.169 | 0.474 |
+| Gentle colour critic | 1.070 | 0.170 | 0.487 |
+| Strong colour critic | 1.413 | 0.171 | 0.497 |
+
+The critics increased the patchiness measure by about37% and81%. On reviewed images, this corresponded to red patches on faces, small coloured areas within otherwise consistent objects, and colour bleeding. More saturation did not make them better releases.
+
+Round7's four objective/degradation variants were also rejected: they were visually almost unchanged and did not improve blotches.
+
+## What improves over the previously deployed app
+The previous Space used the old v2 U-Net. The release uses pretrained semantic features and a shared palette. In the prior pinned300-image fresh COCO comparison (272 chromatic images), selected round6 lowered the patch-excess proxy from1.714 to0.747 and missed-colour fraction from0.223 to0.159. Those are approximately56% and29% reductions under that evaluation pipeline, not universal guarantees.
+
+The production image pipeline additionally retains aspect ratio, uses original-resolution lightness to guide chroma upsampling, preserves EXIF orientation and alpha, checks the image-size limit, compresses out-of-gamut chroma, and reports input errors. See the actual pipeline comparison appended below for its distinct measurements.
+
+## Verification
+QA.json records CPU inference on tiny, portrait, landscape and1024×768 images; exact alpha retention; worst observed lightness difference below0.22 Lab L after8-bit quantisation; black/white and saturation-zero behaviour; Gradio function and HTTP calls; and ONNX parity with maximum observed difference0.000912 Lab units. These are engineering tests, not evidence of historical colour accuracy.
+
+The Space pins the model release commit and uses the same tested source. ZeroGPU GPU operations are isolated in a decorated function; full-resolution rendering runs on CPU. Separate live Space verification is recorded in LIVE_SPACE_CHECK.json when completed.
+
+## Evidence and provenance
+- [Final low-critic training](experiments/final-20260928/realism_low_v2/)
+- [Final high-critic training](experiments/final-20260928/realism_high_v2/)
+- [Round7 review](experiments/round7-20260928/REVIEW.md)
+- [Round6 selected checkpoint and evaluation](experiments/round6-20260928/RESULTS.md)
+- [Actual release pipeline comparisons](experiments/final-20260928/pipeline_eval/)
+
+## Limits
+The release may choose muted, warm or incorrect colours and can still show residual bleeding. Real archival evaluation is limited, and two familiar historical examples are not representative of the entire domain. The moon remains an out-of-domain failure. There is no basis to claim that all further improvement below4M parameters is impossible. This is the selected, tested final release from these experiments; it is not a guarantee of perfect colourisation.
+
+## Actual production image pipeline comparison
+
+{
+  "n_total": 80,
+  "n_color": 78,
+  "summary": {
+    "old_space": {
+      "ab_error": 16.144625015747852,
+      "patch_excess": 1.8169478370020022,
+      "color_coverage": 0.47298392271384215,
+      "missed_color": 0.24084079671968467
+    },
+    "release": {
+      "ab_error": 14.243927399317423,
+      "patch_excess": 0.6932277647444071,
+      "color_coverage": 0.479247068747496,
+      "missed_color": 0.1663338435453805
+    }
+  },
+  "median_pipeline_seconds_L4": 0.06851194500001156
+}
+
+This comparison preserves aspect ratio and original output resolution before measuring the resized results. Median pipeline time excludes ZeroGPU queue/allocation and network transfer.

SHA256SUMS.json

@@ -1,44 +1,23 @@
 {
-  "DEPLOYMENT.md": "089cadec89caa645a5f2617f869ec50186dd8db574b0680a51d4bc12f84b96cb",
-  "README.md": "f05ab35140319d6d8d5a65669d62645e3909b1ec1bd233bd66e0af3c1b135eb3",
-  "RESEARCH_REPORT.md": "6730cf20f7a584707fb0c084b882ac87db1ef858d72e7d5e716e5e0d382ddca1",
-  "RESEARCH_ROUND2.md": "19f42c72003cb685f46b315105ad2d4e62a10a7e0cd1455ab11db51bd5083728",
-  "colorization_project_log.md": "66dbd61e5e45f208fdd36525f19c232678892295d6b31882a5fb71627cb731b9",
-  "colorize_onnx.py": "4ec6bc9dba4a998243e97b3bd824d25639455e6246a47886be1ee796121cf1ba",
-  "colorizer.json": "9f1db0072e91747bd6e9d6de1e2387440a4a2e0669554e499bbf29288a9758cd",
-  "colorizer.onnx": "0ef86749901e66ad53b1e8e1d940330572e2f4c9347ac01e7bc02c7683f8c79a",
-  "config.json": "90299ee25ee3c3e645b362ddbd5a859b9e739c2a0a1c8a5e9ea79df171288bff",
-  "export_onnx.py": "4b0b8494f0eba3e813457fe393c3b96ce1ab35fefcf5f63a9251f4e852552737",
-  "inference.py": "db958511d7a9eecec4c5730d96ac3f0005e002720b1a7f4b035e29cac7e7c5e3",
-  "model.py": "4cc57f82ffd6378bdf23a088ce7a1ed56c09e5673de3ee5232b8ee1cacc9be0a",
-  "model.safetensors": "0e4c417375684a044860f8af3ac3a2fb44e1a5729254ca33abda758ea71aea6e",
-  "reports/round2/coco_manifest.json": "80061d796a1e4f08b508203cd45513916f2f0e74efa0c516673413c44f9d6dcb",
-  "reports/round2/coco_revision.json": "c83949c5adf6e0e29dfb1d37c6beff0044bfa6a6a7161a6e0264bdbf41afd450",
-  "reports/round2/coco_validation200.json": "bf6adcb05a2a0f92a4f428073ff95ff9977064a2a99b3b911ee5c3a5797955ea",
-  "reports/round2/environment-lock.txt": "f95748796cbc5d0667fe17163b6054fb70567a9e87206473e743d150adc26e45",
-  "reports/round2/final_coco100.json": "dabe07889d4ce4fc512f60768aa5c3c6268060464e21aed9c4c1fe28294675a1",
-  "reports/round2/final_coco100.png": "2ba6c18c60e7858574f45f1fe6b1d25ef14031d8b92a3986ec057f5c945c337e",
-  "reports/round2/final_integrity.json": "de32a8c9173efdc112c776a4937a5024b61814e93b16818eeccf2c43bc60b62a",
-  "reports/round2/final_results.json": "40e2e317c3d083be9dedefdcc0ce942d0b972fd64164201680a6aeab589a870b",
-  "reports/round2/final_test200.json": "d525d24e8706ff3f7ee3478c1ab95b8d5875d0d8242f6389dc29b9416449ce63",
-  "reports/round2/final_test_comparison.png": "9681e45700aa5def0f69f67a49a45cadfddb06c1dc4b321995e09641eebf7f73",
-  "reports/round2/final_visual.json": "0ca89a7d8017046c085c7983374706df0c1970284d95a8519cf16bf4d65065a8",
-  "reports/round2/final_visual.png": "df2b3c271150059ab2f0d0a10f7fe889f1d3878c6096e14e0fd5df13edd7022a",
-  "reports/round2/hub_refs.json": "e714d59b825a333abbea48270353a8dffd5c1b1b8b629028a729fac063f7cbd8",
-  "reports/round2/jobs.json": "aa8dc41c57ae6ee41b5e51e8aff09055dafb536424413240cbeff3fcbabcbacc",
-  "reports/round2/manifest.json": "adaf3a771a4c1cd3e1c58e6d74eae2a164e1d00ddbca8232067711111caa62ea",
-  "reports/round2/onnx_benchmark.json": "2afbcbd29f9619dcc0cad1954f8fe2af3fdd11b94235b53883e8e0db53ef67f0",
-  "reports/round2/onnx_export.json": "9f1db0072e91747bd6e9d6de1e2387440a4a2e0669554e499bbf29288a9758cd",
-  "reports/round2/selection_protocol.md": "c297f6141a6c5419c2d6bba4ea1ecb5ce7295a78f9d16abec9e38224d5000a7b",
-  "reports/round2/tests-final.txt": "60e907edbabdfcc838d135fbd18b7733ab87c401bbf608c734f589abcc4687f8",
-  "reports/round2/weight_selection.json": "5ca680f16fab8fedb1ca1a14f59a127ee5d5a71e21fb3560f78417b530201df0",
-  "requirements-onnx.txt": "c243944cabecd501038b8027dc5fd08f6d2ce74bcc47cc121f5c8df1b8c4445c",
-  "requirements.txt": "a5b6a1804d983178099da00bad2f92a4196009384e431119cc73c5433d249622",
-  "spatial.py": "d13abe399ef049e21a6459a7003461afaae0c00e0c560262c6cf375de4c9884a",
-  "training/color_statistics.npz": "1d14920885324137169e63f908a413ebf083e8db1e604d2333847fd2094f36a6",
-  "training/environment.txt": "ee1e54f3b86a977f74fbc0283ce0cfd2fcf54cc4c8ec4b9096634746eadcc18b",
-  "training/history.json": "714ff0c8364e33e75cff21b6abe94f78db6c4536faf016ad1f591eb0ebb7dc72",
-  "training/run_config.json": "6cdd4da9e0ae293e8f1895dd03d28bfb1f45c3abf19fc147cd8c18e6dfd36559",
-  "training/split_manifest.json": "dc5901733751e8585f959918e46ce75b520c6e241a79d26ab9b3df943a12ac38",
-  "upload_main.py": "d59fe5ebfc27f6051b7e7c6d8ad66b23092fa61b3db9fc87b33bff0fad2b483a"
+  "DEPLOYMENT.md": "201879644b48093363f025589641bc2a264ec8097512b4b4c30b621f3b9d9ee6",
+  "PIPELINE_EVAL.json": "595be88704d580c01a3c4dd642409b3dc5dd25e86ca1c7eb40a696605f181a19",
+  "QA.json": "b249b1d49045e31b0bf85f9e01515b91a72c4dd973963751c30d14272d262b90",
+  "README.md": "5ade5fd9022a03937b91fbd3b0fa653ae93c068034b54b35677c3db47a9ccc59",
+  "RELEASE_MANIFEST.json": "872eebfb322c8990b5e6ac493e4e4068b87f8daac0ddf219b8b55299514ca03c",
+  "RELEASE_REPORT.md": "69677ec5e13f5c1249f59b01c31ed1b0f1588bddc216bce9167b5d31423a5574",
+  "app.py": "58be79b62642c2f3393860791a1a7b39d8f2e83ac79caf6545839124ec787404",
+  "colorization_project_log.md": "699238b4078fca93b15f4f2d951e439651502338dac4bf3a5b5a6d0b0449de21",
+  "colorize_image.py": "9a85b7633bdf8a0d63f740ae69ed76644bb2087da4b21f8c1e01ca804cd4e6b2",
+  "colorize_onnx.py": "cc106f066878a7372f4260279620238d46a3841baf09fbbe954f61a684199d05",
+  "colorizer.json": "7d444d5f560b2ea6a070f73750f75f66aa2c61d3dc21a8e4300ed5f5196da179",
+  "colorizer.onnx": "911fb777328fcfbeeb89cc25dca70092cf2de4686ede1edd44a8ccebc89ea341",
+  "config.json": "eaeb49b39f9116bfed0d954e81852dc93476298752787dba88a63c0eec97ccec",
+  "export_onnx.py": "f46a413c2b1b2a6e130cb7d2ad8d6d69c16a16955bf830efdc4c04c30d47ca60",
+  "inference.py": "0ac1f382205b42cef0afaa9173017fa660e6859194a65a61b9b9052c437cd476",
+  "model.py": "31628744fb5d362d91342063c90eb38b2b97fda8c91e303e4a58b6f388f53c55",
+  "model.safetensors": "ec1f27d74533adc83f7ab3639a091fc4d8738a434dafc7d172c7873c28a9e715",
+  "requirements-onnx.txt": "9bcca098a9da63b31fb9d803dfd7f99b753ad125ee9bce3a5bbe52e368739e11",
+  "requirements-space.txt": "4c7f918aadc4afb31ec6808131570f9978cf0bcf9e2af562e93adc749e3245cf",
+  "requirements.txt": "c855eb70020dc89f71fd38e44a0be2cfb80f2fe3d442d5ba45c91398c336f83f",
+  "semantic_model.py": "b019358cbcaa214743cbd244d20eb6e59eeff0ab5264093ec0927be8529b25a2"
 }

app.py

@@ -0,0 +1,47 @@
+"""Gradio and ZeroGPU entry point. The model revision is pinned at release."""
+import os
+from pathlib import Path
+import spaces
+import torch
+import gradio as gr
+from huggingface_hub import snapshot_download
+from inference import load_colorizer, prepare, chroma_coefficients, render
+
+REPO=os.getenv('MODEL_ID','User-2468/mini-unet-colorizer')
+REV=os.getenv('MODEL_REVISION','v3.0.0')
+CPU=os.getenv('ZEROGPU_CPU_TEST')=='1'
+DEVICE='cpu' if CPU else 'cuda'
+if CPU:torch.set_num_threads(min(4,os.cpu_count() or 1))
+path=Path(REPO)
+if not path.is_dir():path=Path(snapshot_download(REPO,revision=REV,allow_patterns=['model.safetensors','config.json']))
+MODEL=load_colorizer(path,DEVICE)
+
+@spaces.GPU(duration=20)
+def infer(small,radius):
+    return chroma_coefficients(MODEL,small,int(radius))
+
+def run(image,strength,smoothing):
+    if image is None:raise gr.Error('Upload a photograph first.')
+    radius={'Balanced':8,'Gentle':4,'Strong':16}[smoothing]
+    try:
+        light,alpha,small=prepare(image,256)
+        coefficients=infer(small,radius)
+        result=render(light,alpha,coefficients,strength)
+    except (ValueError,RuntimeError,TypeError) as exc:
+        raise gr.Error(str(exc)) from exc
+    return result
+
+with gr.Blocks(title='Mini Photo Colorizer') as demo:
+    gr.Markdown('# Mini Photo Colorizer\nAdd plausible colour to a black-and-white photograph. Original colours may be unknowable.')
+    with gr.Row():
+        source=gr.Image(type='pil',image_mode='RGBA',label='Original photograph',sources=['upload','clipboard'],height=440)
+        result=gr.Image(type='pil',label='Colourised photograph',format='png',height=440)
+    with gr.Row():
+        strength=gr.Slider(0,1.5,value=1.,step=.05,label='Colour strength')
+        smoothing=gr.Radio(['Gentle','Balanced','Strong'],value='Balanced',label='Colour smoothing')
+    button=gr.Button('Colourise',variant='primary')
+    button.click(run,[source,strength,smoothing],result,api_name='colorize',concurrency_limit=1)
+    gr.ClearButton([source,result])
+    gr.Markdown('3.995 million parameters · Full-resolution output, up to 12 megapixels · PNG download\n\nBest suited to ordinary photographs. Colours can be muted or inaccurate on unusual scenes, tiny objects and heavily damaged scans.')
+demo.queue(default_concurrency_limit=1,max_size=12)
+if __name__=='__main__':demo.launch()

colorization_project_log.md

@@ -249,3 +249,8 @@ All GPU weights were recovered through checksum-verified artifact transport;
 best/last weights and experiment records are retained. Main and stable remain
 unchanged. The saved release includes a guarded uploader targeting main.
 The current candidate is release-v2; release/ preserves the earlier repair.
+
+
+## Final release — 28 September 2026
+
+Selected round6 palette9000 after rejecting round7 and final critic variants. All3,994,676 parameters include the encoder. Root files now use SemanticColorizer, with aspect-preserving guided colour upsampling, gamut compression, CPU/CUDA support, fixed256 ONNX and Gradio/ZeroGPU app. See RELEASE_REPORT.md, RELEASE_MANIFEST.json and QA.json. Stable branch unchanged.

colorize_image.py

@@ -1,176 +1,2 @@
-# /// script
-# requires-python = ">=3.10"
-# dependencies = [
-#     "torch>=2.3",
-#     "torchvision>=0.18",
-#     "huggingface_hub>=0.24",
-#     "safetensors>=0.4",
-#     "scikit-image>=0.22",
-#     "pillow>=10.0",
-#     "numpy",
-# ]
-# ///
-"""
-Colorize photos with a SmallUNetColorizer checkpoint trained by colorize_train.py
-(classification-head version: predicts a distribution over quantized Lab ab
-bins per pixel, decoded with an annealed mean).
-
-Usage:
-    uv run colorize_image.py --model User-2468/mini-unet-colorizer photo.jpg
-    uv run colorize_image.py --model ./local_checkpoint --temperature 0.2 a.jpg b.jpg
-
---temperature is the main "vividness" knob: lower values weight the decode
-toward the most likely color bin (more saturated, can be a bit blotchy);
-higher values move toward the full expectation over the distribution
-(smoother, but can drift back toward desaturated -- the same hedging effect
-plain regression had). 0.38 (the default) is a reasonable middle ground.
---saturation-boost is an optional *additional* post-decode multiplier on top
-of that, for further hand-tuning after picking a temperature.
-"""
-import argparse
-from pathlib import Path
-
-import numpy as np
-import torch
-import torch.nn as nn
-import torch.nn.functional as F
-from huggingface_hub import PyTorchModelHubMixin
-from PIL import Image
-from skimage.color import lab2rgb, rgb2lab
-
-
-def double_conv(in_ch, out_ch):
-    return nn.Sequential(
-        nn.Conv2d(in_ch, out_ch, 3, padding=1, bias=False),
-        nn.BatchNorm2d(out_ch),
-        nn.ReLU(inplace=True),
-        nn.Conv2d(out_ch, out_ch, 3, padding=1, bias=False),
-        nn.BatchNorm2d(out_ch),
-        nn.ReLU(inplace=True),
-    )
-
-
-class DilatedContextBlock(nn.Module):
-    def __init__(self, channels, mid_ch=96, dilations=(2, 4, 8)):
-        super().__init__()
-        self.proj_in = nn.Sequential(
-            nn.Conv2d(channels, mid_ch, 1, bias=False),
-            nn.BatchNorm2d(mid_ch),
-            nn.ReLU(inplace=True),
-        )
-        layers = []
-        for d in dilations:
-            layers += [
-                nn.Conv2d(mid_ch, mid_ch, 3, padding=d, dilation=d, bias=False),
-                nn.BatchNorm2d(mid_ch),
-                nn.ReLU(inplace=True),
-            ]
-        self.dilated = nn.Sequential(*layers)
-        self.proj_out = nn.Sequential(
-            nn.Conv2d(mid_ch, channels, 1, bias=False),
-            nn.BatchNorm2d(channels),
-        )
-        self.relu = nn.ReLU(inplace=True)
-
-    def forward(self, x):
-        y = self.proj_in(x)
-        y = self.dilated(y)
-        y = self.proj_out(y)
-        return self.relu(x + y)
-
-
-class SmallUNetColorizer(
-    nn.Module,
-    PyTorchModelHubMixin,
-    pipeline_tag="image-to-image",
-    license="apache-2.0",
-    tags=["colorization", "unet", "image-to-image", "classification"],
-):
-    def __init__(self, bin_centers, in_ch: int = 1, base: int = 44,
-                 context_mid_ch: int = 96, context_dilations=(2, 4, 8)):
-        super().__init__()
-        self.in_ch, self.base = in_ch, base
-        num_bins = len(bin_centers)
-        self.num_bins = num_bins
-        self.register_buffer("bin_centers", torch.tensor(bin_centers, dtype=torch.float32))
-
-        self.enc1 = double_conv(in_ch, base)
-        self.enc2 = double_conv(base, base * 2)
-        self.enc3 = double_conv(base * 2, base * 4)
-        self.enc4 = double_conv(base * 4, base * 8)
-        self.pool = nn.MaxPool2d(2)
-        self.context = DilatedContextBlock(base * 8, mid_ch=context_mid_ch,
-                                            dilations=tuple(context_dilations))
-        self.up3 = nn.ConvTranspose2d(base * 8, base * 4, 2, stride=2)
-        self.dec3 = double_conv(base * 8, base * 4)
-        self.up2 = nn.ConvTranspose2d(base * 4, base * 2, 2, stride=2)
-        self.dec2 = double_conv(base * 4, base * 2)
-        self.up1 = nn.ConvTranspose2d(base * 2, base, 2, stride=2)
-        self.dec1 = double_conv(base * 2, base)
-        self.out_conv = nn.Conv2d(base, num_bins, 1)
-
-    def forward(self, x):
-        e1 = self.enc1(x)
-        e2 = self.enc2(self.pool(e1))
-        e3 = self.enc3(self.pool(e2))
-        e4 = self.context(self.enc4(self.pool(e3)))
-        d3 = self.dec3(torch.cat([self.up3(e4), e3], dim=1))
-        d2 = self.dec2(torch.cat([self.up2(d3), e2], dim=1))
-        d1 = self.dec1(torch.cat([self.up1(d2), e1], dim=1))
-        return self.out_conv(d1)
-
-    def decode(self, logits, temperature: float = 0.38):
-        logp = F.log_softmax(logits, dim=1)
-        probs_t = F.softmax(logp / temperature, dim=1)
-        return torch.einsum("bqhw,qc->bchw", probs_t, self.bin_centers)
-
-
-def colorize(model, img, size, temperature, saturation_boost, device):
-    img = img.convert("RGB").resize((size, size))
-    arr = np.asarray(img).astype(np.float32) / 255.0
-    lab = rgb2lab(arr).astype(np.float32)
-    L = torch.from_numpy(lab[:, :, 0:1] / 50.0 - 1.0).permute(2, 0, 1)[None].to(device)
-
-    with torch.no_grad():
-        logits = model(L)
-        ab = model.decode(logits, temperature=temperature)[0].permute(1, 2, 0).cpu().numpy()
-
-    ab = np.clip(ab * saturation_boost, -128, 127)
-    L_out = (L[0, 0].cpu().numpy() + 1.0) * 50.0
-    lab_out = np.concatenate([L_out[:, :, None], ab], axis=-1)
-    rgb_out = np.clip(lab2rgb(lab_out), 0, 1)
-    return Image.fromarray((rgb_out * 255).astype(np.uint8))
-
-
-def main():
-    p = argparse.ArgumentParser(description=__doc__)
-    p.add_argument("images", nargs="+", help="Path(s) to input photo(s)")
-    p.add_argument("--model", required=True, help="Hub model id or local checkpoint path")
-    p.add_argument("--size", type=int, default=256, help="Resize input to this square size")
-    p.add_argument("--temperature", type=float, default=0.38,
-                    help="Annealed-mean decode temperature. Lower = more vivid/mode-like, "
-                         "higher = smoother but can desaturate again. Try 0.15-0.6.")
-    p.add_argument("--saturation-boost", type=float, default=1.0,
-                    help="Extra multiplier on the decoded ab, applied after temperature. "
-                         "1.0 = no extra boost.")
-    p.add_argument("--output-dir", default="./colorized")
-    args = p.parse_args()
-
-    device = "cuda" if torch.cuda.is_available() else "cpu"
-    print(f"Loading {args.model} on {device} ...")
-    model = SmallUNetColorizer.from_pretrained(args.model).to(device).eval()
-    print(f"({model.num_bins} color bins)")
-
-    out_dir = Path(args.output_dir)
-    out_dir.mkdir(parents=True, exist_ok=True)
-
-    for path in args.images:
-        img = Image.open(path)
-        result = colorize(model, img, args.size, args.temperature, args.saturation_boost, device)
-        out_path = out_dir / f"{Path(path).stem}_colorized.png"
-        result.save(out_path)
-        print(f"{path} -> {out_path}")
-
-
-if __name__ == "__main__":
-    main()
+from inference import main
+if __name__ == "__main__": main()

colorize_onnx.py

@@ -1,32 +1,24 @@
-"""Run the exported chroma pipeline without importing PyTorch."""
+"""Minimal ONNX-only image example; fixed square network input.
+
+For aspect-preserving guided upsampling and gamut compression use inference.py.
+"""
 import argparse
-from pathlib import Path
 import numpy as np
 import onnxruntime as ort
 from PIL import Image,ImageOps
 from skimage.color import rgb2lab,lab2rgb
 
-def load_session(path,threads=2):
-    opts=ort.SessionOptions();opts.intra_op_num_threads=threads;opts.inter_op_num_threads=1
-    return ort.InferenceSession(str(path),sess_options=opts,providers=['CPUExecutionProvider'])
-
-def colorize(session,image,size=256):
-    if size<8:raise ValueError('size must be at least8')
+def colorize(image,model='colorizer.onnx'):
     image=ImageOps.exif_transpose(image).convert('RGB')
-    L=rgb2lab(np.asarray(image,dtype=np.float32)/255)[...,0].astype(np.float32)
-    h,w=L.shape;scale=min(size/max(h,w),1)
-    target=(max(8,round(w*scale)),max(8,round(h*scale)))
-    small=np.asarray(Image.fromarray(L).resize(target,Image.Resampling.BILINEAR),dtype=np.float32)
-    x=(small[None,None]/50-1).copy()
-    ab=session.run(['chroma'],{'luminance':x})[0][0]
-    full=np.stack([np.asarray(Image.fromarray(c).resize((w,h),Image.Resampling.BILINEAR)) for c in ab],axis=-1)
-    rgb=np.clip(lab2rgb(np.concatenate([L[...,None],full],axis=-1)),0,1)
-    return Image.fromarray(np.rint(rgb*255).astype(np.uint8))
+    if image.width*image.height>12_000_000:raise ValueError('Maximum 12 megapixels')
+    light=rgb2lab(np.asarray(image,np.float32)/255)[...,0].astype(np.float32)
+    resized=np.asarray(Image.fromarray(light).resize((256,256),Image.Resampling.BILINEAR))
+    session=ort.InferenceSession(model,providers=['CPUExecutionProvider'])
+    ab=session.run(['ab'],{'L':(resized[None,None]/50-1).astype(np.float32)})[0][0]
+    ab=np.stack([np.asarray(Image.fromarray(channel).resize(image.size,Image.Resampling.BILINEAR)) for channel in ab],-1)
+    rgb=np.clip(lab2rgb(np.concatenate([light[...,None],ab],-1)),0,1)
+    return Image.fromarray(np.uint8(np.rint(rgb*255)))
 
 if __name__=='__main__':
-    p=argparse.ArgumentParser(__doc__);p.add_argument('images',nargs='+');p.add_argument('--model',required=True)
-    p.add_argument('--output-dir',default='colorized');p.add_argument('--size',type=int,default=256);p.add_argument('--threads',type=int,default=2)
-    a=p.parse_args();session=load_session(a.model,a.threads);out=Path(a.output_dir);out.mkdir(parents=True,exist_ok=True)
-    for source in a.images:
-        with Image.open(source) as im:result=colorize(session,im,a.size)
-        dest=out/(Path(source).stem+'_colorized.png');result.save(dest);print(dest)
+    p=argparse.ArgumentParser();p.add_argument('input');p.add_argument('output');p.add_argument('--model',default='colorizer.onnx');a=p.parse_args()
+    colorize(Image.open(a.input),a.model).save(a.output)

colorizer.json

@@ -1,54 +1,30 @@
 {
-  "input": "N,1,H,W Lab L*/50-1; H,W>=8",
-  "output": "N,2,H,W Lab chroma a,b",
-  "guided_radius": 8,
-  "guided_epsilon": 0.001,
-  "temperature": 0.38,
+  "release": "v3.0.0",
+  "architecture": "SemanticColorizer",
+  "parameters": 3994676,
+  "format": "onnx",
   "opset": 17,
-  "checks": [
-    {
-      "shape": [
-        1,
-        1,
-        256,
-        256
-      ],
-      "max_ab_difference": 8.58306884765625e-06,
-      "mean_ab_difference": 1.0279118214384653e-06
-    },
-    {
-      "shape": [
-        1,
-        1,
-        173,
-        241
-      ],
-      "max_ab_difference": 7.3909759521484375e-06,
-      "mean_ab_difference": 1.0783561492644367e-06
-    },
-    {
-      "shape": [
-        2,
-        1,
-        64,
-        80
-      ],
-      "max_ab_difference": 7.152557373046875e-06,
-      "mean_ab_difference": 9.707116532808868e-07
-    },
-    {
-      "shape": [
-        1,
-        1,
-        8,
-        9
-      ],
-      "max_ab_difference": 1.5497207641601562e-06,
-      "mean_ab_difference": 3.6218099808138504e-07
-    }
-  ],
-  "parameters": 3968892,
-  "weights_source": "release-v2",
-  "runtime": "1.30.0",
-  "bytes": 15885757
+  "input": {
+    "name": "L",
+    "shape": [
+      1,
+      1,
+      256,
+      256
+    ],
+    "dtype": "float32",
+    "normalization": "Lab L /50 -1"
+  },
+  "output": {
+    "name": "ab",
+    "shape": [
+      1,
+      2,
+      256,
+      256
+    ],
+    "dtype": "float32",
+    "units": "unscaled Lab ab"
+  },
+  "postprocessing": "See inference.py; no colour bins or temperature decode."
 }

colorizer.onnx

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:0ef86749901e66ad53b1e8e1d940330572e2f4c9347ac01e7bc02c7683f8c79a
-size 15885757
+oid sha256:911fb777328fcfbeeb89cc25dca70092cf2de4686ede1edd44a8ccebc89ea341
+size 16039257

config.json

@@ -1,956 +1,7 @@
 {
-  "base": 44,
-  "bin_centers": [
-    [
-      -75.0,
-      25.0
-    ],
-    [
-      -75.0,
-      35.0
-    ],
-    [
-      -75.0,
-      45.0
-    ],
-    [
-      -75.0,
-      55.0
-    ],
-    [
-      -75.0,
-      65.0
-    ],
-    [
-      -75.0,
-      75.0
-    ],
-    [
-      -65.0,
-      25.0
-    ],
-    [
-      -65.0,
-      35.0
-    ],
-    [
-      -65.0,
-      45.0
-    ],
-    [
-      -65.0,
-      55.0
-    ],
-    [
-      -65.0,
-      65.0
-    ],
-    [
-      -65.0,
-      75.0
-    ],
-    [
-      -55.0,
-      5.0
-    ],
-    [
-      -55.0,
-      15.0
-    ],
-    [
-      -55.0,
-      25.0
-    ],
-    [
-      -55.0,
-      35.0
-    ],
-    [
-      -55.0,
-      45.0
-    ],
-    [
-      -55.0,
-      55.0
-    ],
-    [
-      -55.0,
-      65.0
-    ],
-    [
-      -55.0,
-      75.0
-    ],
-    [
-      -45.0,
-      -15.0
-    ],
-    [
-      -45.0,
-      -5.0
-    ],
-    [
-      -45.0,
-      5.0
-    ],
-    [
-      -45.0,
-      15.0
-    ],
-    [
-      -45.0,
-      25.0
-    ],
-    [
-      -45.0,
-      35.0
-    ],
-    [
-      -45.0,
-      45.0
-    ],
-    [
-      -45.0,
-      55.0
-    ],
-    [
-      -45.0,
-      65.0
-    ],
-    [
-      -45.0,
-      75.0
-    ],
-    [
-      -45.0,
-      85.0
-    ],
-    [
-      -35.0,
-      -35.0
-    ],
-    [
-      -35.0,
-      -25.0
-    ],
-    [
-      -35.0,
-      -15.0
-    ],
-    [
-      -35.0,
-      -5.0
-    ],
-    [
-      -35.0,
-      5.0
-    ],
-    [
-      -35.0,
-      15.0
-    ],
-    [
-      -35.0,
-      25.0
-    ],
-    [
-      -35.0,
-      35.0
-    ],
-    [
-      -35.0,
-      45.0
-    ],
-    [
-      -35.0,
-      55.0
-    ],
-    [
-      -35.0,
-      65.0
-    ],
-    [
-      -35.0,
-      75.0
-    ],
-    [
-      -35.0,
-      85.0
-    ],
-    [
-      -35.0,
-      95.0
-    ],
-    [
-      -25.0,
-      -35.0
-    ],
-    [
-      -25.0,
-      -25.0
-    ],
-    [
-      -25.0,
-      -15.0
-    ],
-    [
-      -25.0,
-      -5.0
-    ],
-    [
-      -25.0,
-      5.0
-    ],
-    [
-      -25.0,
-      15.0
-    ],
-    [
-      -25.0,
-      25.0
-    ],
-    [
-      -25.0,
-      35.0
-    ],
-    [
-      -25.0,
-      45.0
-    ],
-    [
-      -25.0,
-      55.0
-    ],
-    [
-      -25.0,
-      65.0
-    ],
-    [
-      -25.0,
-      75.0
-    ],
-    [
-      -25.0,
-      85.0
-    ],
-    [
-      -25.0,
-      95.0
-    ],
-    [
-      -15.0,
-      -45.0
-    ],
-    [
-      -15.0,
-      -35.0
-    ],
-    [
-      -15.0,
-      -25.0
-    ],
-    [
-      -15.0,
-      -15.0
-    ],
-    [
-      -15.0,
-      -5.0
-    ],
-    [
-      -15.0,
-      5.0
-    ],
-    [
-      -15.0,
-      15.0
-    ],
-    [
-      -15.0,
-      25.0
-    ],
-    [
-      -15.0,
-      35.0
-    ],
-    [
-      -15.0,
-      45.0
-    ],
-    [
-      -15.0,
-      55.0
-    ],
-    [
-      -15.0,
-      65.0
-    ],
-    [
-      -15.0,
-      75.0
-    ],
-    [
-      -15.0,
-      85.0
-    ],
-    [
-      -15.0,
-      95.0
-    ],
-    [
-      -5.0,
-      -55.0
-    ],
-    [
-      -5.0,
-      -45.0
-    ],
-    [
-      -5.0,
-      -35.0
-    ],
-    [
-      -5.0,
-      -25.0
-    ],
-    [
-      -5.0,
-      -15.0
-    ],
-    [
-      -5.0,
-      -5.0
-    ],
-    [
-      -5.0,
-      5.0
-    ],
-    [
-      -5.0,
-      15.0
-    ],
-    [
-      -5.0,
-      25.0
-    ],
-    [
-      -5.0,
-      35.0
-    ],
-    [
-      -5.0,
-      45.0
-    ],
-    [
-      -5.0,
-      55.0
-    ],
-    [
-      -5.0,
-      65.0
-    ],
-    [
-      -5.0,
-      75.0
-    ],
-    [
-      -5.0,
-      85.0
-    ],
-    [
-      5.0,
-      -65.0
-    ],
-    [
-      5.0,
-      -55.0
-    ],
-    [
-      5.0,
-      -45.0
-    ],
-    [
-      5.0,
-      -35.0
-    ],
-    [
-      5.0,
-      -25.0
-    ],
-    [
-      5.0,
-      -15.0
-    ],
-    [
-      5.0,
-      -5.0
-    ],
-    [
-      5.0,
-      5.0
-    ],
-    [
-      5.0,
-      15.0
-    ],
-    [
-      5.0,
-      25.0
-    ],
-    [
-      5.0,
-      35.0
-    ],
-    [
-      5.0,
-      45.0
-    ],
-    [
-      5.0,
-      55.0
-    ],
-    [
-      5.0,
-      65.0
-    ],
-    [
-      5.0,
-      75.0
-    ],
-    [
-      5.0,
-      85.0
-    ],
-    [
-      15.0,
-      -75.0
-    ],
-    [
-      15.0,
-      -65.0
-    ],
-    [
-      15.0,
-      -55.0
-    ],
-    [
-      15.0,
-      -45.0
-    ],
-    [
-      15.0,
-      -35.0
-    ],
-    [
-      15.0,
-      -25.0
-    ],
-    [
-      15.0,
-      -15.0
-    ],
-    [
-      15.0,
-      -5.0
-    ],
-    [
-      15.0,
-      5.0
-    ],
-    [
-      15.0,
-      15.0
-    ],
-    [
-      15.0,
-      25.0
-    ],
-    [
-      15.0,
-      35.0
-    ],
-    [
-      15.0,
-      45.0
-    ],
-    [
-      15.0,
-      55.0
-    ],
-    [
-      15.0,
-      65.0
-    ],
-    [
-      15.0,
-      75.0
-    ],
-    [
-      15.0,
-      85.0
-    ],
-    [
-      25.0,
-      -75.0
-    ],
-    [
-      25.0,
-      -65.0
-    ],
-    [
-      25.0,
-      -55.0
-    ],
-    [
-      25.0,
-      -45.0
-    ],
-    [
-      25.0,
-      -35.0
-    ],
-    [
-      25.0,
-      -25.0
-    ],
-    [
-      25.0,
-      -15.0
-    ],
-    [
-      25.0,
-      -5.0
-    ],
-    [
-      25.0,
-      5.0
-    ],
-    [
-      25.0,
-      15.0
-    ],
-    [
-      25.0,
-      25.0
-    ],
-    [
-      25.0,
-      35.0
-    ],
-    [
-      25.0,
-      45.0
-    ],
-    [
-      25.0,
-      55.0
-    ],
-    [
-      25.0,
-      65.0
-    ],
-    [
-      25.0,
-      75.0
-    ],
-    [
-      25.0,
-      85.0
-    ],
-    [
-      35.0,
-      -85.0
-    ],
-    [
-      35.0,
-      -75.0
-    ],
-    [
-      35.0,
-      -65.0
-    ],
-    [
-      35.0,
-      -55.0
-    ],
-    [
-      35.0,
-      -45.0
-    ],
-    [
-      35.0,
-      -35.0
-    ],
-    [
-      35.0,
-      -25.0
-    ],
-    [
-      35.0,
-      -15.0
-    ],
-    [
-      35.0,
-      -5.0
-    ],
-    [
-      35.0,
-      5.0
-    ],
-    [
-      35.0,
-      15.0
-    ],
-    [
-      35.0,
-      25.0
-    ],
-    [
-      35.0,
-      35.0
-    ],
-    [
-      35.0,
-      45.0
-    ],
-    [
-      35.0,
-      55.0
-    ],
-    [
-      35.0,
-      65.0
-    ],
-    [
-      35.0,
-      75.0
-    ],
-    [
-      45.0,
-      -95.0
-    ],
-    [
-      45.0,
-      -85.0
-    ],
-    [
-      45.0,
-      -75.0
-    ],
-    [
-      45.0,
-      -65.0
-    ],
-    [
-      45.0,
-      -55.0
-    ],
-    [
-      45.0,
-      -45.0
-    ],
-    [
-      45.0,
-      -35.0
-    ],
-    [
-      45.0,
-      -25.0
-    ],
-    [
-      45.0,
-      -15.0
-    ],
-    [
-      45.0,
-      -5.0
-    ],
-    [
-      45.0,
-      5.0
-    ],
-    [
-      45.0,
-      15.0
-    ],
-    [
-      45.0,
-      25.0
-    ],
-    [
-      45.0,
-      35.0
-    ],
-    [
-      45.0,
-      45.0
-    ],
-    [
-      45.0,
-      55.0
-    ],
-    [
-      45.0,
-      65.0
-    ],
-    [
-      45.0,
-      75.0
-    ],
-    [
-      55.0,
-      -95.0
-    ],
-    [
-      55.0,
-      -85.0
-    ],
-    [
-      55.0,
-      -75.0
-    ],
-    [
-      55.0,
-      -65.0
-    ],
-    [
-      55.0,
-      -55.0
-    ],
-    [
-      55.0,
-      -45.0
-    ],
-    [
-      55.0,
-      -35.0
-    ],
-    [
-      55.0,
-      -25.0
-    ],
-    [
-      55.0,
-      -15.0
-    ],
-    [
-      55.0,
-      -5.0
-    ],
-    [
-      55.0,
-      5.0
-    ],
-    [
-      55.0,
-      15.0
-    ],
-    [
-      55.0,
-      25.0
-    ],
-    [
-      55.0,
-      35.0
-    ],
-    [
-      55.0,
-      45.0
-    ],
-    [
-      55.0,
-      55.0
-    ],
-    [
-      55.0,
-      65.0
-    ],
-    [
-      55.0,
-      75.0
-    ],
-    [
-      65.0,
-      -105.0
-    ],
-    [
-      65.0,
-      -95.0
-    ],
-    [
-      65.0,
-      -85.0
-    ],
-    [
-      65.0,
-      -75.0
-    ],
-    [
-      65.0,
-      -65.0
-    ],
-    [
-      65.0,
-      -55.0
-    ],
-    [
-      65.0,
-      -45.0
-    ],
-    [
-      65.0,
-      -35.0
-    ],
-    [
-      65.0,
-      -25.0
-    ],
-    [
-      65.0,
-      -15.0
-    ],
-    [
-      65.0,
-      -5.0
-    ],
-    [
-      65.0,
-      5.0
-    ],
-    [
-      65.0,
-      15.0
-    ],
-    [
-      65.0,
-      25.0
-    ],
-    [
-      65.0,
-      35.0
-    ],
-    [
-      65.0,
-      45.0
-    ],
-    [
-      65.0,
-      55.0
-    ],
-    [
-      65.0,
-      65.0
-    ],
-    [
-      75.0,
-      -105.0
-    ],
-    [
-      75.0,
-      -95.0
-    ],
-    [
-      75.0,
-      -45.0
-    ],
-    [
-      75.0,
-      -35.0
-    ],
-    [
-      75.0,
-      -25.0
-    ],
-    [
-      75.0,
-      -15.0
-    ],
-    [
-      75.0,
-      -5.0
-    ],
-    [
-      75.0,
-      5.0
-    ],
-    [
-      75.0,
-      15.0
-    ],
-    [
-      75.0,
-      25.0
-    ],
-    [
-      75.0,
-      35.0
-    ],
-    [
-      75.0,
-      45.0
-    ],
-    [
-      75.0,
-      55.0
-    ],
-    [
-      75.0,
-      65.0
-    ],
-    [
-      85.0,
-      -45.0
-    ],
-    [
-      85.0,
-      -35.0
-    ],
-    [
-      85.0,
-      -25.0
-    ],
-    [
-      85.0,
-      -15.0
-    ],
-    [
-      85.0,
-      -5.0
-    ],
-    [
-      85.0,
-      5.0
-    ],
-    [
-      85.0,
-      35.0
-    ],
-    [
-      85.0,
-      45.0
-    ],
-    [
-      85.0,
-      65.0
-    ],
-    [
-      95.0,
-      -55.0
-    ],
-    [
-      95.0,
-      -45.0
-    ],
-    [
-      95.0,
-      -35.0
-    ]
-  ],
-  "context_dilations": [
-    2,
-    4,
-    8
-  ],
-  "context_mid_ch": 96,
-  "in_ch": 1
+  "architecture": "SemanticColorizer",
+  "head": "palette",
+  "width": 128,
+  "queries": 16,
+  "format_version": 1
 }

export_onnx.py

@@ -1,48 +1,29 @@
-"""Export the colorizer AND luminance-guided chroma decoder as one ONNX graph.
-
-Input: N,1,H,W normalized Lab luminance (L*/50-1), minimum8px per side.
-Output: N,2,H,W Lab a,b values. Resize/preserve original L* in the app.
-"""
-import argparse,json
+"""Export the release network at fixed 256x256, with numerical verification."""
+import argparse
+import importlib.util
+import tempfile
 from pathlib import Path
 import numpy as np
 import torch
-from model import load_model
-from spatial import guided_chroma
-
-class ChromaPipeline(torch.nn.Module):
-    def __init__(self,model,radius=8,temperature=.38):
-        super().__init__();self.model=model;self.radius=radius;self.temperature=temperature
-    def forward(self,L):
-        return guided_chroma(L,self.model.decode(self.model(L),self.temperature),self.radius)
-
-def export(a):
-    import onnx,onnxruntime as ort
-    torch.set_num_threads(2);torch.manual_seed(2026)
-    model=ChromaPipeline(load_model(a.model),a.radius).eval()
-    out=Path(a.output);out.parent.mkdir(parents=True,exist_ok=True)
-    with torch.inference_mode():
-        torch.onnx.export(model,torch.zeros(1,1,256,256),str(out),opset_version=17,
-            input_names=['luminance'],output_names=['chroma'],dynamo=False,
-            dynamic_axes={'luminance':{0:'batch',2:'height',3:'width'},'chroma':{0:'batch',2:'height',3:'width'}})
-    onnx.checker.check_model(str(out))
-    opts=ort.SessionOptions();opts.intra_op_num_threads=2;opts.inter_op_num_threads=1
-    session=ort.InferenceSession(str(out),sess_options=opts,providers=['CPUExecutionProvider'])
-    checks=[]
-    for shape in [(1,1,256,256),(1,1,173,241),(2,1,64,80),(1,1,8,9)]:
-        x=torch.rand(shape)*2-1
-        with torch.inference_mode():expected=model(x).numpy()
-        actual=session.run(None,{'luminance':x.numpy()})[0]
-        error=np.abs(expected-actual)
-        assert actual.shape==expected.shape and np.isfinite(actual).all()
-        np.testing.assert_allclose(actual,expected,atol=.01,rtol=.001)
-        checks.append({'shape':list(shape),'max_ab_difference':float(error.max()),'mean_ab_difference':float(error.mean())})
-    result={'input':'N,1,H,W Lab L*/50-1; H,W>=8','output':'N,2,H,W Lab chroma a,b',
-            'guided_radius':a.radius,'guided_epsilon':.001,'temperature':.38,
-            'opset':17,'checks':checks,'parameters':sum(p.numel() for p in model.parameters()),
-            'weights_source':a.model,'runtime':ort.__version__,'bytes':out.stat().st_size}
-    out.with_suffix('.json').write_text(json.dumps(result,indent=2));print(json.dumps(result,indent=2))
+import onnx
+import onnxruntime as ort
+from semantic_model import load_semantic
 
-if __name__=='__main__':
-    p=argparse.ArgumentParser(__doc__);p.add_argument('--model',required=True);p.add_argument('--output',required=True);p.add_argument('--radius',type=int,default=8)
-    export(p.parse_args())
+def main():
+    p=argparse.ArgumentParser();p.add_argument('--model',default='.');p.add_argument('--output',default='colorizer.onnx');args=p.parse_args()
+    source=Path(__file__).with_name('semantic_model.py').read_text()
+    source=source.replace("x=F.pad(self.neutral_rgb(L),(0,(-w)%32,0,(-h)%32),mode='replicate')","x=self.neutral_rgb(L)")
+    source=source.replace("F.adaptive_avg_pool2d(f,(8,8)).flatten(2).transpose(1,2) for f in projected[1:]","F.avg_pool2d(f,k).flatten(2).transpose(1,2) for f,k in zip(projected[1:],[4,2,1])")
+    with tempfile.TemporaryDirectory() as tmp:
+        path=Path(tmp)/'export_model.py';path.write_text(source)
+        spec=importlib.util.spec_from_file_location('export_model',path);module=importlib.util.module_from_spec(spec);spec.loader.exec_module(module)
+        model=module.load_semantic(args.model,'cpu');reference=load_semantic(args.model,'cpu')
+        x=torch.linspace(-1,1,256*256).reshape(1,1,256,256)
+        with torch.no_grad():expected=reference(x).numpy();assert np.max(np.abs(expected-model(x).numpy()))<1e-5
+        torch.onnx.export(model,x,args.output,input_names=['L'],output_names=['ab'],opset_version=17,do_constant_folding=True,dynamo=False)
+    onnx.checker.check_model(args.output)
+    session=ort.InferenceSession(args.output,providers=['CPUExecutionProvider'])
+    error=float(np.max(np.abs(session.run(None,{'L':x.numpy()})[0]-expected)))
+    if error>=.005:raise RuntimeError(f'ONNX parity failed: {error}')
+    print(f'Exported {args.output}; maximum Lab error {error:.6f}')
+if __name__=='__main__':main()

inference.py

@@ -1,63 +1,111 @@
-"""Aspect-preserving inference; infer chroma globally and retain original luminance."""
-import argparse
+"""Aspect-preserving colourisation with a compact semantic model.
+
+Input and output are PIL images. No teacher, critic or second learned model is
+loaded. Original lightness and alpha are retained; out-of-gamut chroma is reduced.
+"""
+import json
 import math
 from pathlib import Path
 import numpy as np
-from PIL import Image, ImageOps
 import torch
 import torch.nn.functional as F
-from skimage.color import rgb2lab, lab2rgb
-from model import load_model
-from spatial import guided_chroma
+from PIL import Image, ImageOps
+from skimage.color import rgb2lab
+from semantic_model import load_semantic
+
+MAX_PIXELS = 12_000_000
+
+def load_colorizer(path, device='cpu'):
+    model = load_semantic(path, device)
+    count = sum(p.numel() for p in model.parameters())
+    if count >= 4_000_000:
+        raise ValueError('Model exceeds the four-million-parameter limit')
+    return model
+
+def box_mean(x, r):
+    return F.avg_pool2d(x, 2*r+1, 1, r, count_include_pad=False)
+
+def prepare(image, size=256):
+    if not isinstance(image, Image.Image):
+        raise TypeError('Expected a PIL image')
+    if not 128 <= int(size) <= 512:
+        raise ValueError('Input size must be between 128 and 512')
+    image = ImageOps.exif_transpose(image)
+    if image.width * image.height > MAX_PIXELS:
+        raise ValueError('Please resize the image to at most 12 megapixels')
+    alpha = np.asarray(image.getchannel('A')).copy() if 'A' in image.getbands() else None
+    rgb = np.asarray(image.convert('RGB'), dtype=np.float32) / 255
+    light = rgb2lab(rgb)[..., 0].astype(np.float32)
+    scale = min(int(size)/max(image.size), 1.)
+    shape = (max(8, round(image.height*scale)), max(8, round(image.width*scale)))
+    x = torch.from_numpy(light)[None,None]/50-1
+    small = F.interpolate(x, size=shape, mode='bilinear', align_corners=False, antialias=True)
+    return light, alpha, small
 
 @torch.inference_mode()
-def colorize(model, image, size=256, temperature=0.38, saturation=1.0, flip_tta=False,
-             guided_radius=8, guided_epsilon=.001):
-    if size < 8 or not math.isfinite(saturation) or saturation < 0:
-        raise ValueError("size must be >=8 and saturation finite and nonnegative")
-    image = ImageOps.exif_transpose(image).convert("RGB")
-    rgb = np.asarray(image, dtype=np.float32) / 255.0
-    luminance = rgb2lab(rgb)[..., 0].astype(np.float32)
-    h, w = luminance.shape
-    scale = min(size / max(h, w), 1.0)
-    target = (max(8, round(h*scale)), max(8, round(w*scale)))
+def chroma_coefficients(model, small, radius=8):
+    if radius not in (0,4,8,12,16):
+        raise ValueError('Unsupported smoothing radius')
     device = next(model.parameters()).device
-    L = torch.from_numpy(luminance)[None, None].to(device) / 50 - 1
-    small = F.interpolate(L, size=target, mode="bilinear", align_corners=False, antialias=True)
-    logits = model(small)
-    if flip_tta:
-        logits = (logits + model(small.flip(-1)).flip(-1)) * 0.5
-    ab = model.decode(logits, temperature)
-    ab = guided_chroma(small, ab, guided_radius, guided_epsilon)
-    ab = F.interpolate(ab, size=(h,w), mode="bilinear", align_corners=False)
-    ab = ab[0].permute(1,2,0).cpu().numpy() * saturation
-    lab = np.concatenate([luminance[...,None], ab], axis=-1)
-    result = np.clip(lab2rgb(lab), 0, 1)
-    return Image.fromarray(np.rint(result * 255).astype(np.uint8))
+    L = small.to(device)
+    ab = model(L).float()
+    if not torch.isfinite(ab).all():
+        raise RuntimeError('Model returned non-finite colours')
+    if radius == 0:
+        return torch.zeros_like(ab).cpu(), ab.cpu()
+    guide = (L.float()+1)/2
+    mi, mp = box_mean(guide,radius), box_mean(ab,radius)
+    var = (box_mean(guide*guide,radius)-mi*mi).clamp_min(0)
+    cov = box_mean(guide*ab,radius)-mi*mp
+    a = cov/(var+.001)
+    b = mp-a*mi
+    # Coefficients are upsampled, then evaluated against original-resolution L.
+    return box_mean(a,radius).cpu(), box_mean(b,radius).cpu()
+
+def _linear_rgb(light, ab):
+    fy = (light+16)/116
+    f = np.stack([fy+ab[...,0]/500,fy,fy-ab[...,1]/200],axis=-1)
+    xyz = np.where(f>6/29,f**3,(f-4/29)*(3*(6/29)**2))
+    xyz *= np.array([.95047,1.,1.08883],np.float32)
+    matrix = np.array([[3.24048134,-1.53715152,-.49853633],[-.96925495,1.87599,.04155593],[.05564664,-.20404134,1.05731107]],np.float32)
+    return xyz @ matrix.T
+
+def render(light, alpha, coefficients, saturation=1.):
+    saturation = float(saturation)
+    if not math.isfinite(saturation) or not 0 <= saturation <= 1.5:
+        raise ValueError('Colour strength must be between 0 and 1.5')
+    a,b = [F.interpolate(v.float(),size=light.shape,mode='bilinear',align_corners=False)[0].permute(1,2,0).numpy() for v in coefficients]
+    ab = (a*(light[...,None]/100)+b)*saturation
+    # Binary-search chroma compression retains Lab hue and lightness.
+    linear = _linear_rgb(light,ab)
+    invalid = ((linear < -1e-5)|(linear > 1+1e-5)).any(-1)
+    if invalid.any():
+        L = light[invalid]; colors=ab[invalid];lo=np.zeros(len(L),np.float32);hi=np.ones(len(L),np.float32)
+        for _ in range(9):
+            mid=(lo+hi)/2; candidate=_linear_rgb(L,colors*mid[:,None])
+            valid=((candidate>=-1e-5)&(candidate<=1+1e-5)).all(-1)
+            lo=np.where(valid,mid,lo);hi=np.where(valid,hi,mid)
+        ab[invalid]=colors*lo[:,None]
+        linear[invalid]=_linear_rgb(L,ab[invalid])
+    linear=np.clip(linear,0,1)
+    rgb=np.where(linear<=.0031308,12.92*linear,1.055*np.power(linear,1/2.4)-.055)
+    pixels=np.uint8(np.clip(np.rint(rgb*255),0,255))
+    if alpha is not None: pixels=np.concatenate([pixels,alpha[...,None]],axis=-1)
+    return Image.fromarray(pixels)
+
+def colorize(model, image, size=256, radius=8, saturation=1.):
+    light,alpha,small=prepare(image,size)
+    return render(light,alpha,chroma_coefficients(model,small,radius),saturation)
 
 def main():
-    p = argparse.ArgumentParser(__doc__)
-    p.add_argument("images", nargs="+")
-    p.add_argument("--model", required=True)
-    p.add_argument("--revision", default=None)
-    p.add_argument("--size", type=int, default=256)
-    p.add_argument("--temperature", type=float, default=.38)
-    p.add_argument("--saturation", type=float, default=1)
-    p.add_argument("--flip-tta", action="store_true")
-    p.add_argument("--guided-radius",type=int,default=8,help="Chroma smoothing radius at model resolution;0 disables")
-    p.add_argument("--guided-epsilon",type=float,default=.001)
-    p.add_argument("--output-dir", default="colorized")
-    p.add_argument("--device", default="cuda" if torch.cuda.is_available() else "cpu")
-    a = p.parse_args()
-    torch.set_num_threads(min(torch.get_num_threads(),4))
-    model = load_model(a.model, a.revision, a.device)
-    out = Path(a.output_dir); out.mkdir(parents=True, exist_ok=True)
-    for file in a.images:
-        with Image.open(file) as im:
-            result = colorize(model, im, a.size, a.temperature, a.saturation, a.flip_tta,
-                              a.guided_radius,a.guided_epsilon)
-        dest = out / (Path(file).stem + "_colorized.png")
-        result.save(dest); print(dest)
-
-if __name__ == "__main__":
-    main()
+    import argparse
+    parser=argparse.ArgumentParser(description='Compact photo colouriser')
+    parser.add_argument('input');parser.add_argument('output')
+    parser.add_argument('--model',default='.');parser.add_argument('--device',default='cpu')
+    parser.add_argument('--size',type=int,default=256);parser.add_argument('--saturation',type=float,default=1.)
+    args=parser.parse_args()
+    model=load_colorizer(args.model,args.device)
+    with Image.open(args.input) as image:
+        colorize(model,image,args.size,saturation=args.saturation).save(args.output)
+
+if __name__=='__main__':main()

legacy/v2/ARCHIVE.md

@@ -0,0 +1 @@
+Historical v2 helpers. Load weights/config from immutable model revision 704fa80d792c3d759db91daa00b2dcfe6f0f6412. Do not combine these helpers with the new semantic checkpoint.

legacy/v2/DEPLOYMENT.md

@@ -0,0 +1,80 @@
+# Colorizer deployment
+
+Use the release's inference wrapper or its ONNX graph to obtain the complete
+improvement. The `.safetensors` file contains the learned colorizer; guided
+decoding is implemented by `spatial.py` and is included in the ONNX graph.
+
+## Python / PyTorch
+
+Run from the extracted release directory:
+
+```bash
+python -m pip install -r requirements.txt
+python inference.py --model . --output-dir colorized photo.jpg
+```
+
+The default guided radius is 8 at the model's input resolution. Use
+`--guided-radius 0` for raw predictions or `--guided-radius 16` for stronger
+smoothing. Stronger smoothing can remove legitimate small color details.
+`--flip-tta --guided-radius 4` is an optional two-pass mode. The released
+ONNX graph is the single-pass radius-8 mode.
+
+```python
+from PIL import Image
+from model import load_model
+from inference import colorize
+
+model = load_model('.')
+result = colorize(model, Image.open('photo.jpg'))
+result.save('colorized.png')
+```
+
+The wrapper handles EXIF orientation, preserves aspect ratio, bounds the
+longest network-input side to 256 pixels, upsamples chroma to the original
+oriented image dimensions and combines it with the original Lab luminance.
+Final RGB conversion can clip colors outside the display gamut. Very large
+inputs still require memory for full-resolution color conversion. There is
+no video temporal-consistency guarantee.
+
+## ONNX without PyTorch
+
+```bash
+python -m pip install -r requirements-onnx.txt
+python colorize_onnx.py --model colorizer.onnx --output-dir colorized photo.jpg
+```
+
+Input name: `luminance`, float32, shape `N x 1 x H x W`, values `L*/50 - 1`.
+Output name: `chroma`, float32, shape `N x 2 x H x W`, Lab a and b values.
+Height and width must each be at least 8. Dynamic shapes and batches are
+supported. Prefer a longest input side of 256 to match the evaluated
+operating point. Ordinary RGB values are not valid graph inputs.
+
+The graph includes temperature-0.38 decoding and radius-8 guided filtering
+with epsilon 0.001. It does not include file loading, EXIF handling, Lab
+conversion, aspect-ratio resizing or final chroma upsampling; these are
+implemented in `colorize_onnx.py`. The ONNX wrapper uses Pillow resizing,
+whereas the PyTorch wrapper uses PyTorch interpolation. Their image-level
+comparison is recorded in the release checks.
+
+## Publish to main
+
+Authenticate normally on your own computer with repository write access:
+
+```bash
+hf auth login
+python upload_main.py --folder . --repo User-2468/mini-unet-colorizer
+```
+
+This performs one upload to `main` with an optimistic-concurrency guard.
+It also verifies that `stable` retains its pre-upload revision. The app can
+keep using `stable` until you choose to switch it to the tested release.
+The current chat connection has Jobs/read access but no repository write
+scope; the downloadable release is the publication fallback.
+
+## Deployment limits
+
+This is a measured app-testing candidate. Semantic color mistakes remain,
+and smoothing cannot infer an object's unknown original color. Review the
+included failure examples on your app's real input photos before describing
+it as generally production-ready. Browser/mobile performance and real-time
+video have not been validated.

legacy/v2/README.md

@@ -0,0 +1,80 @@
+---
+license: apache-2.0
+pipeline_tag: image-to-image
+tags:
+- colorization
+- unet
+- pytorch
+- safetensors
+- onnx
+datasets:
+- johnowhitaker/imagenette2-320
+- detection-datasets/coco
+---
+# Mini U-Net Colorizer — broader-data trained candidate
+
+**Status: evaluated app-testing candidate.** Some broad color patches and
+incorrect object hues remain. Predicted colors are not evidence of original
+historical colors.
+
+This checkpoint has 3,968,892 learned parameters and 236 fixed color bins.
+It starts from the audited bin-mapping repair of main commit
+`6c47ea40724d8fcd67d4f36ce837dc1cb5b1b2a8` and changes all 65 learned parameter
+tensors. The color vocabulary is unchanged. The selected weights are update
+748 of a completed 1,122-update BF16 L4 run using a 17,325-photo mixed training
+pool (11,943 Imagenette plus 5,382 COCO), batch 32, initial learning rate 1e-5,
+weighted classification loss and frozen BatchNorm running statistics.
+
+Selection compared Imagenette50 and reserved COCO200 validation images.
+The selected model retained color strength better than spatial-loss candidates.
+It was then scored on separate Imagenette200 and COCO-val100 checks.
+
+| Test sample | Previous repaired error | This release error | Fine excess-edge reduction |
+|---|---:|---:|---:|
+| Imagenette 200 | 13.318 | 12.847 | 85.8% |
+| COCO-val 100 | 15.266 | 14.532 | 84.3% |
+
+Error is mean Lab chroma distance. The release includes guided8 decoding;
+raw learned weights alone improve error by 1.97% and 3.25%, respectively.
+Excess-edge reductions are proxies, not counts of visible blotches removed.
+COCO is a convenience sample; older upstream training exposure is unknown.
+
+## Use the complete pipeline
+
+```bash
+python -m pip install -r requirements.txt
+python inference.py --model . --output-dir colorized photo.jpg
+```
+
+```python
+from PIL import Image
+from model import load_model
+from inference import colorize
+model = load_model('.')
+colorize(model, Image.open('photo.jpg')).save('colorized.png')
+```
+
+Defaults: temperature 0.38, guided radius 8, epsilon 0.001, one network pass.
+The wrapper preserves aspect ratio and original luminance. Old app code that
+only loads safetensors will not automatically gain guided filtering.
+
+For ONNX without PyTorch:
+
+```bash
+python -m pip install -r requirements-onnx.txt
+python colorize_onnx.py --model colorizer.onnx --output-dir colorized photo.jpg
+```
+
+The 15.9MB ONNX graph includes the model and guided decoder, with dynamic
+batch/spatial sizes and verified PyTorch parity. See `DEPLOYMENT.md` for the
+Lab input contract, CPU timings, publication commands and integration limits.
+See `RESEARCH_ROUND2.md` and `reports/round2/` for complete measured evidence.
+
+## Limitations
+
+Smoothing removes fine color fluctuations but can suppress true small color
+details, especially without luminance boundaries. Semantically wrong hues
+remain. The coffee and rocket failure examples are retained. Browser/mobile
+performance, video consistency and general production quality are unvalidated.
+The separate experiment bundle contains all runs and reproduction code; GPU
+optimizer state is not included. This is a weights-only continuation point.

legacy/v2/colorize_image.py

@@ -0,0 +1,176 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "torch>=2.3",
+#     "torchvision>=0.18",
+#     "huggingface_hub>=0.24",
+#     "safetensors>=0.4",
+#     "scikit-image>=0.22",
+#     "pillow>=10.0",
+#     "numpy",
+# ]
+# ///
+"""
+Colorize photos with a SmallUNetColorizer checkpoint trained by colorize_train.py
+(classification-head version: predicts a distribution over quantized Lab ab
+bins per pixel, decoded with an annealed mean).
+
+Usage:
+    uv run colorize_image.py --model User-2468/mini-unet-colorizer photo.jpg
+    uv run colorize_image.py --model ./local_checkpoint --temperature 0.2 a.jpg b.jpg
+
+--temperature is the main "vividness" knob: lower values weight the decode
+toward the most likely color bin (more saturated, can be a bit blotchy);
+higher values move toward the full expectation over the distribution
+(smoother, but can drift back toward desaturated -- the same hedging effect
+plain regression had). 0.38 (the default) is a reasonable middle ground.
+--saturation-boost is an optional *additional* post-decode multiplier on top
+of that, for further hand-tuning after picking a temperature.
+"""
+import argparse
+from pathlib import Path
+
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from huggingface_hub import PyTorchModelHubMixin
+from PIL import Image
+from skimage.color import lab2rgb, rgb2lab
+
+
+def double_conv(in_ch, out_ch):
+    return nn.Sequential(
+        nn.Conv2d(in_ch, out_ch, 3, padding=1, bias=False),
+        nn.BatchNorm2d(out_ch),
+        nn.ReLU(inplace=True),
+        nn.Conv2d(out_ch, out_ch, 3, padding=1, bias=False),
+        nn.BatchNorm2d(out_ch),
+        nn.ReLU(inplace=True),
+    )
+
+
+class DilatedContextBlock(nn.Module):
+    def __init__(self, channels, mid_ch=96, dilations=(2, 4, 8)):
+        super().__init__()
+        self.proj_in = nn.Sequential(
+            nn.Conv2d(channels, mid_ch, 1, bias=False),
+            nn.BatchNorm2d(mid_ch),
+            nn.ReLU(inplace=True),
+        )
+        layers = []
+        for d in dilations:
+            layers += [
+                nn.Conv2d(mid_ch, mid_ch, 3, padding=d, dilation=d, bias=False),
+                nn.BatchNorm2d(mid_ch),
+                nn.ReLU(inplace=True),
+            ]
+        self.dilated = nn.Sequential(*layers)
+        self.proj_out = nn.Sequential(
+            nn.Conv2d(mid_ch, channels, 1, bias=False),
+            nn.BatchNorm2d(channels),
+        )
+        self.relu = nn.ReLU(inplace=True)
+
+    def forward(self, x):
+        y = self.proj_in(x)
+        y = self.dilated(y)
+        y = self.proj_out(y)
+        return self.relu(x + y)
+
+
+class SmallUNetColorizer(
+    nn.Module,
+    PyTorchModelHubMixin,
+    pipeline_tag="image-to-image",
+    license="apache-2.0",
+    tags=["colorization", "unet", "image-to-image", "classification"],
+):
+    def __init__(self, bin_centers, in_ch: int = 1, base: int = 44,
+                 context_mid_ch: int = 96, context_dilations=(2, 4, 8)):
+        super().__init__()
+        self.in_ch, self.base = in_ch, base
+        num_bins = len(bin_centers)
+        self.num_bins = num_bins
+        self.register_buffer("bin_centers", torch.tensor(bin_centers, dtype=torch.float32))
+
+        self.enc1 = double_conv(in_ch, base)
+        self.enc2 = double_conv(base, base * 2)
+        self.enc3 = double_conv(base * 2, base * 4)
+        self.enc4 = double_conv(base * 4, base * 8)
+        self.pool = nn.MaxPool2d(2)
+        self.context = DilatedContextBlock(base * 8, mid_ch=context_mid_ch,
+                                            dilations=tuple(context_dilations))
+        self.up3 = nn.ConvTranspose2d(base * 8, base * 4, 2, stride=2)
+        self.dec3 = double_conv(base * 8, base * 4)
+        self.up2 = nn.ConvTranspose2d(base * 4, base * 2, 2, stride=2)
+        self.dec2 = double_conv(base * 4, base * 2)
+        self.up1 = nn.ConvTranspose2d(base * 2, base, 2, stride=2)
+        self.dec1 = double_conv(base * 2, base)
+        self.out_conv = nn.Conv2d(base, num_bins, 1)
+
+    def forward(self, x):
+        e1 = self.enc1(x)
+        e2 = self.enc2(self.pool(e1))
+        e3 = self.enc3(self.pool(e2))
+        e4 = self.context(self.enc4(self.pool(e3)))
+        d3 = self.dec3(torch.cat([self.up3(e4), e3], dim=1))
+        d2 = self.dec2(torch.cat([self.up2(d3), e2], dim=1))
+        d1 = self.dec1(torch.cat([self.up1(d2), e1], dim=1))
+        return self.out_conv(d1)
+
+    def decode(self, logits, temperature: float = 0.38):
+        logp = F.log_softmax(logits, dim=1)
+        probs_t = F.softmax(logp / temperature, dim=1)
+        return torch.einsum("bqhw,qc->bchw", probs_t, self.bin_centers)
+
+
+def colorize(model, img, size, temperature, saturation_boost, device):
+    img = img.convert("RGB").resize((size, size))
+    arr = np.asarray(img).astype(np.float32) / 255.0
+    lab = rgb2lab(arr).astype(np.float32)
+    L = torch.from_numpy(lab[:, :, 0:1] / 50.0 - 1.0).permute(2, 0, 1)[None].to(device)
+
+    with torch.no_grad():
+        logits = model(L)
+        ab = model.decode(logits, temperature=temperature)[0].permute(1, 2, 0).cpu().numpy()
+
+    ab = np.clip(ab * saturation_boost, -128, 127)
+    L_out = (L[0, 0].cpu().numpy() + 1.0) * 50.0
+    lab_out = np.concatenate([L_out[:, :, None], ab], axis=-1)
+    rgb_out = np.clip(lab2rgb(lab_out), 0, 1)
+    return Image.fromarray((rgb_out * 255).astype(np.uint8))
+
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("images", nargs="+", help="Path(s) to input photo(s)")
+    p.add_argument("--model", required=True, help="Hub model id or local checkpoint path")
+    p.add_argument("--size", type=int, default=256, help="Resize input to this square size")
+    p.add_argument("--temperature", type=float, default=0.38,
+                    help="Annealed-mean decode temperature. Lower = more vivid/mode-like, "
+                         "higher = smoother but can desaturate again. Try 0.15-0.6.")
+    p.add_argument("--saturation-boost", type=float, default=1.0,
+                    help="Extra multiplier on the decoded ab, applied after temperature. "
+                         "1.0 = no extra boost.")
+    p.add_argument("--output-dir", default="./colorized")
+    args = p.parse_args()
+
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    print(f"Loading {args.model} on {device} ...")
+    model = SmallUNetColorizer.from_pretrained(args.model).to(device).eval()
+    print(f"({model.num_bins} color bins)")
+
+    out_dir = Path(args.output_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    for path in args.images:
+        img = Image.open(path)
+        result = colorize(model, img, args.size, args.temperature, args.saturation_boost, device)
+        out_path = out_dir / f"{Path(path).stem}_colorized.png"
+        result.save(out_path)
+        print(f"{path} -> {out_path}")
+
+
+if __name__ == "__main__":
+    main()

legacy/v2/colorize_onnx.py

@@ -0,0 +1,32 @@
+"""Run the exported chroma pipeline without importing PyTorch."""
+import argparse
+from pathlib import Path
+import numpy as np
+import onnxruntime as ort
+from PIL import Image,ImageOps
+from skimage.color import rgb2lab,lab2rgb
+
+def load_session(path,threads=2):
+    opts=ort.SessionOptions();opts.intra_op_num_threads=threads;opts.inter_op_num_threads=1
+    return ort.InferenceSession(str(path),sess_options=opts,providers=['CPUExecutionProvider'])
+
+def colorize(session,image,size=256):
+    if size<8:raise ValueError('size must be at least8')
+    image=ImageOps.exif_transpose(image).convert('RGB')
+    L=rgb2lab(np.asarray(image,dtype=np.float32)/255)[...,0].astype(np.float32)
+    h,w=L.shape;scale=min(size/max(h,w),1)
+    target=(max(8,round(w*scale)),max(8,round(h*scale)))
+    small=np.asarray(Image.fromarray(L).resize(target,Image.Resampling.BILINEAR),dtype=np.float32)
+    x=(small[None,None]/50-1).copy()
+    ab=session.run(['chroma'],{'luminance':x})[0][0]
+    full=np.stack([np.asarray(Image.fromarray(c).resize((w,h),Image.Resampling.BILINEAR)) for c in ab],axis=-1)
+    rgb=np.clip(lab2rgb(np.concatenate([L[...,None],full],axis=-1)),0,1)
+    return Image.fromarray(np.rint(rgb*255).astype(np.uint8))
+
+if __name__=='__main__':
+    p=argparse.ArgumentParser(__doc__);p.add_argument('images',nargs='+');p.add_argument('--model',required=True)
+    p.add_argument('--output-dir',default='colorized');p.add_argument('--size',type=int,default=256);p.add_argument('--threads',type=int,default=2)
+    a=p.parse_args();session=load_session(a.model,a.threads);out=Path(a.output_dir);out.mkdir(parents=True,exist_ok=True)
+    for source in a.images:
+        with Image.open(source) as im:result=colorize(session,im,a.size)
+        dest=out/(Path(source).stem+'_colorized.png');result.save(dest);print(dest)

legacy/v2/colorizer.json

@@ -0,0 +1,54 @@
+{
+  "input": "N,1,H,W Lab L*/50-1; H,W>=8",
+  "output": "N,2,H,W Lab chroma a,b",
+  "guided_radius": 8,
+  "guided_epsilon": 0.001,
+  "temperature": 0.38,
+  "opset": 17,
+  "checks": [
+    {
+      "shape": [
+        1,
+        1,
+        256,
+        256
+      ],
+      "max_ab_difference": 8.58306884765625e-06,
+      "mean_ab_difference": 1.0279118214384653e-06
+    },
+    {
+      "shape": [
+        1,
+        1,
+        173,
+        241
+      ],
+      "max_ab_difference": 7.3909759521484375e-06,
+      "mean_ab_difference": 1.0783561492644367e-06
+    },
+    {
+      "shape": [
+        2,
+        1,
+        64,
+        80
+      ],
+      "max_ab_difference": 7.152557373046875e-06,
+      "mean_ab_difference": 9.707116532808868e-07
+    },
+    {
+      "shape": [
+        1,
+        1,
+        8,
+        9
+      ],
+      "max_ab_difference": 1.5497207641601562e-06,
+      "mean_ab_difference": 3.6218099808138504e-07
+    }
+  ],
+  "parameters": 3968892,
+  "weights_source": "release-v2",
+  "runtime": "1.30.0",
+  "bytes": 15885757
+}

legacy/v2/export_onnx.py

@@ -0,0 +1,48 @@
+"""Export the colorizer AND luminance-guided chroma decoder as one ONNX graph.
+
+Input: N,1,H,W normalized Lab luminance (L*/50-1), minimum8px per side.
+Output: N,2,H,W Lab a,b values. Resize/preserve original L* in the app.
+"""
+import argparse,json
+from pathlib import Path
+import numpy as np
+import torch
+from model import load_model
+from spatial import guided_chroma
+
+class ChromaPipeline(torch.nn.Module):
+    def __init__(self,model,radius=8,temperature=.38):
+        super().__init__();self.model=model;self.radius=radius;self.temperature=temperature
+    def forward(self,L):
+        return guided_chroma(L,self.model.decode(self.model(L),self.temperature),self.radius)
+
+def export(a):
+    import onnx,onnxruntime as ort
+    torch.set_num_threads(2);torch.manual_seed(2026)
+    model=ChromaPipeline(load_model(a.model),a.radius).eval()
+    out=Path(a.output);out.parent.mkdir(parents=True,exist_ok=True)
+    with torch.inference_mode():
+        torch.onnx.export(model,torch.zeros(1,1,256,256),str(out),opset_version=17,
+            input_names=['luminance'],output_names=['chroma'],dynamo=False,
+            dynamic_axes={'luminance':{0:'batch',2:'height',3:'width'},'chroma':{0:'batch',2:'height',3:'width'}})
+    onnx.checker.check_model(str(out))
+    opts=ort.SessionOptions();opts.intra_op_num_threads=2;opts.inter_op_num_threads=1
+    session=ort.InferenceSession(str(out),sess_options=opts,providers=['CPUExecutionProvider'])
+    checks=[]
+    for shape in [(1,1,256,256),(1,1,173,241),(2,1,64,80),(1,1,8,9)]:
+        x=torch.rand(shape)*2-1
+        with torch.inference_mode():expected=model(x).numpy()
+        actual=session.run(None,{'luminance':x.numpy()})[0]
+        error=np.abs(expected-actual)
+        assert actual.shape==expected.shape and np.isfinite(actual).all()
+        np.testing.assert_allclose(actual,expected,atol=.01,rtol=.001)
+        checks.append({'shape':list(shape),'max_ab_difference':float(error.max()),'mean_ab_difference':float(error.mean())})
+    result={'input':'N,1,H,W Lab L*/50-1; H,W>=8','output':'N,2,H,W Lab chroma a,b',
+            'guided_radius':a.radius,'guided_epsilon':.001,'temperature':.38,
+            'opset':17,'checks':checks,'parameters':sum(p.numel() for p in model.parameters()),
+            'weights_source':a.model,'runtime':ort.__version__,'bytes':out.stat().st_size}
+    out.with_suffix('.json').write_text(json.dumps(result,indent=2));print(json.dumps(result,indent=2))
+
+if __name__=='__main__':
+    p=argparse.ArgumentParser(__doc__);p.add_argument('--model',required=True);p.add_argument('--output',required=True);p.add_argument('--radius',type=int,default=8)
+    export(p.parse_args())

legacy/v2/inference.py

@@ -0,0 +1,63 @@
+"""Aspect-preserving inference; infer chroma globally and retain original luminance."""
+import argparse
+import math
+from pathlib import Path
+import numpy as np
+from PIL import Image, ImageOps
+import torch
+import torch.nn.functional as F
+from skimage.color import rgb2lab, lab2rgb
+from model import load_model
+from spatial import guided_chroma
+
+@torch.inference_mode()
+def colorize(model, image, size=256, temperature=0.38, saturation=1.0, flip_tta=False,
+             guided_radius=8, guided_epsilon=.001):
+    if size < 8 or not math.isfinite(saturation) or saturation < 0:
+        raise ValueError("size must be >=8 and saturation finite and nonnegative")
+    image = ImageOps.exif_transpose(image).convert("RGB")
+    rgb = np.asarray(image, dtype=np.float32) / 255.0
+    luminance = rgb2lab(rgb)[..., 0].astype(np.float32)
+    h, w = luminance.shape
+    scale = min(size / max(h, w), 1.0)
+    target = (max(8, round(h*scale)), max(8, round(w*scale)))
+    device = next(model.parameters()).device
+    L = torch.from_numpy(luminance)[None, None].to(device) / 50 - 1
+    small = F.interpolate(L, size=target, mode="bilinear", align_corners=False, antialias=True)
+    logits = model(small)
+    if flip_tta:
+        logits = (logits + model(small.flip(-1)).flip(-1)) * 0.5
+    ab = model.decode(logits, temperature)
+    ab = guided_chroma(small, ab, guided_radius, guided_epsilon)
+    ab = F.interpolate(ab, size=(h,w), mode="bilinear", align_corners=False)
+    ab = ab[0].permute(1,2,0).cpu().numpy() * saturation
+    lab = np.concatenate([luminance[...,None], ab], axis=-1)
+    result = np.clip(lab2rgb(lab), 0, 1)
+    return Image.fromarray(np.rint(result * 255).astype(np.uint8))
+
+def main():
+    p = argparse.ArgumentParser(__doc__)
+    p.add_argument("images", nargs="+")
+    p.add_argument("--model", required=True)
+    p.add_argument("--revision", default=None)
+    p.add_argument("--size", type=int, default=256)
+    p.add_argument("--temperature", type=float, default=.38)
+    p.add_argument("--saturation", type=float, default=1)
+    p.add_argument("--flip-tta", action="store_true")
+    p.add_argument("--guided-radius",type=int,default=8,help="Chroma smoothing radius at model resolution;0 disables")
+    p.add_argument("--guided-epsilon",type=float,default=.001)
+    p.add_argument("--output-dir", default="colorized")
+    p.add_argument("--device", default="cuda" if torch.cuda.is_available() else "cpu")
+    a = p.parse_args()
+    torch.set_num_threads(min(torch.get_num_threads(),4))
+    model = load_model(a.model, a.revision, a.device)
+    out = Path(a.output_dir); out.mkdir(parents=True, exist_ok=True)
+    for file in a.images:
+        with Image.open(file) as im:
+            result = colorize(model, im, a.size, a.temperature, a.saturation, a.flip_tta,
+                              a.guided_radius,a.guided_epsilon)
+        dest = out / (Path(file).stem + "_colorized.png")
+        result.save(dest); print(dest)
+
+if __name__ == "__main__":
+    main()

legacy/v2/model.py

@@ -0,0 +1,122 @@
+"""Shared, checkpoint-compatible Mini U-Net. Parameters remain under 4M."""
+import json
+import math
+from pathlib import Path
+import numpy as np
+import torch
+from torch import nn
+import torch.nn.functional as F
+from huggingface_hub import PyTorchModelHubMixin, snapshot_download
+from safetensors.torch import load_file, save_file
+def double_conv(in_ch, out_ch):
+    return nn.Sequential(
+        nn.Conv2d(in_ch, out_ch, 3, padding=1, bias=False),
+        nn.BatchNorm2d(out_ch),
+        nn.ReLU(inplace=True),
+        nn.Conv2d(out_ch, out_ch, 3, padding=1, bias=False),
+        nn.BatchNorm2d(out_ch),
+        nn.ReLU(inplace=True),
+    )
+
+
+class DilatedContextBlock(nn.Module):
+    def __init__(self, channels, mid_ch=96, dilations=(2, 4, 8)):
+        super().__init__()
+        self.proj_in = nn.Sequential(
+            nn.Conv2d(channels, mid_ch, 1, bias=False),
+            nn.BatchNorm2d(mid_ch),
+            nn.ReLU(inplace=True),
+        )
+        layers = []
+        for d in dilations:
+            layers += [
+                nn.Conv2d(mid_ch, mid_ch, 3, padding=d, dilation=d, bias=False),
+                nn.BatchNorm2d(mid_ch),
+                nn.ReLU(inplace=True),
+            ]
+        self.dilated = nn.Sequential(*layers)
+        self.proj_out = nn.Sequential(
+            nn.Conv2d(mid_ch, channels, 1, bias=False),
+            nn.BatchNorm2d(channels),
+        )
+        nn.init.zeros_(self.proj_out[-1].weight)
+        self.relu = nn.ReLU(inplace=True)
+
+    def forward(self, x):
+        y = self.proj_in(x)
+        y = self.dilated(y)
+        y = self.proj_out(y)
+        return self.relu(x + y)
+
+
+class SmallUNetColorizer(
+    nn.Module,
+    PyTorchModelHubMixin,
+    pipeline_tag="image-to-image",
+    license="apache-2.0",
+    tags=["colorization", "unet", "image-to-image", "classification"],
+):
+    def __init__(self, bin_centers, in_ch: int = 1, base: int = 44,
+                 context_mid_ch: int = 96, context_dilations=(2, 4, 8)):
+        super().__init__()
+        self.in_ch, self.base = in_ch, base
+        num_bins = len(bin_centers)
+        self.num_bins = num_bins
+        self.register_buffer("bin_centers", torch.tensor(bin_centers, dtype=torch.float32))
+
+        self.enc1 = double_conv(in_ch, base)
+        self.enc2 = double_conv(base, base * 2)
+        self.enc3 = double_conv(base * 2, base * 4)
+        self.enc4 = double_conv(base * 4, base * 8)
+        self.pool = nn.MaxPool2d(2)
+        self.context = DilatedContextBlock(base * 8, mid_ch=context_mid_ch,
+                                            dilations=tuple(context_dilations))
+        self.up3 = nn.ConvTranspose2d(base * 8, base * 4, 2, stride=2)
+        self.dec3 = double_conv(base * 8, base * 4)
+        self.up2 = nn.ConvTranspose2d(base * 4, base * 2, 2, stride=2)
+        self.dec2 = double_conv(base * 4, base * 2)
+        self.up1 = nn.ConvTranspose2d(base * 2, base, 2, stride=2)
+        self.dec1 = double_conv(base * 2, base)
+        self.out_conv = nn.Conv2d(base, num_bins, 1)
+
+    def forward(self, x):
+        h, w = x.shape[-2:]
+        x = F.pad(x, (0, (-w) % 8, 0, (-h) % 8), mode="replicate")
+        e1 = self.enc1(x)
+        e2 = self.enc2(self.pool(e1))
+        e3 = self.enc3(self.pool(e2))
+        e4 = self.context(self.enc4(self.pool(e3)))
+        d3 = self.dec3(torch.cat([self.up3(e4), e3], dim=1))
+        d2 = self.dec2(torch.cat([self.up2(d3), e2], dim=1))
+        d1 = self.dec1(torch.cat([self.up1(d2), e1], dim=1))
+        return self.out_conv(d1)[..., :h, :w]
+
+    def decode(self, logits, temperature: float = 0.38):
+        if not math.isfinite(temperature) or temperature <= 0:
+            raise ValueError("temperature must be finite and positive")
+        probs_t = F.softmax(logits.float() / temperature, dim=1)
+        return torch.einsum("bqhw,qc->bchw", probs_t, self.bin_centers)
+
+
+def load_model(source, revision=None, device="cpu"):
+    path = Path(source)
+    if not path.is_dir():
+        path = Path(snapshot_download(source, revision=revision,
+            allow_patterns=["config.json", "model.safetensors"]))
+    config = json.loads((path / "config.json").read_text())
+    state = load_file(str(path / "model.safetensors"))
+    centers = torch.tensor(config["bin_centers"], dtype=torch.float32)
+    if not torch.equal(centers, state["bin_centers"]):
+        raise ValueError("Checkpoint config and state color bins differ; refusing ambiguous decode")
+    model = SmallUNetColorizer(**config)
+    model.load_state_dict(state, strict=True)
+    model.to(device).eval()
+    return model
+
+def save_model(model, path):
+    path = Path(path); path.mkdir(parents=True, exist_ok=True)
+    model.save_pretrained(path)
+    # Mixin config can retain constructor bins; use the actual authoritative buffer.
+    cfg = json.loads((path / "config.json").read_text())
+    cfg["bin_centers"] = model.bin_centers.detach().cpu().tolist()
+    (path / "config.json").write_text(json.dumps(cfg, indent=2))

legacy/v2/requirements-onnx.txt

@@ -0,0 +1,4 @@
+onnxruntime>=1.17
+numpy
+pillow
+scikit-image

legacy/v2/requirements.txt

@@ -0,0 +1,12 @@
+torch>=2.3
+huggingface_hub>=0.24
+safetensors>=0.4
+scikit-image>=0.22
+scipy>=1.11
+pillow>=10
+numpy
+pyarrow
+pytest
+datasets
+torchvision>=0.18
+tqdm

mini-colorizer-v3.zip

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ec6c3e507c15a74faf869d92d6b80e7374d24e990e95176187483905fba2afc6
+size 29784576

model.py

@@ -1,122 +1,8 @@
-"""Shared, checkpoint-compatible Mini U-Net. Parameters remain under 4M."""
-import json
-import math
 from pathlib import Path
-import numpy as np
-import torch
-from torch import nn
-import torch.nn.functional as F
-from huggingface_hub import PyTorchModelHubMixin, snapshot_download
-from safetensors.torch import load_file, save_file
-def double_conv(in_ch, out_ch):
-    return nn.Sequential(
-        nn.Conv2d(in_ch, out_ch, 3, padding=1, bias=False),
-        nn.BatchNorm2d(out_ch),
-        nn.ReLU(inplace=True),
-        nn.Conv2d(out_ch, out_ch, 3, padding=1, bias=False),
-        nn.BatchNorm2d(out_ch),
-        nn.ReLU(inplace=True),
-    )
-
-
-class DilatedContextBlock(nn.Module):
-    def __init__(self, channels, mid_ch=96, dilations=(2, 4, 8)):
-        super().__init__()
-        self.proj_in = nn.Sequential(
-            nn.Conv2d(channels, mid_ch, 1, bias=False),
-            nn.BatchNorm2d(mid_ch),
-            nn.ReLU(inplace=True),
-        )
-        layers = []
-        for d in dilations:
-            layers += [
-                nn.Conv2d(mid_ch, mid_ch, 3, padding=d, dilation=d, bias=False),
-                nn.BatchNorm2d(mid_ch),
-                nn.ReLU(inplace=True),
-            ]
-        self.dilated = nn.Sequential(*layers)
-        self.proj_out = nn.Sequential(
-            nn.Conv2d(mid_ch, channels, 1, bias=False),
-            nn.BatchNorm2d(channels),
-        )
-        nn.init.zeros_(self.proj_out[-1].weight)
-        self.relu = nn.ReLU(inplace=True)
-
-    def forward(self, x):
-        y = self.proj_in(x)
-        y = self.dilated(y)
-        y = self.proj_out(y)
-        return self.relu(x + y)
-
-
-class SmallUNetColorizer(
-    nn.Module,
-    PyTorchModelHubMixin,
-    pipeline_tag="image-to-image",
-    license="apache-2.0",
-    tags=["colorization", "unet", "image-to-image", "classification"],
-):
-    def __init__(self, bin_centers, in_ch: int = 1, base: int = 44,
-                 context_mid_ch: int = 96, context_dilations=(2, 4, 8)):
-        super().__init__()
-        self.in_ch, self.base = in_ch, base
-        num_bins = len(bin_centers)
-        self.num_bins = num_bins
-        self.register_buffer("bin_centers", torch.tensor(bin_centers, dtype=torch.float32))
-
-        self.enc1 = double_conv(in_ch, base)
-        self.enc2 = double_conv(base, base * 2)
-        self.enc3 = double_conv(base * 2, base * 4)
-        self.enc4 = double_conv(base * 4, base * 8)
-        self.pool = nn.MaxPool2d(2)
-        self.context = DilatedContextBlock(base * 8, mid_ch=context_mid_ch,
-                                            dilations=tuple(context_dilations))
-        self.up3 = nn.ConvTranspose2d(base * 8, base * 4, 2, stride=2)
-        self.dec3 = double_conv(base * 8, base * 4)
-        self.up2 = nn.ConvTranspose2d(base * 4, base * 2, 2, stride=2)
-        self.dec2 = double_conv(base * 4, base * 2)
-        self.up1 = nn.ConvTranspose2d(base * 2, base, 2, stride=2)
-        self.dec1 = double_conv(base * 2, base)
-        self.out_conv = nn.Conv2d(base, num_bins, 1)
-
-    def forward(self, x):
-        h, w = x.shape[-2:]
-        x = F.pad(x, (0, (-w) % 8, 0, (-h) % 8), mode="replicate")
-        e1 = self.enc1(x)
-        e2 = self.enc2(self.pool(e1))
-        e3 = self.enc3(self.pool(e2))
-        e4 = self.context(self.enc4(self.pool(e3)))
-        d3 = self.dec3(torch.cat([self.up3(e4), e3], dim=1))
-        d2 = self.dec2(torch.cat([self.up2(d3), e2], dim=1))
-        d1 = self.dec1(torch.cat([self.up1(d2), e1], dim=1))
-        return self.out_conv(d1)[..., :h, :w]
-
-    def decode(self, logits, temperature: float = 0.38):
-        if not math.isfinite(temperature) or temperature <= 0:
-            raise ValueError("temperature must be finite and positive")
-        probs_t = F.softmax(logits.float() / temperature, dim=1)
-        return torch.einsum("bqhw,qc->bchw", probs_t, self.bin_centers)
-
-
+from semantic_model import SemanticColorizer, load_semantic, save_semantic
 def load_model(source, revision=None, device="cpu"):
-    path = Path(source)
-    if not path.is_dir():
-        path = Path(snapshot_download(source, revision=revision,
-            allow_patterns=["config.json", "model.safetensors"]))
-    config = json.loads((path / "config.json").read_text())
-    state = load_file(str(path / "model.safetensors"))
-    centers = torch.tensor(config["bin_centers"], dtype=torch.float32)
-    if not torch.equal(centers, state["bin_centers"]):
-        raise ValueError("Checkpoint config and state color bins differ; refusing ambiguous decode")
-    model = SmallUNetColorizer(**config)
-    model.load_state_dict(state, strict=True)
-    model.to(device).eval()
-    return model
-
-def save_model(model, path):
-    path = Path(path); path.mkdir(parents=True, exist_ok=True)
-    model.save_pretrained(path)
-    # Mixin config can retain constructor bins; use the actual authoritative buffer.
-    cfg = json.loads((path / "config.json").read_text())
-    cfg["bin_centers"] = model.bin_centers.detach().cpu().tolist()
-    (path / "config.json").write_text(json.dumps(cfg, indent=2))
+    from huggingface_hub import snapshot_download
+    path=Path(source)
+    if not path.is_dir(): path=Path(snapshot_download(source,revision=revision,allow_patterns=["config.json","model.safetensors"]))
+    return load_semantic(path,device)
+save_model=save_semantic

model.safetensors

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:0e4c417375684a044860f8af3ac3a2fb44e1a5729254ca33abda758ea71aea6e
-size 15909320
+oid sha256:ec1f27d74533adc83f7ab3639a091fc4d8738a434dafc7d172c7873c28a9e715
+size 16112432

requirements-onnx.txt

@@ -1,4 +1,5 @@
-onnxruntime>=1.17
-numpy
-pillow
-scikit-image
+onnxruntime==1.20.1
+onnx==1.17.0
+numpy==1.26.4
+Pillow==11.1.0
+scikit-image==0.25.2

requirements-space.txt

@@ -0,0 +1,9 @@
+torch==2.8.0
+torchvision==0.23.0
+numpy==1.26.4
+Pillow==11.1.0
+scikit-image==0.25.2
+safetensors==0.5.3
+huggingface-hub>=1.0,<2
+gradio==6.28.0
+spaces==0.51.3

requirements.txt

@@ -1,12 +1,7 @@
-torch>=2.3
-huggingface_hub>=0.24
-safetensors>=0.4
-scikit-image>=0.22
-scipy>=1.11
-pillow>=10
-numpy
-pyarrow
-pytest
-datasets
-torchvision>=0.18
-tqdm
+torch==2.8.0
+torchvision==0.23.0
+numpy==1.26.4
+Pillow==11.1.0
+scikit-image==0.25.2
+safetensors==0.5.3
+huggingface-hub>=1.0,<2

semantic_model.py

@@ -0,0 +1,94 @@
+"""Compact pretrained semantic colorizer; dense and shared-palette variants."""
+import json
+from pathlib import Path
+import torch
+from torch import nn
+import torch.nn.functional as F
+from torchvision.models import mobilenet_v3_large, MobileNet_V3_Large_Weights
+from safetensors.torch import save_file, load_file
+
+class QueryBlock(nn.Module):
+    def __init__(self,d=96):
+        super().__init__()
+        self.self_attn=nn.MultiheadAttention(d,4,batch_first=True,dropout=0)
+        self.cross_attn=nn.MultiheadAttention(d,4,batch_first=True,dropout=0)
+        self.norms=nn.ModuleList([nn.LayerNorm(d) for _ in range(3)])
+        self.ff=nn.Sequential(nn.Linear(d,2*d),nn.GELU(),nn.Linear(2*d,d))
+    def forward(self,q,memory):
+        x=self.norms[0](q);q=q+self.self_attn(x,x,x,need_weights=False)[0]
+        x=self.norms[1](q);q=q+self.cross_attn(x,memory,memory,need_weights=False)[0]
+        return q+self.ff(self.norms[2](q))
+
+def refine(d):
+    return nn.Sequential(nn.Conv2d(d,d,3,padding=1,bias=False),nn.GroupNorm(8,d),nn.SiLU())
+
+class SemanticColorizer(nn.Module):
+    def __init__(self,head='palette',pretrained=False,width=128,queries=16):
+        super().__init__()
+        if head not in ['palette','dense']:raise ValueError(head)
+        self.config={'architecture':'SemanticColorizer','head':head,'width':width,'queries':queries,'format_version':1}
+        self.encoder=mobilenet_v3_large(weights=MobileNet_V3_Large_Weights.IMAGENET1K_V2 if pretrained else None,progress=False).features
+        self.lateral=nn.ModuleList([nn.Conv2d(c,width,1) for c in [24,40,112,960]])
+        self.refine=nn.ModuleList([refine(width) for _ in range(3)])
+        self.register_buffer('rgb_mean',torch.tensor([.485,.456,.406]).view(1,3,1,1))
+        self.register_buffer('rgb_std',torch.tensor([.229,.224,.225]).view(1,3,1,1))
+        if head=='palette':
+            self.queries=nn.Parameter(torch.randn(queries,width)*.2)
+            self.query_blocks=nn.ModuleList([QueryBlock(width) for _ in range(2)])
+            self.memory_norm=nn.LayerNorm(width)
+            self.query_norm=nn.LayerNorm(width)
+            self.pixel=nn.Conv2d(width,width,1)
+            self.palette=nn.Sequential(nn.Linear(width,width),nn.GELU(),nn.Linear(width,2))
+            self.residual=nn.Conv2d(width,2,1)
+            nn.init.normal_(self.palette[-1].weight,std=.01);nn.init.zeros_(self.palette[-1].bias)
+            nn.init.zeros_(self.residual.weight);nn.init.zeros_(self.residual.bias)
+        else:
+            self.dense=nn.Sequential(refine(width),nn.Conv2d(width,2,1))
+            nn.init.normal_(self.dense[-1].weight,std=.01);nn.init.zeros_(self.dense[-1].bias)
+        count=sum(p.numel() for p in self.parameters())
+        if count>=4_000_000:raise ValueError(f'Parameter budget exceeded: {count}')
+
+    @staticmethod
+    def neutral_rgb(L):
+        light=(L.float()*50+50).clamp(0,100)
+        y=torch.where(light>8,((light+16)/116)**3,light/903.296296)
+        g=torch.where(y<=.0031308,12.92*y,1.055*y.clamp_min(1e-8).pow(1/2.4)-.055)
+        return g.expand(-1,3,-1,-1)
+
+    def forward(self,L):
+        h,w=L.shape[-2:]
+        x=F.pad(self.neutral_rgb(L),(0,(-w)%32,0,(-h)%32),mode='replicate')
+        x=(x-self.rgb_mean)/self.rgb_std
+        features=[]
+        for i,layer in enumerate(self.encoder):
+            x=layer(x)
+            if i in [3,6,12,16]:features.append(x)
+        projected=[layer(f) for layer,f in zip(self.lateral,features)]
+        x=projected[-1]
+        for i in range(2,-1,-1):
+            x=self.refine[2-i](F.interpolate(x,size=projected[i].shape[-2:],mode='bilinear',align_corners=False)+projected[i])
+        if self.config['head']=='palette':
+            memory=torch.cat([F.adaptive_avg_pool2d(f,(8,8)).flatten(2).transpose(1,2) for f in projected[1:]],1)
+            memory=self.memory_norm(memory)
+            q=self.queries[None].expand(L.shape[0],-1,-1)
+            for block in self.query_blocks:q=block(q,memory)
+            q=self.query_norm(q)
+            palette=80*torch.tanh(self.palette(q))
+            masks=torch.einsum('bqd,bdhw->bqhw',q,self.pixel(x))/(self.config['width']**.5)
+            weights=F.softmax(masks.float(),dim=1)
+            ab=torch.einsum('bqhw,bqc->bchw',weights,palette.float())+2*torch.tanh(self.residual(x).float())
+        else:ab=80*torch.tanh(self.dense(x).float())
+        return F.interpolate(ab,size=(x.shape[-2]*4,x.shape[-1]*4),mode='bilinear',align_corners=False)[...,:h,:w]
+    def decode(self,z,temperature=.38):return z.float()
+
+def save_semantic(model,path):
+    path=Path(path);path.mkdir(parents=True,exist_ok=True)
+    save_file({k:v.detach().cpu().contiguous() for k,v in model.state_dict().items()},str(path/'model.safetensors'))
+    (path/'config.json').write_text(json.dumps(model.config,indent=2))
+    (path/'README.md').write_text('# Experimental semantic colorizer\n\nHead: '+model.config['head']+'. Parameters: '+str(sum(p.numel() for p in model.parameters()))+'.\n\nNot approved for production. Requires semantic_model.py; incompatible with the old U-Net loader. Input is Lab lightness normalized to [-1,1]; output is Lab ab. See the run protocol, provenance, selection and visual comparisons. Predictions are plausible colors, not recovered historical truth.\n')
+
+def load_semantic(path,device='cpu'):
+    path=Path(path);cfg=json.loads((path/'config.json').read_text())
+    model=SemanticColorizer(**{k:cfg[k] for k in ['head','width','queries']})
+    model.load_state_dict(load_file(str(path/'model.safetensors')),strict=True)
+    return model.to(device).eval()