docs/inference.md

Inference guide

Run commands from the repository root after following the environment and checkpoint setup in the root README.

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

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.