<p align="center">
<img src="https://img.shields.io/badge/contributions-welcome!-green" alt="Contributions welcome!"/>
<img src="https://img.shields.io/github/last-commit/ch-sa/labelCloud?color=blue">
<img src="https://img.shields.io/pypi/pyversions/labelCloud" />
<img src="https://github.com/ch-sa/labelCloud/actions/workflows/unit-tests.yml/badge.svg" />
<img src="https://img.shields.io/badge/code%20style-black-000000.svg" />
</p>
# labelCloud
:information_source: [Interactive Documentation](https://ch-sa.github.io/labelCloud/)
A lightweight tool for labeling 3D bounding boxes in point clouds.
## Setup
:information_source: *Currently labelCloud supports Python 3.7 to 3.9.*
### via pip (PyPI)
```bash
pip install labelCloud
labelCloud --example # start labelCloud with example point cloud
```
### via git (manually)
```bash
git clone https://github.com/ch-sa/labelCloud.git # 1. Clone repository
pip install -r requirements.txt # 2. Install requirements
# 3. Copy point clouds into `pointclouds` folder.
python3 labelCloud.py # 4. Start labelCloud
```
Configure the software to your needs by editing the `config.ini` file or settings (see [Configuration](https://ch-sa.github.io/labelCloud/configuration/)).
## Labeling
labelCloud supports two different ways of labeling (*picking* & *spanning*) as well as multiple mouse and keyboard options for subsequent correction.
(See also https://www.youtube.com/watch?v=8GF9n1WeR8A for a short introduction and preview of the tool.)
### Picking Mode
* Pick the location of the bounding box (front-top edge).
* Adjust the z-rotation by scrolling with your mouse wheel.
### Spanning Mode
* Subsequently span the length, width and height of the bounding box by selecting four vertices.
* The layers for the last two vertices (width & height) will be locked to allow easy selection.
### Correction
* Use the buttons on the left-hand side or shortcuts to correct the *translation*, *dimension* and
*rotation* of the bounding box.
* Resize the bounding box by holding your cursor above one side and scrolling with the mouse wheel.
By default the x- and y-rotation of bounding boxes will be prohibited.
For labeling **9 DoF-Bounding Boxes** deactivate `z-Rotation Only Mode` in the menu, settings or
`config.ini` file.
The bouding boxes can then be freely rotated around all three axes.
### Semantic Segmentation (bounding box-based)
labelCloud also supports the creation of segmentation labels based on bounding boxes.
To activate the semantic segmentation mode, toggle the segmentation button in the startup dialog.
Then label as usual and push the *Assign* button whenever all points inside the current bounding box
should be labeled with the current class.
The resulting labels will be stored as `*.bin` files inside `labels/segmentation/`.
Each `*.bin` file contains an array with the shape of (number of points, ) with dtype `np.int8`.
Each entry represents the index of the label of the corresponding point in the original point cloud.
## Import & Export Options
labelCloud is built for a versatile use and aims at supporting all common point cloud file
and label formats for storing 3D bounding boxes.
The tool is designed to be easily adaptable to multiple use cases. The welcome dialog will ask for
the most common parameters (mode, classes, export format).
For more configuration, edit the corresponding fields in `labels/_classes.json` for label
configuration or `config.ini` for general settings (see
[Configuration](https://ch-sa.github.io/labelCloud/configuration/)) for a description of all
parameters).
**Supported Import Formats**
| Type | File Formats |
| --------- | ------------------------------------- |
| Colored | `*.pcd`, `*.ply`, `*.pts`, `*.xyzrgb` |
| Colorless | `*.xyz`, `*.xyzn`, `*.bin` (KITTI) |
**Supported Export Formats**
| Label Format | Description |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `centroid_rel` | Centroid `[x, y, z]`; Dimensions `[length, width, height]`; <br> Relative Rotations as Euler angles in radians (-pi..+pi) `[yaw, pitch, roll]` |
| `centroid_abs` | Centroid `[x, y, z]`; Dimensions `[length, width, height]`; <br> Absolute Rotations as Euler angles in degrees (0..360°) `[yaw, pitch, roll]` |
| `vertices` | 8 Vertices of the bounding box each with `[x, y, z]` (see [Conventions](conventions.md) for order) |
| `kitti` | Centroid; Dimensions; z-Rotation (See [specification](https://github.com/bostondiditeam/kitti/blob/master/resources/devkit_object/readme.txt)); Requires calibration files |
| `kitti_untransformed` | See above, but without transformations (if you just want to use the same label structure). |
You can easily create your own exporter by subclassing the abstract [BaseLabelFormat](https://github.com/ch-sa/labelCloud/blob/master/labelCloud/label_formats/base.py#L10).
All rotations are counterclockwise (i.e. a z-rotation of 90°/π is from the positive x- to the negative y-axis!).
## Shortcuts
| Shortcut | Description |
| :------------------------------------------------------------------: | ---------------------------------------------------- |
| *Navigation* | |
| Left Mouse Button | Rotates the camera around Point Cloud centroid |
| Right Mouse Button | Translates the camera |
| Mouse Wheel | Zooms into the Point Cloud |
| *Correction* | |
| `W`, `A`, `S`, `D` | Translates the Bounding Box back, left, front, right |
| `Ctrl` + Right Mouse Button | Translates the Bounding Box in all dimensions |
| `Q`, `E` | Lifts the Bounding Box up, down |
| `Z`, `X` | Rotates the Bounding Box around z-Axis |
| `C`, `V` | Rotates the Bounding Box around y-Axis |
| `B`, `N` | Rotates the Bounding Box around x-Axis |
| `I`/ `O` | Increase/Decrease the Bounding Box length |
| `K`/ `L` | Increase/Decrease the Bounding Box width |
| `,`/ `.` | Increase/Decrease the Bounding Box height |
| Scrolling with the Cursor above a Bounding Box Side ("Side Pulling") | Changes the Dimension of the Bounding Box |
| `R`/`Left`, `F`/`Right` | Previous/Next sample |
| `T`/`Up`, `G`/`Down` | Previous/Next bbox |
| `Y`, `H` | Change current bbox class to previous/next in list |
| `1`-`9` | Select any of first 9 bboxes with number keys |
| *General* | |
| `Del` | Deletes Current Bounding Box |
| `P`/`Home` | Resets Perspective |
| `Esc` | Cancels Selected Points |
See [Conventions](https://ch-sa.github.io/labelCloud/conventions/) for the principles on which the
software is built.
## Usage & Attribution
When using the tool feel free to drop me a mail with feedback or a description of your use case (christoph.sager[at]gmail.com).
If you are using the tool for a scientific project please consider citing our [publication](http://cad-journal.net/files/vol_19/CAD_19(6)_2022_1191-1206.pdf):
# CAD Journal
@article{Sager_2022,
doi = {10.14733/cadaps.2022.1191-1206},
url = {http://cad-journal.net/files/vol_19/CAD_19(6)_2022_1191-1206.pdf},
year = 2022,
month = {mar},
publisher = {{CAD} Solutions, {LLC}},
volume = {19},
number = {6},
pages = {1191--1206},
author = {Christoph Sager and Patrick Zschech and Niklas Kuhl},
title = {{labelCloud}: A Lightweight Labeling Tool for Domain-Agnostic 3D Object Detection in Point Clouds},
journal = {Computer-Aided Design and Applications}
}
# CAD Conference
@misc{sager2021labelcloud,
title={labelCloud: A Lightweight Domain-Independent Labeling Tool for 3D Object Detection in Point Clouds},
author={Christoph Sager and Patrick Zschech and Niklas Kühl},
year={2021},
eprint={2103.04970},
archivePrefix={arXiv},
primaryClass={cs.CV}
}
## Acknowledgment
I would like to thank the [Robotron RCV-Team](https://www.robotron.de/rcv) for the support in the
preparation and user evaluation of the software.
The software was developed as part of my diploma thesis titled "labelCloud: Development of a
Labeling Tool for 3D Object Detection in Point Clouds" at the
[Chair for Business Informatics, especially Intelligent Systems](https://tu-dresden.de/bu/wirtschaft/winf/isd)
of the TU Dresden. The ongoing research can be followed in our
[project on ResearchGate](https://www.researchgate.net/project/Development-of-a-Point-Cloud-Labeling-Tool-to-Generate-Training-Data-for-3D-Object-Detection-and-6D-Pose-Estimation).
Raw data
{
"_id": null,
"home_page": "https://github.com/ch-sa/labelCloud",
"name": "labelCloud",
"maintainer": "Christoph Sager",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "christoph.sager@gmail.com",
"keywords": "labelCloud, machine learning, computer vision, annotation tool, labeling, point clouds, bounding boxes, 3d object detection, 6d pose estimation",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/76/51/f7f80400a2b731463c463a0b3757a366de8c7e4bb9f37eeec898379cd2fc/labelcloud-1.1.1.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://img.shields.io/badge/contributions-welcome!-green\" alt=\"Contributions welcome!\"/>\n <img src=\"https://img.shields.io/github/last-commit/ch-sa/labelCloud?color=blue\">\n <img src=\"https://img.shields.io/pypi/pyversions/labelCloud\" />\n <img src=\"https://github.com/ch-sa/labelCloud/actions/workflows/unit-tests.yml/badge.svg\" />\n <img src=\"https://img.shields.io/badge/code%20style-black-000000.svg\" />\n</p>\n\n\n# labelCloud\n:information_source: [Interactive Documentation](https://ch-sa.github.io/labelCloud/)\n\nA lightweight tool for labeling 3D bounding boxes in point clouds.\n\n\n\n## Setup\n:information_source: *Currently labelCloud supports Python 3.7 to 3.9.*\n\n### via pip (PyPI)\n```bash\npip install labelCloud\nlabelCloud --example # start labelCloud with example point cloud\n```\n\n### via git (manually)\n\n```bash\ngit clone https://github.com/ch-sa/labelCloud.git # 1. Clone repository\npip install -r requirements.txt # 2. Install requirements\n# 3. Copy point clouds into `pointclouds` folder.\npython3 labelCloud.py # 4. Start labelCloud\n```\n\nConfigure the software to your needs by editing the `config.ini` file or settings (see [Configuration](https://ch-sa.github.io/labelCloud/configuration/)).\n\n## Labeling\nlabelCloud supports two different ways of labeling (*picking* & *spanning*) as well as multiple mouse and keyboard options for subsequent correction.\n\n\n(See also https://www.youtube.com/watch?v=8GF9n1WeR8A for a short introduction and preview of the tool.)\n\n### Picking Mode\n\n* Pick the location of the bounding box (front-top edge).\n* Adjust the z-rotation by scrolling with your mouse wheel.\n\n### Spanning Mode\n\n* Subsequently span the length, width and height of the bounding box by selecting four vertices.\n* The layers for the last two vertices (width & height) will be locked to allow easy selection.\n\n### Correction\n\n* Use the buttons on the left-hand side or shortcuts to correct the *translation*, *dimension* and\n *rotation* of the bounding box.\n* Resize the bounding box by holding your cursor above one side and scrolling with the mouse wheel.\n\nBy default the x- and y-rotation of bounding boxes will be prohibited.\nFor labeling **9 DoF-Bounding Boxes** deactivate `z-Rotation Only Mode` in the menu, settings or\n`config.ini` file.\nThe bouding boxes can then be freely rotated around all three axes.\n\n### Semantic Segmentation (bounding box-based)\n\nlabelCloud also supports the creation of segmentation labels based on bounding boxes.\nTo activate the semantic segmentation mode, toggle the segmentation button in the startup dialog.\nThen label as usual and push the *Assign* button whenever all points inside the current bounding box\nshould be labeled with the current class.\n\nThe resulting labels will be stored as `*.bin` files inside `labels/segmentation/`.\nEach `*.bin` file contains an array with the shape of (number of points, ) with dtype `np.int8`.\nEach entry represents the index of the label of the corresponding point in the original point cloud.\n\n\n## Import & Export Options\nlabelCloud is built for a versatile use and aims at supporting all common point cloud file\nand label formats for storing 3D bounding boxes.\nThe tool is designed to be easily adaptable to multiple use cases. The welcome dialog will ask for\nthe most common parameters (mode, classes, export format).\n\nFor more configuration, edit the corresponding fields in `labels/_classes.json` for label\nconfiguration or `config.ini` for general settings (see\n[Configuration](https://ch-sa.github.io/labelCloud/configuration/)) for a description of all\nparameters).\n\n**Supported Import Formats**\n\n| Type | File Formats |\n| --------- | ------------------------------------- |\n| Colored | `*.pcd`, `*.ply`, `*.pts`, `*.xyzrgb` |\n| Colorless | `*.xyz`, `*.xyzn`, `*.bin` (KITTI) |\n\n**Supported Export Formats**\n\n| Label Format | Description |\n| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `centroid_rel` | Centroid `[x, y, z]`; Dimensions `[length, width, height]`; <br> Relative Rotations as Euler angles in radians (-pi..+pi) `[yaw, pitch, roll]` |\n| `centroid_abs` | Centroid `[x, y, z]`; Dimensions `[length, width, height]`; <br> Absolute Rotations as Euler angles in degrees (0..360\u00b0) `[yaw, pitch, roll]` |\n| `vertices` | 8 Vertices of the bounding box each with `[x, y, z]` (see [Conventions](conventions.md) for order) |\n| `kitti` | Centroid; Dimensions; z-Rotation (See [specification](https://github.com/bostondiditeam/kitti/blob/master/resources/devkit_object/readme.txt)); Requires calibration files |\n| `kitti_untransformed` | See above, but without transformations (if you just want to use the same label structure). |\n\nYou can easily create your own exporter by subclassing the abstract [BaseLabelFormat](https://github.com/ch-sa/labelCloud/blob/master/labelCloud/label_formats/base.py#L10).\nAll rotations are counterclockwise (i.e. a z-rotation of 90\u00b0/\u03c0 is from the positive x- to the negative y-axis!).\n\n## Shortcuts\n\n| Shortcut | Description |\n| :------------------------------------------------------------------: | ---------------------------------------------------- |\n| *Navigation* | |\n| Left Mouse Button | Rotates the camera around Point Cloud centroid |\n| Right Mouse Button | Translates the camera |\n| Mouse Wheel | Zooms into the Point Cloud |\n| *Correction* | |\n| `W`, `A`, `S`, `D` | Translates the Bounding Box back, left, front, right |\n| `Ctrl` + Right Mouse Button | Translates the Bounding Box in all dimensions |\n| `Q`, `E` | Lifts the Bounding Box up, down |\n| `Z`, `X` | Rotates the Bounding Box around z-Axis |\n| `C`, `V` | Rotates the Bounding Box around y-Axis |\n| `B`, `N` | Rotates the Bounding Box around x-Axis |\n| `I`/ `O` | Increase/Decrease the Bounding Box length |\n| `K`/ `L` | Increase/Decrease the Bounding Box width |\n| `,`/ `.` | Increase/Decrease the Bounding Box height |\n| Scrolling with the Cursor above a Bounding Box Side (\"Side Pulling\") | Changes the Dimension of the Bounding Box |\n| `R`/`Left`, `F`/`Right` | Previous/Next sample |\n| `T`/`Up`, `G`/`Down` | Previous/Next bbox |\n| `Y`, `H` | Change current bbox class to previous/next in list |\n| `1`-`9` | Select any of first 9 bboxes with number keys |\n| *General* | |\n| `Del` | Deletes Current Bounding Box |\n| `P`/`Home` | Resets Perspective |\n| `Esc` | Cancels Selected Points |\n\n\nSee [Conventions](https://ch-sa.github.io/labelCloud/conventions/) for the principles on which the\nsoftware is built.\n\n## Usage & Attribution\nWhen using the tool feel free to drop me a mail with feedback or a description of your use case (christoph.sager[at]gmail.com).\nIf you are using the tool for a scientific project please consider citing our [publication](http://cad-journal.net/files/vol_19/CAD_19(6)_2022_1191-1206.pdf):\n\n # CAD Journal\n @article{Sager_2022,\n doi = {10.14733/cadaps.2022.1191-1206},\n url = {http://cad-journal.net/files/vol_19/CAD_19(6)_2022_1191-1206.pdf},\n year = 2022,\n month = {mar},\n publisher = {{CAD} Solutions, {LLC}},\n volume = {19},\n number = {6},\n pages = {1191--1206},\n author = {Christoph Sager and Patrick Zschech and Niklas Kuhl},\n title = {{labelCloud}: A Lightweight Labeling Tool for Domain-Agnostic 3D Object Detection in Point Clouds},\n journal = {Computer-Aided Design and Applications}\n }\n\n # CAD Conference\n @misc{sager2021labelcloud,\n title={labelCloud: A Lightweight Domain-Independent Labeling Tool for 3D Object Detection in Point Clouds},\n author={Christoph Sager and Patrick Zschech and Niklas K\u00fchl},\n year={2021},\n eprint={2103.04970},\n archivePrefix={arXiv},\n primaryClass={cs.CV}\n }\n\n## Acknowledgment\nI would like to thank the [Robotron RCV-Team](https://www.robotron.de/rcv) for the support in the\npreparation and user evaluation of the software.\nThe software was developed as part of my diploma thesis titled \"labelCloud: Development of a\nLabeling Tool for 3D Object Detection in Point Clouds\" at the\n[Chair for Business Informatics, especially Intelligent Systems](https://tu-dresden.de/bu/wirtschaft/winf/isd)\nof the TU Dresden. The ongoing research can be followed in our\n[project on ResearchGate](https://www.researchgate.net/project/Development-of-a-Point-Cloud-Labeling-Tool-to-Generate-Training-Data-for-3D-Object-Detection-and-6D-Pose-Estimation).\n",
"bugtrack_url": null,
"license": "GNU General Public License v3.0",
"summary": "A lightweight tool for labeling 3D bounding boxes in point clouds.",
"version": "1.1.1",
"project_urls": {
"Homepage": "https://github.com/ch-sa/labelCloud"
},
"split_keywords": [
"labelcloud",
" machine learning",
" computer vision",
" annotation tool",
" labeling",
" point clouds",
" bounding boxes",
" 3d object detection",
" 6d pose estimation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bada80c0b5ab9ebceb1feda57ec8cb551b29fd68305b759ca45289734a9b9a57",
"md5": "dba05075766a15e062d0e4cffbdb736f",
"sha256": "f1391e08e2e3fc062f5e81cb36b53d5b4194160f08d04ba9e85976e08f7a0e7c"
},
"downloads": -1,
"filename": "labelCloud-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dba05075766a15e062d0e4cffbdb736f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 2347692,
"upload_time": "2024-08-18T17:05:28",
"upload_time_iso_8601": "2024-08-18T17:05:28.008166Z",
"url": "https://files.pythonhosted.org/packages/ba/da/80c0b5ab9ebceb1feda57ec8cb551b29fd68305b759ca45289734a9b9a57/labelCloud-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7651f7f80400a2b731463c463a0b3757a366de8c7e4bb9f37eeec898379cd2fc",
"md5": "424a3f19e8186c3b2b7d7f1fb858ebf4",
"sha256": "61066e1f2e0fce6f626765379f0e21c2512962a6ca8e0e019e77acbb9f00862a"
},
"downloads": -1,
"filename": "labelcloud-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "424a3f19e8186c3b2b7d7f1fb858ebf4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 2330530,
"upload_time": "2024-08-18T17:05:29",
"upload_time_iso_8601": "2024-08-18T17:05:29.882725Z",
"url": "https://files.pythonhosted.org/packages/76/51/f7f80400a2b731463c463a0b3757a366de8c7e4bb9f37eeec898379cd2fc/labelcloud-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-18 17:05:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ch-sa",
"github_project": "labelCloud",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "labelcloud"
}
JSON
