Upload standalone NLOS model, inference code, and verified package

97fd768 verified 27 days ago

6.21 kB

---
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).

	---
	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).