eelab-dev/Occlusion_Based_NLOS_model

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:

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:

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.

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.

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.