File size: 3,488 Bytes
ec4cc48 9304719 ec4cc48 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 | # Inference guide
Run commands from the repository root after following the environment and
checkpoint setup in the root README.
```bash
python files_inference.py --help
bash scripts/run_demo.sh
python files_inference.py --input /path/to/panoramas --output outputs/batch
CUDA_VISIBLE_DEVICES=0 python files_inference.py --input /path/to/pano.jpg --save-views
```
| Option | Default | Purpose |
| --- | --- | --- |
| `--input` | Repository `examples/` | One image or non-recursive directory |
| `--checkpoint` | `checkpoints/pytorch_model.bin` | GeoPano state dictionary |
| `--output` | Repository `outputs/` | Per-image result root |
| `--device` | `cuda` | `cuda` or `cpu` |
| `--precision` | `auto` | `auto`, `fp32`, `fp16`, `bf16` |
| `--save-views` | Off | Also save ten perspective RGB images and PLY clouds |
| `--overwrite` | Off | Permit updates to existing results |
Auto precision selects BF16 on supported CUDA devices, otherwise FP16. CPU uses
FP32. View count and resolution are fixed to match checkpoint attention geometry.
Each input is processed independently. Duplicate filename stems are rejected.
Overwrite replaces generated files; use a new output directory for a clean run.
## Loading outputs
```python
from pathlib import Path
import numpy as np
result = Path('outputs/real_samples/0db658dc49514ca18be7b44ceb363849')
xyz = np.load(result / 'pano_points.npy')
depth = np.load(result / 'pano_depth.npy')
valid = np.isfinite(xyz).all(axis=-1) & (depth > 0)
points = xyz[valid]
assert np.allclose(depth[valid], np.linalg.norm(points, axis=-1))
```
XYZ is float32 with shape `(1440, 2880, 3)`; depth has shape `(1440, 2880)`.
Depth is radial distance, not perspective Z-depth. No external metric calibration
is applied. Invalid values are zero. Coordinates follow the original panorama
geometry convention. The PNG mask uses 255 for valid pixels. Depth visualization
uses a separate min-to-99th-percentile range for each image and is not numeric depth.
Use MeshLab, CloudCompare, or Open3D to open the colored PLY. No mesh or
multi-panorama registration is generated.
## Troubleshooting
- Missing weights: supply the complete GeoPano inference checkpoint. Public
download the published weights from https://huggingface.co/ouou123/GeoPano/resolve/main/checkpoints/pytorch_model.bin; Pi3/VGGT weights cannot replace it.
- Incompatible checkpoint: loading is strict and strips only `module.` prefixes.
A complete checkpoint must include the trained attention mask.
- CUDA unavailable: check PyTorch, driver, scheduler allocation, and environment.
Explicit CPU mode is possible but has not passed full inference validation.
- GPU memory errors: inspect `nvidia-smi` for other jobs. Use mixed precision or
a GPU with more available memory. Fewer input files do not reduce the peak
memory of one panorama. Do not arbitrarily change the fixed view count.
- Invalid predictions: try `--precision fp32` if GPU memory permits.
- RoPE/xFormers warnings: pure PyTorch fallback is expected; custom extensions
are not required.
- Slow first run: geometry caches are created in the source tree and reused.
Keep the checkout writable and avoid concurrent first runs in one checkout.
- Headless Open3D import errors: install system runtime libraries, such as
`libgl1` and `libgomp1` on an Ubuntu-compatible machine.
- Outdoor skies: the experimental sky-segmentation branch is not included in
this release. Sky and distant-region geometry can be unreliable.
|