Add model card, checksums and brightness head

README.md

@@ -0,0 +1,86 @@
+---
+pipeline_tag: image-to-image
+tags:
+- pytorch
+- hirise
+- mars
+- remote-sensing
+- flow-matching
+---
+
+# HiPredict Diffusion
+
+Bidirectional conditional flow-matching checkpoints for reconstructing HiRISE RED4 from IR10, or IR10 from RED4. Use these checkpoints with the [HiPredict Python package](https://github.com/EricKing22/HiPredict).
+
+## Checkpoints
+
+| File | Model | Training steps | Gradient-loss weight |
+| --- | --- | --- | --- |
+| `FM_Condition/latest.pt` | BidirectionalFM, Condition mode | 100,000 | 0.0 |
+| `FM_Condition_gradient/latest.pt` | BidirectionalFM, Condition mode | 100,000 | 0.1 |
+| `brightness/model.pt` | Auxiliary RED3 boundary-residual brightness head | — | — |
+
+Choose either FM checkpoint as the main model. Both support `ir2red` and `red2ir`. The brightness head is optional: the default boundary-based correction does not need it.
+
+Both main checkpoints include model weights, EMA weights, optimizer state, learning-rate scheduler state, and model/training settings. Each file is approximately 2.05 GB. The brightness head is approximately 32 KB.
+
+## Installation
+
+Use a HiPredict checkout containing `hipredict.diffusion` and install its diffusion dependencies from the checkout root:
+
+```bash
+pip install ".[diffusion]"
+```
+
+For evaluation with HiPredict's shared metrics, install `.[diffusion,postprocess]` instead.
+
+## Download and load
+
+```python
+from huggingface_hub import hf_hub_download
+from hipredict.diffusion import load_checkpoint
+
+checkpoint = hf_hub_download(
+    repo_id="syding9/HiPredict_Diffusion",
+    filename="FM_Condition/latest.pt",
+)
+model, model_config, training_config, step = load_checkpoint(
+    checkpoint, device="cuda"
+)
+```
+
+Select `FM_Condition_gradient/latest.pt` for the gradient-loss model.
+
+## HiPredict API
+
+The HiPredict API adapter reconstructs RED4 (`ir2red`), on patches or full strips. Large images are predicted with overlapping tiles.
+
+```python
+from hipredict.diffusion import build_hipredict_predictor
+
+predictor, config, step = build_hipredict_predictor(checkpoint, device="cuda")
+samples = predictor.load("files/data_record_evals.csv", mode="patches")
+predictions = predictor.predict(samples)
+```
+
+For `red2ir`, use the diffusion inference command with the downloaded checkpoint path:
+
+```bash
+python -m hipredict.diffusion.inference.inference     --ckpt_path /path/to/latest.pt     --input_path observation_RED4.npy     --red3_path observation_RED3.npy     --direction red2ir     --output_dir outputs/inference/
+```
+
+## Brightness correction
+
+The default correction uses the RED3 boundary. To use the learned residual brightness head for dataset inference or evaluation, download `brightness/model.pt`, select `--dc_correct head`, and pass its local path as `--head_ckpt`.
+
+## Model configuration
+
+Both FM checkpoints use a 128-channel base width, three residual blocks per level, Sobel edge conditioning, and noise-conditioned flow matching. Their normalization settings are stored in the checkpoint:
+
+- Center: `0.103687465`
+- Scale: `0.04842728`
+- Normalized training values clipped to `[-5, 5]`
+
+HiPredict reads these settings when loading the checkpoint. Evaluation uses original, unclipped physical targets. The checkpoint format is `hipredict.diffusion`, version `1`.
+
+File SHA-256 digests are recorded in `checksums.json`.

brightness/model.pt

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

checksums.json

@@ -0,0 +1,14 @@
+{
+  "FM_Condition/latest.pt": {
+    "sha256": "8aad7235ef7e117bf1bbf3ef55b3e0a76f35b85d884f2f00b1588c0075c26f4d",
+    "size_bytes": 2048582622
+  },
+  "FM_Condition_gradient/latest.pt": {
+    "sha256": "2c1698b8cfb9ad0bc058ec0928a7d4770acefcd10d51da95c39315b44f056484",
+    "size_bytes": 2048582622
+  },
+  "brightness/model.pt": {
+    "sha256": "4bc20b87fe967cbb9856395594c4db5407c474c7bddf2a2e2158d38f7056c131",
+    "size_bytes": 32509
+  }
+}