# HorizonNet: room corners from a panorama, on a stack pinned to 2021

> HorizonNet is a pure Python implementation of a CVPR 2019 room layout method, delivered as three scripts you run in sequence, and the most consequential detail for a new user is the environment it was tested on rather than the architecture it implements.

**sunset1995/HorizonNet** — Pytorch implementation of HorizonNet: Learning Room Layout with 1D Representation and Pano Stretch Data Augmentation.

- Repository: https://github.com/sunset1995/HorizonNet
- Website: https://sunset1995.github.io/HorizonNet/
- Stars: 372 · Forks: 95
- Language: Python
- License: MIT
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/sunset1995-horizonnet

## The whole workflow is three scripts run in sequence

Inference on your own image is documented as three numbered steps with one command each, and the file naming convention is the contract between them. The first aligns the camera rotation pose and dumps an aligned RGB image, a line segment image, and a vanishing point matrix, all prefixed with the source image's basename:

```bash
python preprocess.py --img_glob assets/demo.png --output_dir assets/preprocessed/
```

The second consumes that aligned image and predicts the layout:

```bash
python inference.py --pth ckpt/resnet50_rnn__mp3d.pth --img_glob assets/preprocessed/demo_aligned_rgb.png --output_dir assets/inferenced --visualize
```

The third renders the result:

```bash
python layout_viewer.py --img assets/preprocessed/demo_aligned_rgb.png --layout assets/inferenced/demo_aligned_rgb.json --ignore_ceiling
```

The preprocessing script also accepts shell-style wildcards when quoted, so a directory of panoramas can be passed at once, and both scripts document a help flag for the full option list.

## Inference returns corners and a height pair, cuboid on request

The prediction step writes two files. One is the raw one-dimensional representation the network produces, saved as a PNG when the visualisation flag is present, which is the tensor you would look at when a prediction looks wrong. The other is the extracted layout as JSON, named after the input, and it holds a pair of values called z0 and z1 alongside a uv array of corner coordinates. Those corners are the output anyone downstream actually wants. The flags decide what they mean. A `--force_cuboid` option restricts the output to a cuboid layout with four walls, which is the cheaper and more constrained problem, and the default path estimates general shaped rooms instead. The preprocessing stage is what makes those coordinates meaningful, since it corrects the rotation pose so the output is Manhattan aligned, and the vanishing point file it writes is a three by three matrix of the estimated camera rotation.

## Pano stretch augmentation is offered as something to copy elsewhere

The feature list is written less like a changelog and more like a set of things worth stealing. Alongside inference and the 3D viewer, it lists correcting the rotation pose to ensure Manhattan alignment, and it lists the pano stretch augmentation as copy and paste material you can apply to your own task, which is an unusual thing for a repository to advertise and tells you the augmentation is a self-contained piece of code rather than an internal detail. The same list covers quantitative evaluation, naming 2D IoU, 3D IoU, Corner Error and Pixel Error for cuboid and general shape separately, which matches the two evaluation scripts in the repository, one per shape. The last item is preparing and training on your own dataset, so the repository is positioned as a starting point for your data rather than a fixed benchmark.

## The viewer section says point cloud while the update note says mesh

There is a documented inconsistency left over from a March 2021 change. The update log records two changes on 21 March 2021, using a mesh instead of a point cloud as the layout viewer, and updating the line segment detector dependency. The viewer section still describes the step as visualising the predicted layout in 3D using a point cloud, and the dependencies list still carries Open3D at version 0.7 or newer for the 3D viewer. The renderer flag `--ignore_ceiling` is documented alongside it, which drops the ceiling from the view so the walls and floor are visible. If you are reading the viewer section to work out what you will see, trust the update note over the prose.

## Four checkpoints, one per dataset, each with its own data setup

Pretrained weights are published on the Hugging Face hub, and there are four ResNet-50 recurrent checkpoints, one per training source, with the panorama counts given for three of them: `resnet50_rnn__panos2d3d.pth` trained on 817 PanoContext with Stanford2D3D panoramas, `resnet50_rnn__st3d.pth` on 18362 Structured3D panoramas with original furniture and lighting, `resnet50_rnn__mp3d.pth` on Matterport3D, and `resnet50_rnn__zind.pth` on 20077 Zillow Indoor panoramas prepared with the layout_visible, is_primary, is_inside and is_ceiling_flat fields. One line sits above that list and is easy to scroll past: downloading the weights is stated to mean agreeing to the licence and terms of usage of the training datasets. Fetching them is a one-liner from the command line with huggingface-cli, or a call to hf_hub_download with a repository id, a filename and a local directory.

## The general-shape split is 65 rooms the authors re-annotated

