# SUSTechPOINTS: a 3D point cloud annotation tool built for driving datasets

> SUSTechPOINTS is a research platform for annotating 3D bounding boxes in LiDAR point clouds for autonomous driving work, with nine degree-of-freedom box editing, automatic yaw prediction and batch mode. This looks at what it does, how the repository is laid out, and what the release history says about adopting it.

**naurril/SUSTechPOINTS** — 3D Point Cloud Annotation Platform for Autonomous Driving

- Repository: https://github.com/naurril/SUSTechPOINTS
- Stars: 1,171 · Forks: 259
- Language: JavaScript
- License: GPL-3.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/naurril-sustechpoints

## Labelling driving data in three dimensions

SUSTechPOINTS is a point cloud 3D bounding box annotation tool for autonomous driving, and it is the software behind a paper rather than a product. The readme asks that you cite it if it is useful in your research, and gives the citation for SUSTech POINTS: A Portable 3D Point Cloud Interactive Annotation Platform System, published at the 2020 IEEE Intelligent Vehicles Symposium.

The problem it addresses is the one every driving dataset team faces. A 3D box in a point cloud is not a rectangle drawn on an image, it is a pose in space, with position, extent and orientation, and it has to be aligned to the returns of a LiDAR sensor. Drawing that by hand, in a browser, on a hundred thousand frames, is the bottleneck. The platform exists to make that interactive, and to make it fast enough that a human can do a day's work.

The feature list in the readme is the scope in one screen. There is 9 DoF box editing, editing of object type, ID and attributes, interactive and automatic box fitting, batch-mode editing, perspective and projective view editing, multiple camera images with auto camera switching, support for binary and pcd files for point cloud data and jpg and png image files, colouring of objects, boxes and points, a focus mode to hide the background so you can check details, stream play and stop, and object ID generation.

The licence is GPL-3.0, the language is JavaScript for the interface with a Python core, and the default branch is `dev-auto-annotate`.

## Automatic yaw prediction and semi-automatic batch mode

Two of those features are the ones that change the throughput of an annotation team, and the readme gives each its own demonstration.

The first is automatic yaw angle prediction on the z-axis. Orientation is the hardest parameter for a human to set, because a box has to be rotated to match the object, not just aligned to the sensor rays, and getting it wrong by ten degrees is obvious in the 3D view and invisible in the image view. Predicting the yaw from the point cloud and letting the annotator accept or adjust it removes the single slowest interaction in the workflow.

The second is batch-mode box editing, described as semi-auto annotation. The idea is that a frame's objects are fitted automatically and then corrected in bulk, rather than one box at a time. With automatic fitting available, the annotator's job becomes reviewing and adjusting proposals, which is a different and much faster activity than drawing.

Interactive and auto box fitting sit underneath both of these, and the object ID generation feature handles the bookkeeping that follows: in a driving dataset every object needs a stable identity across frames, and generating those IDs automatically is the difference between a usable track and a pile of boxes.

The perspective and projective view editing modes fill the remaining gap. A box that is correct in the point cloud can still be wrong in the image, and the reverse is also true, so being able to edit in both projections and see the correspondence is what makes the annotation trustworthy.

## Cameras, colouring and the focus mode

The supporting features are what turn a box drawing tool into something a labelling team can use all day.

Multiple camera images with auto camera switching means the annotator sees the frame from whichever camera makes the object legible, rather than cycling through views by hand. That matters because a vehicle thirty metres ahead may be unrecognisable in the front camera and obvious in the side one.

Colouring of objects, boxes and points is a second quality tool. A point cloud is a mass of returns, and a mis-fitted box is much easier to spot when the points inside it are drawn in a different colour from the points around it. The focus mode, described as hiding the background to check details easily, is the same idea taken further: it removes everything that is not the object under edit, so a boundary error of a few centimetres is visible rather than plausible.

Stream play and stop handles the file formats. The readme lists binary and pcd files for point cloud data and jpg and png for images, and the stream controls suggest the tool can walk a sequence rather than a single frame, which is the mode a labelling team works in.

Together with object ID generation, these features describe a workflow built around reviewing machine proposals rather than hand drawing everything, and that is the design idea behind the paper's claim of a portable interactive platform.

## Getting it running, and what is in the repository

The readme links to three deployment paths rather than repeating them: a Docker guide in `doc/docker.md`, an install from source guide in `doc/install_from_source.md`, and a uwsgi deployment document in `doc/deploy_server.md`. There is also an operations document, `doc/operations.md`, and a shortcuts sheet in Chinese at `doc/shortcuts_cn.md`.

The repository layout shows the shape of the application. `main.py` is the entry point, `scene_reader.py` handles reading the scene data, `server.conf` and `uwsgi.ini` are the server configuration, and `index.html`, `view.html` and `registration_demo.html` are the browser side, with `public/` holding the static assets. `requirement.txt` lists the Python dependencies, which tells you the core is Python with a JavaScript front end served over HTTP.

The algorithmic parts sit in `algos/`, and `calibpy/` is clearly the calibration handling, which is the part of any driving setup that has to be right before a single box can be drawn. `go-icp.prototxt` is the configuration for an iterative closest point registration, which is the algorithm used to align a point cloud into a reference frame, and `registration_demo.html` is its demonstration page.

There is also `data/`, `tools/`, `doc/`, and four Markdown files besides the readme: `README_cn.md` for the Chinese version, `README_guide.md`, and `notes.md` and `todo.md` for the working notes. The `Docker/` directory holds the container definition, which is the shortest path to a working instance.

