Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update setup and docs #46

Merged
merged 1 commit into from
Dec 19, 2021
Merged

Update setup and docs #46

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 39 additions & 28 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,21 @@
A lightweight tool for labeling 3D bounding boxes in point clouds.

![Overview of the Labeling Tool](docs/io_overview.png)

:new: *labelCloud is now [part of the PyPI](https://pypi.org/project/labelCloud/) and can be installed via pip!*

:new: *We are currently evaluating labelCloud and invite you to fill this questionaire https://forms.gle/moEyjGSa1Eiiq7VT8 (~5 min)!*

## Setup
:information_source: *Currently labelCloud supports Python 3.6 to 3.8; Python 3.9 will be supported as soon as Open3D supports it!*
:information_source: *Currently labelCloud supports Python 3.6 to 3.9.*

### via pip (PyPI)
```bash
pip install labelCloud
labelCloud # by default looks for a `pointcloud` folder in the same directory
```

### via git (manually)

```bash
git clone https://github.com/ch-sa/labelCloud.git # 1. Clone repository
Expand Down Expand Up @@ -56,42 +67,42 @@ The tool is designed to be easily adaptable to multiple use cases. To change the

**Supported Import Formats**

| Type | File Formats |
| --- | --- |
| Colored | `*.pcd`, `*.ply`, `*.pts`, `*.xyzrgb` |
| Colorless | `*.xyz`, `*.xyzn`, `*.bin` (KITTI) |
| 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 [documentation.md](docs/documentation.md) for order) |
| `kitti` | Centroid; Dimensions; z-Rotation (See [specification](https://github.com/bostondiditeam/kitti/blob/master/resources/devkit_object/readme.txt)) |
| `kitti_untransformed` | See above, but without transformations. |
| 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 [documentation.md](docs/documentation.md) for order) |
| `kitti` | Centroid; Dimensions; z-Rotation (See [specification](https://github.com/bostondiditeam/kitti/blob/master/resources/devkit_object/readme.txt)) |
| `kitti_untransformed` | See above, but without transformations. |

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 Point Cloud |
| Right Mouse Button | Translates the Point Cloud |
| Mouse Wheel | Zooms into the Point Cloud |
| *Correction* | |
| `W`, `A`, `S`, `D` <br> `Ctrl` + Right Mouse Button | Translates the Bounding Box back, left, front, right |
| `Q`, `E` | Lifts the Bounding Box up, down |
| `X`, `Y` | Rotates the Boundign Box around z-Axis |
| Scrolling with the Cursor above a Bounding Box Side ("Side Pulling") | Changes the Dimension of the Bounding Box |
|`C` & `V`, `B` & `N` | Rotates the Bounding Box around y-Axis, x-Axis |
| *General* | |
| `Del` | Deletes Current Bounding Box |
| `R` | Resets Perspective |
| `Esc` | Cancels Selected Points |
| Shortcut | Description |
| :------------------------------------------------------------------: | ---------------------------------------------------- |
| *Navigation* | |
| Left Mouse Button | Rotates the Point Cloud |
| Right Mouse Button | Translates the Point Cloud |
| Mouse Wheel | Zooms into the Point Cloud |
| *Correction* | |
| `W`, `A`, `S`, `D` <br> `Ctrl` + Right Mouse Button | Translates the Bounding Box back, left, front, right |
| `Q`, `E` | Lifts the Bounding Box up, down |
| `X`, `Y` | Rotates the Boundign Box around z-Axis |
| Scrolling with the Cursor above a Bounding Box Side ("Side Pulling") | Changes the Dimension of the Bounding Box |
| `C` & `V`, `B` & `N` | Rotates the Bounding Box around y-Axis, x-Axis |
| *General* | |
| `Del` | Deletes Current Bounding Box |
| `R` | Resets Perspective |
| `Esc` | Cancels Selected Points |


See [documentation.md](docs/documentation.md) for software conventions.
Expand Down
86 changes: 44 additions & 42 deletions docs/documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,16 +14,16 @@ The initial bounding box is oriented with the x-axis representing the length of
The bounding box vertices are ordered clockwise from bottom to top starting at the origin.
The sequence is adopted from the [bbox library](https://varunagrawal.github.io/bbox/bbox.html#module-bbox.bbox3d).

| Point | Position (x, y, z)|
| :---: | --- |
| 0 | left back bottom |
| 1 | left front bottom |
| 2 | right front bottom |
| 3 | right back bottom |
| 4 | left back top |
| 5 | left front top |
| 6 | right front top |
| 7 | right back top |
| Point | Position (x, y, z) |
| :---: | ------------------ |
| 0 | left back bottom |
| 1 | left front bottom |
| 2 | right front bottom |
| 3 | right back bottom |
| 4 | left back top |
| 5 | left front top |
| 6 | right front top |
| 7 | right back top |

If the `vertices` label format is selected, the points will get exported in a list in this sequence.
When labelCloud shows the orientation, the arrow points at the right side of the bounding box (2, 3, 6, 7) and upwards (6, 7).
Expand All @@ -33,35 +33,37 @@ When labelCloud shows the orientation, the arrow points at the right side of the
The settings of labelCloud can be changed using the config file (`config.ini`) and for most options exists an entry in the graphical settings (accesible via the menu).
The following parameters can be changed:

| Parameter | Description | Default/ Example |
| :---: | --- | :---: |
| **[FILE]** |
| `pointcloud_folder` | Folder from which the point cloud files are loaded. | *pointclouds/* |
| `label_folder`| Folder where the label files will be saved. | *labels/* |
| **[POINTCLOUD]** |
| `point_size` | Drawing size for points in point cloud (rasterized diameter). | *4* |
| `colorless_color` | Point color for colorless point clouds (r,g,b). | *0.9, 0.9, 0.9* |
| `colorless_colorize` | Colerize colorless point clouds by height value. | *True* |
| `std_translation` | Standard step for point cloud translation (with mouse move). | *0.03* |
| `std_zoom` | Standard step for zooming (with mouse scroll). | *0.0025* |
| **[LABEL]** |
| `label_format` | Format for exporting labels, choose from `vertices`, `centroid_rel`, `centroid_abs` or `kitti`. | *centroid_abs* |
| `object_classes` | List of object classes for autocompletion in the class text field. | *class1, class2, ...* |
| `std_object_class` | Default object class for new bounding boxes. | *default_class* |
| `export_precision` | Number of decimal places for exporting the bounding box parameters. | *8* |
| `std_boundingbox_length` | Default length of the bounding box (for picking mode). | *0.75* |
| `std_boundingbox_width` | Default width of the bounding box (for picking mode). | *0.55* |
| `std_boundingbox_height`| Default height of the bounding box (for picking mode). | *0.15* |
| `std_translation`| Standard step for translating the bounding box (with key or button press). | *0.03* |
| `std_rotation` | Standard step for rotating the bounding box (with key press). | *0.5* |
| `std_scaling` | Standard step for scaling the bounding box (with button press). | *0.03* |
| `min_boundingbox_dimension` | Minimum value for the length, width and height of a bounding box. | *0.01* |
| **[USER_INTERFACE]** |
| `z_rotation_only` | Only allow z-rotation of bounding box; deactivate to also label x- & y-rotation. | *True* |
| `show_floor` | Visualizes the floor (x-y-plane) as a grid. | *True* |
| `show_orientation` | Visualizes the object's orientation as an arrow. | *True* |
| `background_color` | Background color of the point cloud viewer (rgb). | *100, 100, 100* |
| `viewing_precision` | Number of decimal places shown on the right side for the parameters of the active bounding box. | *3* |
| `near_plane` | Min. distance of objects to be displayed by OpenGL | *0.1* |
| `far_plane` | Max. distance of objects to be displayed by OpenGL | *300* |
| `keep_perspective` | Save last perspective when leaving a point cloud | *False* |
| Parameter | Description | Default/ Example |
| :-------------------------: | ----------------------------------------------------------------------------------------------- | :-------------------: |
| **[FILE]** |
| `pointcloud_folder` | Folder from which the point cloud files are loaded. | *pointclouds/* |
| `label_folder` | Folder where the label files will be saved. | *labels/* |
| `image_folder` | Folder from which related images can be loaded (OPTIONAL). | *pointclouds/* |
| **[POINTCLOUD]** |
| `point_size` | Drawing size for points in point cloud (rasterized diameter). | *4* |
| `colorless_color` | Point color for colorless point clouds (r,g,b). | *0.9, 0.9, 0.9* |
| `colorless_colorize` | Colerize colorless point clouds by height value. | *True* |
| `std_translation` | Standard step for point cloud translation (with mouse move). | *0.03* |
| `std_zoom` | Standard step for zooming (with mouse scroll). | *0.0025* |
| **[LABEL]** |
| `label_format` | Format for exporting labels, choose from `vertices`, `centroid_rel`, `centroid_abs` or `kitti`. | *centroid_abs* |
| `object_classes` | List of object classes for autocompletion in the class text field. | *class1, class2, ...* |
| `std_object_class` | Default object class for new bounding boxes. | *default_class* |
| `export_precision` | Number of decimal places for exporting the bounding box parameters. | *8* |
| `std_boundingbox_length` | Default length of the bounding box (for picking mode). | *0.75* |
| `std_boundingbox_width` | Default width of the bounding box (for picking mode). | *0.55* |
| `std_boundingbox_height` | Default height of the bounding box (for picking mode). | *0.15* |
| `std_translation` | Standard step for translating the bounding box (with key or button press). | *0.03* |
| `std_rotation` | Standard step for rotating the bounding box (with key press). | *0.5* |
| `std_scaling` | Standard step for scaling the bounding box (with button press). | *0.03* |
| `min_boundingbox_dimension` | Minimum value for the length, width and height of a bounding box. | *0.01* |
| **[USER_INTERFACE]** |
| `z_rotation_only` | Only allow z-rotation of bounding box; deactivate to also label x- & y-rotation. | *True* |
| `show_floor` | Visualizes the floor (x-y-plane) as a grid. | *True* |
| `show_orientation` | Visualizes the object's orientation as an arrow. | *True* |
| `background_color` | Background color of the point cloud viewer (rgb). | *100, 100, 100* |
| `viewing_precision` | Number of decimal places shown on the right side for the parameters of the active bounding box. | *3* |
| `near_plane` | Min. distance of objects to be displayed by OpenGL | *0.1* |
| `far_plane` | Max. distance of objects to be displayed by OpenGL | *300* |
| `keep_perspective` | Save last perspective when leaving a point cloud | *False* |
| `show_2d_image` | Show button to visualize related images in a separate window | *False* |
2 changes: 1 addition & 1 deletion labelCloud/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1 @@
__version__ = "0.6.1"
__version__ = "0.6.4"
4 changes: 3 additions & 1 deletion labelCloud/ressources/default_config.ini
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,4 +55,6 @@ viewing_precision = 2
near_plane=0.1
far_plane=300
; keep last perspective between point clouds
keep_perspective = False
keep_perspective = False
; show button to visualize related images in a separate window
show_2d_image = False
6 changes: 3 additions & 3 deletions requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
numpy~=1.21.2
open3d~=0.13.0
numpy~=1.21.4
open3d~=0.14.1
PyOpenGL~=3.1.5
PyQt5~=5.15.4
PyQt5~=5.14.1
39 changes: 29 additions & 10 deletions setup.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,34 +1,46 @@
from pathlib import Path

from setuptools import setup

this_directory = Path(__file__).parent
README = (this_directory / "README.md").read_text()


setup(
name="labelCloud",
version="0.6.1",
version="0.6.4",
description="A lightweight tool for labeling 3D bounding boxes in point clouds.",
long_description=open("README.md").read(),
long_description=README,
long_description_content_type="text/markdown",
author="Christoph Sager",
author_email="[email protected]",
url="https://github.com/ch-sa/labelCloud",
license="GNU Geneal Public License v3.0",
packages=[
"labelCloud",
"labelCloud.ressources",
"labelCloud.ressources.icons",
"labelCloud.ressources.interfaces",
"labelCloud.tests",
"labelCloud.control",
"labelCloud.definitions",
"labelCloud.label_formats",
"labelCloud.labeling_strategies",
"labelCloud.model",
"labelCloud.ressources.icons",
"labelCloud.ressources.interfaces",
"labelCloud.ressources",
"labelCloud.tests",
"labelCloud.utils",
"labelCloud.view",
],
package_data={"labelCloud.ressources": ["*"], "labelCloud.ressources.icons": ["*"]},
package_data={
"labelCloud.ressources": ["*"],
"labelCloud.ressources.icons": ["*"],
"labelCloud.ressources.interfaces": ["*"],
},
entry_points={"console_scripts": ["labelCloud=labelCloud.__main__:main"]},
install_requires=[
"numpy~=1.21.2",
"open3d~=0.13.0",
"numpy~=1.21.4",
"open3d~=0.14.1",
"PyOpenGL~=3.1.5",
"PyQt5~=5.15.4",
"PyQt5~=5.14.1",
],
extras_require={
"tests": [
Expand All @@ -39,8 +51,15 @@
zip_safe=False,
keywords="labelCloud",
classifiers=[
"Development Status :: 4 - Beta",
"Natural Language :: English",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.6",
"Programming Language :: Python :: 3.7",
"Programming Language :: Python :: 3.8",
"Programming Language :: Python :: 3.9",
"License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
"Topic :: Scientific/Engineering :: Artificial Intelligence",
"Topic :: Multimedia :: Graphics :: Viewers",
],
)