Training data is organised into a layoutnet_dataset directory with four splits, and the provenance of each is stated. The train, valid and test splits are processed from LayoutNet's cuboid dataset. The fourth, finetune_general, is different: the authors re-annotated it themselves from train and valid, and it contains 65 general shaped rooms, which is a small number and explains why the cuboid checkpoint is the better default for a first run. The preprocessed panoramas for PanoContext with Stanford2D3D come as a single download that is unpacked under a `data` directory. The other two datasets are not included, and each has its own tutorial instead, with README_ST3D.md, README_ZInD.md and a separate README_PREPARE_DATASET.md at the top level handling preparation for the remaining sources.

## PyTorch 1.8.1 on Python 3.7.6 is the tested combination

The installation section says PyTorch is machine dependent and then names the version that was actually tested, PyTorch 1.8.1 with Python 3.7.6. Everything else follows from that: the dependency list is unpinned apart from a floor of 3.1 for opencv-python used in preprocessing and 0.7 for Open3D used in the 3D viewer, and it runs to numpy, scipy, scikit-learn, Pillow, tqdm, tensorboardX, the pylsd line segment detector and shapely. A conda environment file is present at the top level, which is the practical route for reproducing the tested combination. For a branch that was pushed in June 2026, the gap between the tested stack and a current one is the main thing to plan around, and the two version floors that do exist are on the image processing dependencies rather than on the framework.

## Update notes stop in 2021 while commits continue

The update log is a dated list of six entries and the last one is 4 November 2021, reporting results on the Zillow Indoor dataset. Before that: April 2021 pointing readers to a newer project on the same task and more, March 2021 for the mesh viewer and detector update, August 2019 for Structured3D results, and June 2019 for a bug fix to general layout across dataset.py, inference.py and misc/post_proc.py. The branch itself was last pushed on 7 June 2026, four and a half years after the final note, and there are no tagged releases, so there is no version to pin and nothing that distinguishes a release from a random commit. The top level also carries a committed .DS_Store file, which is the kind of artifact that should have stayed out of the tree.

## Conclusion

HorizonNet fits someone who needs room layout corners from a 360 degree image and who wants the pano stretch augmentation and the Manhattan rotation correction they can lift into another task, since the feature list treats both as copy and paste material. It fits badly if you need a current environment without work, because the tested stack is PyTorch 1.8.1 on Python 3.7.6 and the dependency list includes a line segmentation package plus Open3D for the viewer. Three things to check before planning around it. The update notes stop at 4 November 2021 while the branch was last pushed on 7 June 2026, so those notes are not a changelog. The layout viewer section still describes a point cloud even though the March 2021 note says the viewer moved to a mesh. And the four published checkpoints carry a condition, since downloading the weights is stated to mean agreeing to the licence and terms of the training datasets, which is worth reading before shipping anything built on the Structured3D, Matterport3D or Zillow Indoor checkpoints. MIT licensed, no tagged releases.

## FAQ

### What is HorizonNet?

HorizonNet here is a PyTorch implementation of the CVPR 2019 work on learning room layout from a one-dimensional representation with pano stretch data augmentation. It takes a 360 degree room image and predicts the layout corners, either as a cuboid with four walls or as a general shaped room.

### Which scripts does the HorizonNet inference workflow use?

Three, in order. preprocess.py corrects the camera rotation pose and writes an aligned image, a line segment image and a vanishing point matrix, inference.py turns that into a layout JSON plus an optional raw visualisation, and layout_viewer.py renders the predicted layout in 3D with an option to ignore the ceiling.

### Which pretrained HorizonNet models can I download?

Four ResNet-50 recurrent checkpoints on the Hugging Face hub, trained on PanoContext with Stanford2D3D at 817 panoramas, Structured3D at 18362, Matterport3D, and the Zillow Indoor dataset at 20077 panoramas. The documentation states that downloading the weights means agreeing to the licence and terms of usage of the training datasets.

### What data do I need to train HorizonNet myself?

The preprocessed PanoContext with Stanford2D3D set goes into a data directory as layoutnet_dataset with train, valid, test and finetune_general splits. The first three come from LayoutNet's cuboid dataset, and finetune_general was re-annotated by the authors to hold 65 general shaped rooms. Structured3D and Zillow Indoor each have their own preparation tutorial.

### What metrics does HorizonNet report?

2D IoU, 3D IoU, Corner Error and Pixel Error, evaluated separately for cuboid and general shaped layouts. The repository carries two evaluation scripts, one for each case, named eval_cuboid.py and eval_general.py.

## Sources

- [Issues](https://github.com/sunset1995/HorizonNet/issues)
- [License: MIT](https://github.com/sunset1995/HorizonNet/blob/master/LICENSE)
- [Project website](https://sunset1995.github.io/HorizonNet/)
- [README](https://github.com/sunset1995/HorizonNet/blob/master/README.md)
- [sunset1995/HorizonNet on GitHub](https://github.com/sunset1995/HorizonNet)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sunset1995-horizonnet