README.md

---
license: apache-2.0
library_name: pytorch
pipeline_tag: image-to-image
tags:
  - hyperspectral-imaging
  - long-wave-infrared
  - thermal-infrared
  - temperature-emissivity-texture
  - lwir
  - hadar
  - tex-1500
  - arxiv:2606.03806
datasets:
  - jialelin2007/TeX-1500
metrics:
  - mean_absolute_error
  - mean_squared_error
  - spectral_angle_mapper
model-index:
  - name: TeX-UNet-v2 DARPA
    results:
      - task:
          type: image-to-image
          name: LWIR HSI to TeX decomposition
        dataset:
          name: TeX-1500 DARPA IH-test
          type: jialelin2007/TeX-1500
        metrics:
          - name: T MAE
            type: mean_absolute_error
            value: 7.3284
            unit: K
          - name: e MSE
            type: mean_squared_error
            value: 0.0453
          - name: X MSE
            type: mean_squared_error
            value: 0.0311
      - task:
          type: image-to-image
          name: LWIR HSI to TeX decomposition
        dataset:
          name: TeX-1500 FTIR-zeroshot-test
          type: jialelin2007/TeX-1500
        metrics:
          - name: T MAE
            type: mean_absolute_error
            value: 5.8309
            unit: K
          - name: e MSE
            type: mean_squared_error
            value: 0.0674
          - name: X MSE
            type: mean_squared_error
            value: 0.0219
  - name: TeX-UNet-v2 FTIR Few-shot
    results:
      - task:
          type: image-to-image
          name: LWIR HSI to TeX decomposition
        dataset:
          name: TeX-1500 FTIR-fewshot-test
          type: jialelin2007/TeX-1500
        metrics:
          - name: T MAE
            type: mean_absolute_error
            value: 4.1004
            unit: K
          - name: e MSE
            type: mean_squared_error
            value: 0.0458
          - name: X MSE
            type: mean_squared_error
            value: 0.0220
---

# TeX-UNet