## The paper is the documentation, and there is one release from 2020

Two facts about the maintenance of this project should shape any adoption decision, and they point in opposite directions.

The first is the citation. The readme asks you to cite the IEEE IV 2020 paper, and gives the full BibTeX entry with the DOI:

```
@INPROCEEDINGS{9304562,
  author={Li, E and Wang, Shuaijun and Li, Chengyang and Li, Dachuan and Wu, Xiangbin and Hao, Qi},
  booktitle={2020 IEEE Intelligent Vehicles Symposium (IV)},
  title={SUSTech POINTS: A Portable 3D Point Cloud Interactive Annotation Platform System},
  year={2020},
  pages={1108-1115},
  doi={10.1109/IV47402.2020.9304562}}
```

That paper is the authoritative description of the intended workflow, and it is a better guide than the repository documentation, which is thin by comparison.

The second is the release history. There is one tag, 0.1, dated 2020-04-02, and no releases since. The last push to the repository was on 2026-06-13, so work is still happening in the source, but the default branch is `dev-auto-annotate`, a feature branch rather than a stable line, and there is no tagged artefact to pin.

The practical consequence is that adopting this means adopting a checkout, not a release. You get whatever is on the branch on the day you clone it, and there is no version marker to record in a dataset paper or a pipeline configuration.

There is one more thing to note about the shape of the repository: the `tools/` and `algos/` directories and the presence of `notes.md` and `todo.md` suggest a research codebase that is still being worked on, which is consistent with the project being a platform for research rather than a maintained tool.

## Where SUSTechPOINTS is the wrong tool

Four limits are worth stating.

The first is maturity and support. A single 0.1 tag from April 2020, a feature branch as the default, and no release stream mean there is nobody shipping you a tested build. If your dataset is a deliverable for a partner or a published benchmark, a tool at that stage is a risk you have to absorb yourself, and the licence being GPL-3.0 means any change you distribute has to be published too.

The second is scope. This is a research platform for 3D boxes on driving data, with the box-centric feature set the readme lists. It is not a general point cloud editor, not a sensor simulator, and not a data management system. If your pipeline needs a scene graph, a database of tracks, or automatic labelling of a particular class of object, none of that is in the feature list.

The third is the data format. The readme mentions binary and pcd files and jpg and png images, and the repository has a `data/` directory. In practice this is the question to ask before starting, because a labelling tool is only as useful as the data model it writes.

The fourth is the front end. The interface is JavaScript served from a Python backend through uwsgi, and the deployment documents assume a machine you control with a reverse proxy. That is fine for a research group, and it does mean you are running a web application to do a desktop task, which is one more moving part than a native tool would be.

None of that makes the project wrong for its purpose. It makes it a research codebase to plan around, not a tool to deploy on a Friday.

## Conclusion

SUSTechPOINTS fits a research group building a driving dataset that needs 3D boxes labelled against LiDAR and camera data, and that wants an interactive tool with automatic fitting and semi-automatic batch annotation rather than a bare labelling script. It does not fit a production data pipeline that needs a maintained release, a documented file format and tested builds, because the repository has a single 0.1 tag from 2020 and works from a feature branch. Before you build on it, read the install documents in `doc/`, check that the `requirement.txt` dependencies resolve on your Python, and treat the IEEE IV 2020 paper as the authoritative description of the intended workflow, since the repository documentation is thinner than the paper.

## FAQ

### What is SUSTechPOINTS used for?

It is a 3D point cloud annotation platform for autonomous driving work, for drawing and editing 3D bounding boxes against LiDAR data and camera images. The project is the software behind the SUSTech POINTS paper published at the 2020 IEEE Intelligent Vehicles Symposium.

### How do I install SUSTechPOINTS?

The readme points to three documents in the doc/ directory: a Docker guide at doc/docker.md, an install from source guide at doc/install_from_source.md, and a uwsgi deployment guide at doc/deploy_server.md. The Python dependencies are listed in requirement.txt and the browser interface is served from main.py.

### What can the SUSTechPOINTS box editor do?

9 DoF box editing, interactive and automatic box fitting, batch-mode editing, automatic yaw angle prediction on the z-axis, editing of object type, ID and attributes, perspective and projective view editing, multiple camera images with auto camera switching, colouring of objects, boxes and points, a focus mode, and stream play and stop.

### Is SUSTechPOINTS actively released?

There is a single release tag, 0.1, dated 2020-04-02, and the default branch is dev-auto-annotate rather than a stable line. The last push to the repository was on 2026-06-13, so the source is still being worked on, but there is no tagged artefact to pin.

### What licence is SUSTechPOINTS released under?

GPL-3.0, with the licence file at the repository root. The readme also asks that you cite the associated IEEE Intelligent Vehicles Symposium 2020 paper, with a DOI of 10.1109/IV47402.2020.9304562.

## Sources

- [Issues](https://github.com/naurril/SUSTechPOINTS/issues)
- [License: GPL-3.0](https://github.com/naurril/SUSTechPOINTS/blob/dev-auto-annotate/LICENSE)
- [naurril/SUSTechPOINTS on GitHub](https://github.com/naurril/SUSTechPOINTS)
- [README](https://github.com/naurril/SUSTechPOINTS/blob/dev-auto-annotate/README.md)
- [Releases](https://github.com/naurril/SUSTechPOINTS/releases)

---

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