Superpoint Transformer: A PyTorch Stack for Superpoint-Based 3D Segmentation and Panoptic Clustering

The problem SPT solves is the cost of attention over raw points

Dense self-attention over a large 3D scene is expensive because the token count is the point count. Superpoint Transformer takes a different route: it first partitions the cloud into superpoints, then runs attention over superpoints at several scales. The README describes this as a fast partitioning algorithm that builds a hierarchical superpoint structure, plus a self-attention mechanism that exploits relationships between superpoints at multiple scales. The payoff claimed in the README is size and time: 212k parameters, with S3DIS training in 3h on 1 GPU, and preprocessing described as x7 faster than SPG. Those are the project's own figures, not independently reproduced here. The audience is narrow and identifiable. It is researchers and engineers working on large-scale 3D semantic segmentation who already accept superpoint pipelines and want the specific SPT formulation, or who want the partitioner as a preprocessing step for something else. If your scenes are small enough that per-point models fit comfortably in memory, the superpoint stage is an extra moving part with no obvious return.

Three papers, one repository, and how the three methods relate

The repository is the official implementation for three separate papers: Superpoint Transformer (ICCV'23) for semantic segmentation, SuperCluster (3DV'24 Oral) for panoptic segmentation, and EZ-SP (ICRA'26) for fast and lightweight superpoint-based segmentation. SuperCluster is described as building on SPT and reformulating panoptic segmentation as superpoint graph clustering. The mechanism is worth stating precisely because it is the least conventional part: the model is trained to predict the input parameters of a graph optimization problem whose solution is a panoptic segmentation. Supervision comes from per-node and per-edge objectives only, which the README frames as a way to avoid computing an actual panoptic segmentation and the associated matching at train time. At inference, a parallelized algorithm solves that small graph optimization to produce instances. The README claims fewer than 1M parameters for SuperCluster and says it can process very large scenes at once on a single GPU. That claim is the project's, and the phrase unprecedented scale is the README's framing rather than a measured bound.

The training stack is Lightning plus Hydra, and that shapes everything

The badges at the top of the README pin the stack: Python 3.8+, PyTorch 2.2+, Lightning 2.2+, and Hydra 1.3 for configuration. The repository is derived from the lightning-hydra-template, which is where the MIT licence badge links. In practice this means experiment configuration lives in Hydra config files rather than in Python constructors, and training loops, checkpointing and logging are Lightning's responsibility. The upside is that switching between SPT, SuperCluster and EZ-SP is a config change rather than a code fork. The cost is that nothing runs without the config tree being correct, and Hydra's composition rules become part of your debugging surface. If your team has no prior exposure to Hydra, budget time for that before you budget time for the model. The README also points to a video tutorial and project pages for each paper, which is where a new user should start, since the README itself is closer to a paper landing page than an installation guide.

What you can and cannot confirm about getting it running

This is the weakest part of the supplied material, and it should be said plainly. The README excerpt contains no installation command, no conda or pip invocation, no entry-point script name, and no dataset preparation instructions. The only concrete environment facts available are the version pins in the badges: Python 3.8 or newer, PyTorch 2.2 or newer, Lightning 2.2 or newer, Hydra 1.3. The presence of Hydra means training is launched through Hydra's command-line overrides against a config name, but the specific config names for SPT, SuperCluster and EZ-SP are not given in the material provided, so I will not invent them. What can be stated is the shape of the workflow: prepare a dataset in the format the configs expect, select the config for the paper you want, and launch training through the Hydra entry point with overrides for dataset paths and hardware. Treat the video tutorial and the three project pages as the actual onboarding path. Anyone evaluating this repository should read the full README and the config directory before assuming the setup is documented.

The partitioner is the reusable component, and the model is the specialised one

A useful way to read this repository is as two artifacts with different half-lives. The first is the superpoint partitioning algorithm, which turns a point cloud into a hierarchical superpoint structure. That is a general preprocessing step and the README's x7-faster-than-SPG claim is about exactly this stage. The second is the transformer that consumes those superpoints for semantic or panoptic segmentation. If your problem is segmentation, you need both. If your problem is something else that benefits from a coarse graph over a large cloud, the partitioner alone may be the part you want, and the training harness is then irrelevant to you. The README does not present the partitioner as a standalone library with its own API, so extracting it means reading the source rather than importing a documented module. That is a real friction point, and it is the kind of thing that separates a research repository from a tool.

Where this is the wrong tool

The clearest failure mode is expecting library-grade stability. There are no retrieved releases, which means no tagged versions, no changelogs and no compatibility guarantees between commits. If you vendor this into a product, you are tracking master. The second limitation is scope: the README's reported results are on S3DIS, KITTI-360 and DALES. Nothing in the material indicates support for arbitrary sensor modalities, indoor versus outdoor transfer, or datasets outside that family, and the config-driven design means adding a dataset is a code task, not a config task. Third, the repository is a research artifact for three papers with different publication dates. The ICCV'23, 3DV'24 and ICRA'26 code paths coexist, and the maintenance burden of keeping three method variants working against a moving PyTorch and Lightning is real. Finally, if your scenes are small, or if your accuracy target is already met by a per-point model, the partitioning stage adds preprocessing time and a second source of error for no benefit.

The obvious alternative and the actual difference in approach

The README itself names the comparison point: SPG, the superpoint graph work at loicland/superpoint_graph, against which SPT claims x7 faster preprocessing. The difference is not just speed. SPG builds a superpoint graph and then applies graph convolutional style learning over it, while SPT keeps the hierarchical superpoint structure and applies transformer self-attention across superpoints at multiple scales. That is a different inductive bias: attention over a hierarchy versus message passing over a flat graph. The second alternative, implied by the README's own parameter comparisons, is a per-point transformer such as Stratified Transformer or a point-based network such as PointNeXt. Those operate on points directly and the README positions SPT against them on parameter count and training time, citing 212k parameters and 3h S3DIS training. Choosing between them is a question of whether you can afford a superpoint preprocessing stage and whether your scenes are large enough for the hierarchy to matter. For panoptic work specifically, SuperCluster's graph-clustering formulation is the distinguishing piece, and there is no equivalent in the per-point alternatives named in the README.

Licence, maintenance and what upgrading actually costs

The repository is MIT licensed, which is permissive and permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a statement about the licence text, not legal advice; if you are shipping this in a product, have your own counsel review it, particularly because the repository is derived from the lightning-hydra-template and the licence badge links there. On maintenance: the last push recorded is 2026-04-21, and the repository is not archived, so it is active. But active is not the same as stable. With no releases, an upgrade means moving to a new commit and reconciling it against PyTorch 2.2+, Lightning 2.2+ and Hydra 1.3. Because the training loop is Lightning's and the configuration is Hydra's, a breaking change in either dependency lands on you through this repository's configs rather than through a version pin you can hold. The practical upgrade cost is therefore dominated by dependency drift in the harness, not by changes to the model code.

Editorial conclusion

Adopt it if you are reproducing or extending SPT, SuperCluster or EZ-SP, or if you need a fast hierarchical superpoint partitioner to feed another model. Do not adopt it if you need a supported library with semantic versioning, release artifacts or a stable API surface: the repository has no retrieved releases and the README is the only integration documentation. Before committing, verify the Python 3.8+, PyTorch 2.2+ and Lightning 2.2+ pins against your environment, confirm which of the three paper configs you actually need, and check the dataset preparation steps for your dataset rather than assuming the S3DIS path generalises.

Official sources

1. drprojects/superpoint_transformer on GitHub
2. Issues
3. License: MIT
4. README