TeX-UNet is the initial wavelength-aware neural baseline for
[TeX-1500](https://huggingface.co/datasets/jialelin2007/TeX-1500), a paired
real-world LWIR hyperspectral benchmark for temperature-emissivity-texture
decomposition. Given a calibrated LWIR HSI cube and its wavelength positions,
TeX-UNet predicts temperature `T`, emissivity `e`, and texture `X`.

This repository releases two inference checkpoints from
[TeX-1500: A Paired Real-World LWIR Hyperspectral Dataset and Benchmark for
Temperature-Emissivity-Texture Decomposition](https://arxiv.org/abs/2606.03806).

## Authors

- Cheng Dai ([Hugging Face](https://huggingface.co/dccc2025), [GitHub](https://github.com/dccc2025))*
- Jiale Lin ([Hugging Face](https://huggingface.co/jialelin2007), [GitHub](https://github.com/jialelin2007))*
- Hongyi Xu
- Bingxuan Song
- Ziyang Xie
- Fanglin Bao

*Equal Contribution.

## Links

- Hugging Face Papers: [TeX-1500](https://huggingface.co/papers/2606.03806)
- arXiv: [2606.03806](https://arxiv.org/abs/2606.03806)
- Dataset: [jialelin2007/TeX-1500](https://huggingface.co/datasets/jialelin2007/TeX-1500)
- Code: [dccc2025/TeX-1500](https://github.com/dccc2025/TeX-1500)
- Model: [dccc2025/TeX-UNet](https://huggingface.co/dccc2025/TeX-UNet)

## Files

```text
TeX-UNet/
  README.md
  LICENSE
  CITATION.cff
  NOTICE
  model_index.json
  verification.json
  requirements.txt
  docs/reproducibility.md

  tex_unet_v2_darpa/
    model.safetensors
    config.json
    normalization.json
    inference_config.yaml
    training_config.json
    metrics.json
    conversion.json

  tex_unet_v2_ftir_fewshot/
    model.safetensors
    config.json
    normalization.json
    inference_config.yaml
    training_config.json
    metrics.json
    conversion.json
```

## Checkpoints

| Directory | Training data | Intended use | Parameters |
|---|---|---|---:|
| `tex_unet_v2_darpa` | DARPA IH training split | DARPA IH test and FTIR zero-shot transfer | 34.28M |
| `tex_unet_v2_ftir_fewshot` | FTIR few-shot split, initialized from `tex_unet_v2_darpa` | FTIR few-shot transfer | 34.28M |

Both checkpoints are stored as `safetensors` and contain only the model state
dict, not optimizer state.

Each checkpoint uses the same TeX-UNet-v2 architecture:

- input HSI tensor: `[B, 64, H, W]`
- input wavelength tensor: `[64]` or `[B, 64]`, in micrometers
- outputs:
  - `T`: `[B, 1, H, W]`, temperature
  - `e`: `[B, 64, H, W]`, spectral emissivity
  - `X`: `[B, 1, H, W]`, texture
- wavelength range: 6-14 micrometers
- inference tiling: `224 x 224` patches, stride `112`, raised-cosine blending
- released parameter count: `34,279,155`

## Benchmark

The initial benchmark reports TeX-UNet inversion results on held-out DARPA IH
pushbroom scenes and FTIR zero-/few-shot transfer scenes.

| Test split | Checkpoint | T MAE (K) | T MAPE (%) | e MSE | e SAM (rad) | X MSE | X SAM (rad) |
|---|---|---:|---:|---:|---:|---:|---:|
| DARPA IH-test | `tex_unet_v2_darpa` | 7.3284 | 2.5488 | 0.0453 | 0.2267 | 0.0311 | 0.5206 |
| FTIR-zeroshot-test | `tex_unet_v2_darpa` | 5.8309 | 1.9753 | 0.0674 | 0.0451 | 0.0219 | 0.2995 |
| FTIR-fewshot-test | `tex_unet_v2_ftir_fewshot` | 4.1004 | 1.3830 | 0.0458 | 0.1970 | 0.0220 | 0.2224 |

`e` and `X` are normalized. Full training settings, inference tiling, and
evaluation details are in the paper and in each checkpoint directory's
`training_config.json`, `normalization.json`, and `inference_config.yaml`.

## Use With The Code Repository

Install the released inference code from GitHub:

```bash
git clone https://github.com/dccc2025/TeX-1500
cd TeX-1500
uv sync
```

Download one checkpoint:

```bash
uv run python scripts/download_weights.py \
  --repo-id dccc2025/TeX-UNet \
  --filename tex_unet_v2_darpa/model.safetensors \
  --output checkpoints/tex_unet_v2_darpa.safetensors
```

Run inference with a calibrated HSI `.mat` file:

```bash
uv run tex1500-infer \
  --checkpoint checkpoints/tex_unet_v2_darpa.safetensors \
  --model-config configs/tex_unet_v2_model.json \
  --input /path/to/hsi.mat \
  --output outputs/sample_tex_prediction.npz
```

The input `.mat` should contain an HSI cube and wavelength positions compatible
with the TeX-1500 data format. See the GitHub repository for the exact CLI
arguments and output format.

## Loading The Weights

```python
from pathlib import Path
from huggingface_hub import hf_hub_download
from safetensors.torch import load_file

weights = hf_hub_download(
    repo_id="dccc2025/TeX-UNet",
    filename="tex_unet_v2_darpa/model.safetensors",
)
state_dict = load_file(weights, device="cpu")
print(len(state_dict))
```

To verify a checkpoint against the TeX-1500 codebase:

```bash
python scripts/verify_load.py \
  --code-root /path/to/TeX-1500 \
  --model-dir tex_unet_v2_darpa
```

## Data

The dataset is hosted separately at
[jialelin2007/TeX-1500](https://huggingface.co/datasets/jialelin2007/TeX-1500).
The local dataset release notes describe TeX-1500 as a paired LWIR HSI benchmark
with 1,522 calibrated real-scene HSI-TeX pairs from DARPA pushbroom data and
FTIR acquisitions.

The dataset repository is separate from this model repository. The current
dataset release is a preview containing one example sample for format inspection
and visualization; the full dataset is planned for a later release.

Current preview layout:

```text
data/sample_0001/
  hsi.mat
  hsi_noisy.mat
  T.mat
  e.mat
  X.mat
  previews/
    T.png
    e.png
    X.png
    hsi_band.png
```

The preview `.mat` files use MATLAB v5 format:

| File | Variable | Shape | Dtype | Description |
|---|---|---:|---|---|
| `hsi.mat` | `denoised_hsi_original` | `[260, 1500, 256]` | `single` | Denoised calibrated LWIR HSI cube. |
| `hsi.mat` | `hsi_wav` | `[1, 256]` | `double` | HSI wavelength grid. |
| `hsi.mat` | `good_band_indices` | `[1, 230]` | `int64` | 0-indexed valid band indices used by the processing pipeline. |
| `hsi.mat` | `calibrated_sky` | `[1, 256]` | `double` | Calibrated sky signal estimate. |
| `hsi.mat` | `observed_sky` | `[1, 256]` | `double` | Observed sky signal estimate. |
| `hsi.mat` | `working_wav` | `[1, 256]` | `single` | Calibrated working wavelength grid. |
| `hsi_noisy.mat` | `hsi_noisy` | `[260, 1500, 256]` | `single` | Noisy input HSI cube. |
| `T.mat` | `T` | `[260, 1500]` | `single` | Temperature field. |
| `e.mat` | `e` | `[260, 1500, 256]` | `single` | Spectral emissivity field. |
| `X.mat` | `X` | `[260, 1500]` | `single` | Texture field. |

Preview PNG files are for visual inspection only and should not be treated as
numeric labels.

If the Hugging Face dataset repository requires authentication, log in and
accept its access terms before downloading files:

```bash
hf auth login
hf download jialelin2007/TeX-1500 \
  data/sample_0001/hsi.mat data/sample_0001/T.mat \
  --repo-type dataset \
  --local-dir data/tex1500_sample
```

The dataset license and access terms are governed by the dataset repository.

## License

This model repository is released under Apache-2.0. The TeX-1500 dataset files
are hosted separately and are distributed under the PolyForm Noncommercial
License 1.0.0 in the dataset repository. TeX-1500 dataset files are not included
in this model repository.

## Limitations

- TeX-UNet is an initial supervised baseline, not a complete physical inverse
  solver.
- Predictions depend on calibrated LWIR HSI inputs and valid wavelength
  positions; unsupported sensors or uncalibrated radiance can degrade results.
- The released checkpoints target TeX-1500-style normalized `e` and `X` outputs.
- The benchmark is reported on the paper's held-out DARPA IH and FTIR splits;
  use caution when interpreting results outside these settings.

## Citation

```bibtex
@misc{dai2026tex1500pairedrealworldlwir,
      title={TeX-1500: A Paired Real-World LWIR Hyperspectral Dataset and Benchmark for Temperature-Emissivity-Texture Decomposition},
      author={Cheng Dai and Jiale Lin and Hongyi Xu and Bingxuan Song and Ziyang Xie and Fanglin Bao},
      year={2026},
      eprint={2606.03806},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2606.03806},
}
```