Upload standalone NLOS model, inference code, and verified package

.gitattributes

@@ -1,35 +1 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
 *.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.venv/
+.cache/

README.md

@@ -1,3 +1,159 @@
 ---
-license: mit
+library_name: pytorch
+tags:
+- lidar
+- nlos
+- binary-classification
+- histogram
+- pytorch
+datasets:
+- PeizhaoEdinburgh/Occlusion_Based_NLOS
 ---
+
+# Occlusion-Based NLOS Model
+
+Standalone PyTorch implementation and checkpoint for binary classification of
+32 × 32 × 64 histograms. This package includes the complete inference architecture,
+weights, and saved preprocessing statistics. It does not require the original
+`lidarx` repository and is not a Transformers `AutoModel` package.
+
+## Model
+
+- Architecture: `HistCoarseMultiScaleMLP`; 549,641 parameters.
+- Multiscale coarse histogram projections (32×8×8, 16×8×8, 32×4×4), global
+  statistics, temporal statistics, and spatial projections.
+- Batch normalization, a 128-dimensional projection, gated residual layers,
+  and a 128→64→1 classification head; SiLU activation and dropout 0.2.
+- Output: one logit; sigmoid produces the positive-class score.
+- Threshold: 0.5. Class 0 is negative; class 1 is positive.
+- `best.pt` contains the original state dictionary, training configuration,
+  preprocessing statistics, selected epoch, and validation loss.
+
+The precise physical definition of positive/negative and histogram timing/range
+units require author documentation. This package preserves the original labels.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `best.pt` | Original checkpoint, unchanged |
+| `model.py` | Architecture and feature extraction |
+| `inference.py` | Input validation, preprocessing, model loading, and prediction CLI |
+| `config.json` | Inference configuration and class labels |
+| `preprocess_stats.json` | Saved normalization statistics |
+| `requirements.txt` | Runtime dependencies |
+| `verification.json` | Original-versus-standalone parity results and tested versions |
+| `SHA256SUMS` | Integrity hashes for package files |
+
+## Local inference
+
+Use Python 3.10 or newer. Install a PyTorch build suitable for your hardware if
+needed, then install the remaining requirements:
+
+```bash
+python -m pip install -r requirements.txt
+python inference.py /path/to/sample.h5
+# Optional CUDA inference:
+python inference.py /path/to/sample.h5 --device cuda
+```
+
+The HDF5 key must be `stamped_histogram`, with raw shape `(32, 32, 64)` in
+`(height, width, time_bin)` order. Values must be finite, nonnegative counts.
+Do not pass already normalized data. No test-time augmentation is applied.
+The output JSON contains the logit, positive probability, numeric label, and label name.
+
+From Python, with this folder on the Python import path:
+
+```python
+import h5py
+from inference import load_model, predict
+
+model, config, stats = load_model()
+with h5py.File("sample.h5", "r") as f:
+    result = predict(f["stamped_histogram"][()], model, config, stats)
+print(result)
+```
+
+## Downloading from Hugging Face
+
+Download this model package from
+[`PeizhaoEdinburgh/Occlusion_Based_NLOS_model`](https://huggingface.co/PeizhaoEdinburgh/Occlusion_Based_NLOS_model).
+
+```python
+from huggingface_hub import snapshot_download
+
+folder = snapshot_download(
+    repo_id="PeizhaoEdinburgh/Occlusion_Based_NLOS_model",
+    repo_type="model",
+    # revision="COMMIT_HASH",  # Pin a published commit for reproducibility.
+)
+print(folder)
+```
+
+Run `python /downloaded/folder/inference.py /path/to/sample.h5`. The downloaded
+Python files execute locally, so review the source before running them.
+
+## Exact preprocessing
+
+1. Cast raw counts to NumPy float32.
+2. Compute the total using float64 accumulation. For a positive total, multiply
+   all bins by `10000 / total`; an all-zero histogram remains zero at this step.
+3. Apply `log1p`.
+4. Subtract `0.10141183639534776` and divide by `0.22149132767394814`.
+5. Transpose to `(64, 32, 32)` and add batch/channel axes: `(B, 1, 64, 32, 32)`.
+
+The original checkpoint also records `pixel_photon_count` and `count_power`;
+those settings are inactive for this preprocessing mode.
+
+## Training and recorded evaluation
+
+Source run:
+`20260726_212202_tmf8829_36noise_seed_lhs_plus30_36_global_log_count_coarse_multiscale_h128_d4_aug_standard_hist_coarse_multiscale_mlp`.
+
+Training used the synthetic dataset with 26,600 training, 5,700 validation,
+and 5,700 test samples, seed 42, batch size 64, learning rate 0.001,
+weight decay 0.0001, and D4 spatial augmentation. The selected checkpoint is
+from epoch 50, with the lowest run validation loss, **0.3138319095**.
+No real experimental samples were used for training according to the run artifacts.
+
+| Evaluation | Recorded result |
+|---|---:|
+| Synthetic test accuracy | 0.8626316 |
+| Synthetic test precision | 0.8627589 |
+| Synthetic test recall | 0.8624561 |
+| Synthetic test F1 | 0.8626075 |
+| Synthetic test ROC-AUC | 0.9465309 |
+| Experimental groups 1–5 | 88/100 correct |
+| Additional left/right/long/short groups | 68/80 correct |
+| Combined experimental accuracy | 156/180 = 86.67% |
+
+Metrics above are historical artifacts, not newly recomputed benchmark scores.
+“Best” means lowest validation loss within this run, not best across all models.
+Experimental data use during model selection has not been audited. The synthetic
+split does not establish independence between related clean/noisy scenes.
+
+## Verification
+
+`verification.json` records exact CPU agreement with the original implementation
+for preprocessing and logits on all 180 experimental samples and six synthetic
+samples spanning both labels and clean/noise_1/noise_36 conditions. Boundary
+checks cover zero counts, constant counts, wrong shape, negative counts, and NaNs.
+
+```bash
+sha256sum --check SHA256SUMS
+```
+
+## Intended use and limitations
+
+Research on NLOS histogram classification. Generalization to different sensors,
+scene geometry, or timing calibration is not established. Probability outputs
+have not been shown to be calibrated. The original checkpoint contains provenance
+paths that are not used by the standalone loader.
+
+## License and attribution
+
+A license for these model weights and source code has not been selected. The
+associated dataset's MIT metadata does not automatically license this model.
+Author attribution and a paper citation have not been supplied.
+
+The card follows the [Hugging Face model card format](https://huggingface.co/docs/hub/model-cards).

SHA256SUMS

@@ -0,0 +1,10 @@
+4009e8f5faf67ca3607a646c9b12350d8237e344e6853c59bf9dbad697db3952  .gitattributes
+3e7f345273a9999a6c5e379f8418d7bbc46b7bee5899436384b03bfde7a4e044  .gitignore
+46b438bea76f30462c2164095addfed08cbeb27cec8f856e9be3e0b9767f0fc5  README.md
+6e6b8bf4adbd61f7cdda117498c916c9c098d9a49ef0edecb224a4cac8690f5d  best.pt
+543bfb9a13bfdfde410ed42116267cb8b291c1dfd69f664d214638eca6057526  config.json
+a8a513e9231546bc0b64612673677a466e562a0e8eccafe6b040c042a589069f  inference.py
+52b036003ee5f5a0d4b62f66f5281e60f7775cfa95f003f588c77195272ab240  model.py
+db61d5a67ecfc6fea45be741ea0e185d2add1d7a30c77d197569371a18489ddf  preprocess_stats.json
+0abfce5b440789fe8c39e170023071816ad44e9fa899f8f1e71b164da382d0c7  requirements.txt
+0a3fe2f23144ec52342a3c6096ad8e8646256e6260f2a0a4cb94fbf09801569b  verification.json

best.pt

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

config.json

@@ -0,0 +1,19 @@
+{
+  "architecture": "HistCoarseMultiScaleMLP",
+  "hidden_features": 128,
+  "dropout": 0.2,
+  "input_shape": [
+    32,
+    32,
+    64
+  ],
+  "h5_key": "stamped_histogram",
+  "threshold": 0.5,
+  "id2label": {
+    "0": "negative",
+    "1": "positive"
+  },
+  "epoch": 50,
+  "validation_loss": 0.3138319095184928,
+  "parameters": 549641
+}

inference.py

@@ -0,0 +1,64 @@
+"""Inference on raw (height, width, time-bin) HDF5 histograms."""
+import argparse
+import json
+from pathlib import Path
+
+import h5py
+import numpy as np
+import torch
+from model import HistCoarseMultiScaleMLP
+
+
+def preprocess(histogram, stats):
+    data = np.asarray(histogram, dtype=np.float32)
+    if data.shape != (32, 32, 64):
+        raise ValueError(f'Expected (32, 32, 64), got {data.shape}')
+    if not np.isfinite(data).all() or (data < 0).any():
+        raise ValueError('Histogram counts must be finite and nonnegative')
+    if stats['mode'] != 'photon_count_10000_log1p_standardize':
+        raise ValueError('Unsupported preprocessing mode')
+    total = float(data.sum(dtype=np.float64))
+    if total > 0:
+        data = data * (10000.0 / total)
+    data = np.log1p(data)
+    data = (data - stats['mean']) / max(stats['std'], 1e-6)
+    return torch.from_numpy(np.transpose(data, (2, 0, 1)).copy()).unsqueeze(0).unsqueeze(0)
+
+
+def load_model(model_dir=None, device='cpu'):
+    root = Path(model_dir) if model_dir else Path(__file__).resolve().parent
+    config = json.loads((root / 'config.json').read_text())
+    stats = json.loads((root / 'preprocess_stats.json').read_text())
+    checkpoint = torch.load(root / 'best.pt', map_location='cpu', weights_only=True)
+    if stats != checkpoint['preprocess_stats']:
+        raise ValueError('Preprocessing statistics differ from checkpoint')
+    model = HistCoarseMultiScaleMLP(config['hidden_features'], config['dropout'])
+    model.load_state_dict(checkpoint['model_state'], strict=True)
+    model.to(device).eval()
+    return model, config, stats
+
+
+def predict(histogram, model, config, stats):
+    device = next(model.parameters()).device
+    with torch.inference_mode():
+        logit = model(preprocess(histogram, stats).to(device)).item()
+        probability = torch.sigmoid(torch.tensor(logit)).item()
+    label = int(probability >= config['threshold'])
+    return {'logit': logit, 'probability_positive': probability,
+            'label': label, 'label_name': config['id2label'][str(label)]}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('histogram', type=Path)
+    parser.add_argument('--model-dir', type=Path, default=Path(__file__).resolve().parent)
+    parser.add_argument('--device', default='cpu')
+    args = parser.parse_args()
+    model, config, stats = load_model(args.model_dir, args.device)
+    with h5py.File(args.histogram, 'r') as f:
+        histogram = f[config['h5_key']][()]
+    print(json.dumps(predict(histogram, model, config, stats), indent=2))
+
+
+if __name__ == '__main__':
+    main()

model.py

@@ -0,0 +1,148 @@
+"""Standalone architecture extracted from the original lidarx implementation."""
+import torch
+from torch import nn
+
+
+def coarse_projection_features(x: torch.Tensor) -> torch.Tensor:
+    """Return `projection_coarse_32x8x8` features for `[B, 1, D, H, W]` tensors."""
+    if x.ndim != 5:
+        msg = f"expected input with shape [batch, channel, depth, height, width], got {x.shape}"
+        raise ValueError(msg)
+    if x.shape[1] != 1:
+        msg = f"expected one histogram channel, got {x.shape[1]}"
+        raise ValueError(msg)
+
+    x = x.squeeze(1)
+    depth = x.shape[1]
+    height = x.shape[2]
+    width = x.shape[3]
+    if depth % 32 != 0 or height % 8 != 0 or width % 8 != 0:
+        msg = (
+            "hist coarse projection requires depth divisible by 32 and "
+            f"height/width divisible by 8, got {(depth, height, width)}"
+        )
+        raise ValueError(msg)
+
+    global_features = torch.cat(
+        [
+            x.mean(dim=(1, 2, 3), keepdim=False).unsqueeze(1),
+            x.std(dim=(1, 2, 3), unbiased=False, keepdim=False).unsqueeze(1),
+            x.amin(dim=(1, 2, 3), keepdim=False).unsqueeze(1),
+            x.amax(dim=(1, 2, 3), keepdim=False).unsqueeze(1),
+        ],
+        dim=1,
+    )
+    depth_features = torch.cat(
+        [
+            x.mean(dim=(2, 3)),
+            x.std(dim=(2, 3), unbiased=False),
+        ],
+        dim=1,
+    )
+    row_features = x.mean(dim=(1, 3))
+    col_features = x.mean(dim=(1, 2))
+    coarse = (
+        x.reshape(
+            x.shape[0],
+            32,
+            depth // 32,
+            8,
+            height // 8,
+            8,
+            width // 8,
+        )
+        .mean(dim=(2, 4, 6))
+        .reshape(x.shape[0], -1)
+    )
+    return torch.cat(
+        [global_features, depth_features, row_features, col_features, coarse],
+        dim=1,
+    )
+
+
+def _coarse_grid_features(
+    x: torch.Tensor,
+    *,
+    depth_bins: int,
+    row_bins: int,
+    col_bins: int,
+) -> torch.Tensor:
+    depth = x.shape[1]
+    height = x.shape[2]
+    width = x.shape[3]
+    if depth % depth_bins != 0 or height % row_bins != 0 or width % col_bins != 0:
+        msg = (
+            "hist coarse grid requires dimensions divisible by requested bins, "
+            f"got volume {(depth, height, width)} and bins {(depth_bins, row_bins, col_bins)}"
+        )
+        raise ValueError(msg)
+
+    return (
+        x.reshape(
+            x.shape[0],
+            depth_bins,
+            depth // depth_bins,
+            row_bins,
+            height // row_bins,
+            col_bins,
+            width // col_bins,
+        )
+        .mean(dim=(2, 4, 6))
+        .reshape(x.shape[0], -1)
+    )
+
+
+def multiscale_coarse_projection_features(x: torch.Tensor) -> torch.Tensor:
+    """Return coarse histogram features with added low-resolution context views."""
+    base = coarse_projection_features(x)
+    volume = x.squeeze(1)
+    depth_context = _coarse_grid_features(volume, depth_bins=16, row_bins=8, col_bins=8)
+    spatial_context = _coarse_grid_features(volume, depth_bins=32, row_bins=4, col_bins=4)
+    return torch.cat([base, depth_context, spatial_context], dim=1)
+
+
+class HistCoarseMultiScaleMLP(nn.Module):
+    """Small supervised MLP over multi-scale coarse histogram projections.
+
+    This keeps the strong non-backbone inductive bias of the coarse-only model,
+    but gives the classifier both the best 32x8x8 block view and two coarser
+    context views before a lightweight gated residual head.
+    """
+
+    def __init__(self, hidden_features: int = 128, dropout: float = 0.2) -> None:
+        super().__init__()
+        bottleneck_features = max(1, hidden_features // 2)
+        self.input_norm = nn.LazyBatchNorm1d()
+        self.input_projection = nn.Sequential(
+            nn.LazyLinear(hidden_features),
+            nn.SiLU(inplace=True),
+            nn.Dropout(dropout),
+        )
+        self.residual = nn.Sequential(
+            nn.Linear(hidden_features, hidden_features),
+            nn.SiLU(inplace=True),
+            nn.Dropout(dropout),
+            nn.Linear(hidden_features, hidden_features),
+        )
+        self.gate = nn.Sequential(
+            nn.Linear(hidden_features, hidden_features),
+            nn.Sigmoid(),
+        )
+        self.head = nn.Sequential(
+            nn.LayerNorm(hidden_features),
+            nn.SiLU(inplace=True),
+            nn.Dropout(dropout),
+            nn.Linear(hidden_features, bottleneck_features),
+            nn.SiLU(inplace=True),
+            nn.Dropout(dropout),
+            nn.Linear(bottleneck_features, 1),
+        )
+
+    def forward_features(self, x: torch.Tensor) -> torch.Tensor:
+        """Return the learned 128-D representation immediately before the classifier."""
+        features = self.input_norm(multiscale_coarse_projection_features(x))
+        embedding = self.input_projection(features)
+        return embedding + self.gate(embedding) * self.residual(embedding)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.head(self.forward_features(x))

preprocess_stats.json

@@ -0,0 +1,7 @@
+{
+  "mode": "photon_count_10000_log1p_standardize",
+  "mean": 0.10141183639534776,
+  "std": 0.22149132767394814,
+  "pixel_photon_count": 1000.0,
+  "count_power": 0.75
+}

requirements.txt

@@ -0,0 +1,4 @@
+torch>=2.5.1
+numpy>=1.24
+h5py>=3.8
+huggingface_hub>=0.24

verification.json

@@ -0,0 +1,16 @@
+{
+  "samples_compared": 186,
+  "experimental_samples": 180,
+  "synthetic_samples": 6,
+  "preprocessing_exact_match": true,
+  "logits_exact_match": true,
+  "maximum_absolute_logit_difference": 0,
+  "checkpoint_sha256": "6e6b8bf4adbd61f7cdda117498c916c9c098d9a49ef0edecb224a4cac8690f5d",
+  "parameters": 549641,
+  "validation_device": "cpu",
+  "tested_versions": {
+    "torch": "2.5.1+cu121",
+    "numpy": "2.4.6",
+    "h5py": "3.16.0"
+  }
+}