Update setup and docs (#46)

- make setup.py load the README.md - update the README and documentation - update the requirement versioning
ch-sa · Dec 19, 2021 · 3df814c · 3df814c
1 parent 81995f9
commit 3df814c
Show file tree

Hide file tree

Showing 6 changed files with 119 additions and 85 deletions.
diff --git a/README.md b/README.md
@@ -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
@@ -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.

diff --git a/docs/documentation.md b/docs/documentation.md
@@ -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).
@@ -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*        |
diff --git a/labelCloud/__init__.py b/labelCloud/__init__.py
@@ -1 +1 @@
-__version__ = "0.6.1"
+__version__ = "0.6.4"
diff --git a/labelCloud/ressources/default_config.ini b/labelCloud/ressources/default_config.ini
@@ -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
diff --git a/requirements.txt b/requirements.txt
@@ -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
diff --git a/setup.py b/setup.py
@@ -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": [
@@ -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",
     ],
 )