README.md

---
license: mit
datasets:
- heig-vd-geo/GridNet-HD
language:
- en
metrics:
- mean_iou
---
# GridNet-HD Baseline: Super Point Transformer segmentation

## Overview

This repository is a fork of the [SuperPoint Transformer (SPT)](https://github.com/drprojects/superpoint_transformer) proposed by Robert et al., adapted to support training and inference on the **GridNet-HD** dataset.

Our version introduces the following modifications:

- Integration with the **GridNet-HD** dataset structure.
- Support for exporting **softmax logits per class and per point**, used as inputs for the **third fusion baseline** in our NeurIPS submission.
- Support for full resolution inference.

This implementation serves as one of the **official baselines** provided for GridNet-HD.

For more information on the original SPT architecture, training options, model internals and hyperparameters, please refer to the [official SuperPoint Transformer repository](https://github.com/drprojects/superpoint_transformer).

---

## Table of Contents

* [Configuration](#configuration)
* [Environment](#environment)
* [Dataset Structure](#dataset-structure)
* [Installation](#setup--installation)
* [Supported Modes](#supported-modes)
* [Results](#results)
* [Pretrained Weights](#pretrained-weights)
* [Usage Examples](#usage-examples)
* [License](#license)
* [Contact](#contact)
* [Citation](#citation)

---

## Configuration

The modified configuration files for training on GridNet-HD are available in `config/datamodule/semantic` and `config/experiment/semantic` directory. These include:

- dataset paths compatible with GridNet-HD structure,
- number of classes,
- class mappings.

For all other training parameters (optimizer, scheduler, etc.), we use the defaults from the original SPT repo.


---

## Environment

The following environment was used to train and evaluate the baseline model (detailed requirements are provided by the spt repo).

| Component       | Details                          |
| --------------- | -------------------------------- |
| GPU             | NVIDIA A40 (48 GB VRAM)          |
| CUDA Version    | 12.x                             |
| OS              | Ubuntu 22.04 LTS                 |
| RAM             | 256 GB     |

---

## Dataset Structure

The [GridNet-HD dataset](https://huggingface.co/datasets/heig-vd-geo/GridNet-HD) dataset must be structured as follows for compatibility with this implementation:

```
project_root/
├── data/
│   └── raw/
│       ├── train/
│       │   ├── t1z4/
│       │   │   └── lidar/
│       │   │       └── t1z4.las
│       │   ├── t2z5/
│       │   │   └── lidar/
│       │   │       └── t2z5.las
│       │   └── ...
│       ├── val/
│       │   ├── t1z5b/
│       │   │   └── lidar/
│       │   │       └── t1z5b.las
│       │   └── ...
│       └── test/
│           ├── t1z4/
│           │   └── lidar/
│           │       └── t1z4.las
│           └── ...
```


---

## Setup & Installation

1. **Clone the repository**:
 
   ```bash
   git clone https://huggingface.co/heig-vd-geo/SPT_GridNet-HD_baseline
   cd SPT_GridNet-HD_baseline
   ```

2. **Simply run the installation script** to set up the required environment (given by the spt repo):

```bash
bash install.sh
```

---

## Supported Modes

The following modes are supported in this fork:

- Training on GridNet-HD dataset (with official train.py from spt repo)

- Validation using the same split logic (with officiel eval.py from spt.py)

- Inference on selected split (with inference.py)

- Exporting per-point softmax logits (with inference.py)

For additional informations, refer to [the original SPT documentation](https://github.com/drprojects/superpoint_transformer).

---

### Results

The following table summarizes the per-class Intersection over Union (IoU) scores on the test set at 3D level for the best model. 

| Class                     | IoU (Test set) (%)|
|---------------------------|------------|
| Pylon                     |   92.75     |
| Conductor cable           |   91.05     |
| Structural cable          |   70.51     |
| Insulator                 |   80.60     |
| High vegetation           |   85.15     |
| Low vegetation            |   55.91     |
| Herbaceous vegetation     |   84.64     |
| Rock, gravel, soil        |   40.63     |
| Impervious soil (Road)    |   73.57     |
| Water                     |   3.69      |
| Building                  |   57.38     |
| **Mean IoU (mIoU)**       |   **66.90** |


### Pretrained Weights

🔗 **Pretrained weights** for the best performing model are available for download directly in this repo.


---

## Usage Examples

- Train on GridNet-HD:
```
python src/train.py experiment=semantic/gridnet
```

- Evaluate on GridNet-HD:
```
python src/eval.py experiment=semantic/gridnet  ckpt_path=/path/to/your/checkpoint.ckpt
```
- Inference to obtain full-resolution predictions on test point clouds:
```
python inference.py --mode inference --split test --weights path/to/model.ckpt --root_dir /path/to/data/gridnet/raw
```

- Export Softmax Logits for all splits:
```
python inference.py --mode export_log --weights path/to/model.ckpt --root_dir /path/to/data/gridnet/raw
```

This will export .las files with added sof_log0, sof_log1, ..., sof_logN fields representing softmax scores per class and per point to train the 3rd baseline.

---

## License

This project is open-sourced under the MIT License. The original SuperPoint Transformer repository is licensed under the same MIT Licence.

---

## Contact

For questions, issues, or contributions, please open an issue on the repository.


---

## Citation

If you use this repo in research, please cite:

    GridNet-HD: A High-Resolution Multi-Modal Dataset for LiDAR-Image Fusion on Power Line Infrastructure
    Masked Authors
    Submitted to NeurIPS 2025.