Merge pull request #26 from prime-slam/docs

Documentation & new README

.github/workflows/docs.yml

@@ -0,0 +1,38 @@
+name: Docs website
+
+# build the documentation whenever there are new commits on docs
+on:
+  push:
+    branches:
+      - docs
+      - master
+
+jobs:
+  # Build the documentation and upload the static HTML files as an artifact.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install pdoc
+
+      - run: pdoc ./vprdb -o ./docs
+
+      - name: Deploy
+        uses: s0/git-publish-subdir-action@develop
+        env:
+          REPO: self
+          BRANCH: gh-pages
+          FOLDER: ./docs
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TARGET_DIR: ./docs
+          MESSAGE: "Updating the website with documentation"

README.md

@@ -1,34 +1,34 @@
 # PlaceRecognitionDB
-PlaceRecognitionDB is a tool for creating optimally sized databases (containing the minimum number of frames covering the scene) for place recognition task from RGBD and LiDAR data.
+[![Lint&Tests](https://github.com/prime-slam/place-recognition-db/actions/workflows/ci.yml/badge.svg)](https://github.com/prime-slam/place-recognition-db/actions/workflows/ci.yml)
+[![Docs](https://github.com/prime-slam/place-recognition-db/actions/workflows/docs.yml/badge.svg)](https://prime-slam.github.io/place-recognition-db/docs/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
-The tool supports several basic methods for creating databases, as well as the DominatingSet method for creating optimal databases.
+PlaceRecognitionDB is a tool for creating optimally sized databases 
+(containing the minimum number of frames covering the scene) for place recognition task from RGBD and LiDAR data.
+
+The tool supports several basic methods for creating databases, 
+as well as the DominatingSet method for creating optimal databases.
+A detailed description of all methods for creating databases can be found in our [paper](https://arxiv.org/abs/2303.05123).
+
+The tool also contains a global localization pipeline with [CosPlace](https://github.com/gmberton/CosPlace) 
+and [NetVLAD](https://github.com/QVPR/Patch-NetVLAD). 
+The models of these neural networks can be fine-tuned for a particular previously created database. 
+The results of global localization can also be improved with [SuperGlue](https://github.com/magicleap/SuperGluePretrainedNetwork).
+More details about the available configurations for global localization and the results 
+are available in the [paper](https://arxiv.org/abs/2303.05123).
+
+We have also developed a set of metrics that can be used to evaluate 
+the quality of created databases and the accuracy of VPR systems.
+
+For more, please visit the [PlaceRecognitionDB documentation](https://prime-slam.github.io/place-recognition-db/docs/).
+You can also find full information about our research on the [website](https://prime-slam.github.io/place-recognition-db/).
 
 ## Datasets format
-To use the tool, your data must be in a specific format
-* Color images in any format
-* Depth images in 16-bit grayscale format or point clouds in `.pcd` format. The depth images must match the color images 
-pixel by pixel (and therefore have the same resolution). You should also know the intrinsic parameters of the camera and the depth scale if you use depth images
-* The trajectory containing one pose in each line in `timestamp tx ty tz qx qy qz qw` format. Timestamp is an optional argument that is not used in the library
-
-Thus, the tool supports the [TUM](https://cvg.cit.tum.de/data/datasets/rgbd-dataset/file_formats) format for datasets.
-
-The correspondence between poses, depth images, and color images is determined based on the order of lines in the trajectory file and the alphabetical order of the files.
-
-Therefore, the structure of the dataset should look like this:
-```
-Example dataset
-├── color
-|   ├── 001.png
-|   ├── 002.png
-|   ├── ...
-├── depth
-|   ├── 001.pcd or 001.png
-|   ├── 002.pcd or 002.png
-|   ├── ...
-└── CameraTrajectory.txt
-```
-The number of color images, depth images (or PCDs) and poses 
-in the trajectory file must be the same. The names of folders and the trajectory file are configurable.
+You can find detailed information about the data format used in the tool [here](https://prime-slam.github.io/place-recognition-db/docs/vprdb/io.html#datasets-format).
 
 ## Usage
-Please, check `example.ipynb` with usage example.
+Please check `example.ipynb` with a small example on creating a database.
+
+## License
+This project is licensed under the Apache License — 
+see the [LICENSE](https://github.com/prime-slam/place-recognition-db/blob/master/LICENSE) file for details.

vprdb/__init__.py

@@ -0,0 +1,16 @@
+#  Copyright (c) 2023, Ivan Moskalenko, Anastasiia Kornilova
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+"""
+.. include:: ../README.md
+"""

vprdb/core/__init__.py

@@ -11,6 +11,12 @@
 #  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
+"""
+`core` submodule contains a Database class for easy storage and processing of
+color images, depth images and trajectory and their further use for the VPR task.
+
+`VoxelGrid` and `utils` provide various operations on point clouds.
+"""
 from vprdb.core.database import Database
 from vprdb.core.utils import (
     calculate_iou,

vprdb/core/database.py

@@ -25,6 +25,11 @@
 
 @dataclass(frozen=True)
 class Database:
+    """
+    Class for easy storage and processing of color images, depth images
+    and trajectory and their further use for the VPR task
+    """
+
     color_images: list[ColorImageProvider]
     point_clouds: list[DepthImageProvider | PointCloudProvider]
     trajectory: list[NDArray[Shape["4, 4"], Float]]
@@ -44,6 +49,15 @@ def from_depth_images(
         intrinsics: NDArray[Shape["3, 3"], Float],
         trajectory: list[NDArray[Shape["4, 4"], Float]],
     ):
+        """
+        The method allows to construct the Database from scanning sequence
+        :param color_images_paths: List of paths to color images
+        :param depth_images_paths: List of paths to depth images
+        :param depth_scale: Depth scale for transforming depth image into point clouds
+        :param intrinsics: Intrinsic camera parameters
+        :param trajectory: List of camera poses
+        :return: Constructed database
+        """
         color_images_providers = [
             ColorImageProvider(path_to_image) for path_to_image in color_images_paths
         ]
@@ -60,6 +74,13 @@ def from_point_clouds(
         point_clouds_paths: list[Path],
         trajectory: list[NDArray[Shape["4, 4"], Float]],
     ):
+        """
+        The method allows to construct the Database from point clouds, color images and trajectory
+        :param color_images_paths: List of paths to color images
+        :param point_clouds_paths: List of paths to point clouds
+        :param trajectory: List of camera poses
+        :return: Constructed database
+        """
         color_images_providers = [
             ColorImageProvider(path_to_image) for path_to_image in color_images_paths
         ]

vprdb/global_localization/__init__.py

@@ -11,4 +11,9 @@
 #  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
+"""
+Pipeline for global localization allows to build matches between database and queries using different VPR systems.
+"""
 from vprdb.global_localization.global_localization import GlobalLocalization
+
+__all__ = ["GlobalLocalization"]

vprdb/global_localization/global_localization.py

@@ -21,6 +21,12 @@
 
 
 class GlobalLocalization:
+    """
+    Allows to create a predictor based on a given database
+    and one of the methods of global localization.
+    Results can be improved with SuperGlue.
+    """
+
     def __init__(
         self,
         global_extractor: CosPlace | NetVLAD,

vprdb/io/__init__.py

@@ -11,5 +11,37 @@
 #  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
+"""
+The `io` submodule allows to read datasets from the hard disk and export them.
+## Datasets format
+To use the tool, your data must be in a specific format
+* Color images in any format
+* Depth images in 16-bit grayscale format or point clouds in `.pcd` format.
+The depth images must match the color images pixel by pixel (and therefore have the same resolution).
+You should also know the intrinsic parameters of the camera and the depth scale if you use depth images
+* The trajectory containing one pose in each line in `timestamp tx ty tz qx qy qz qw` format.
+Timestamp is an optional argument that is not used in the library
+
+Thus, the tool supports the [TUM](https://cvg.cit.tum.de/data/datasets/rgbd-dataset/file_formats) format for datasets.
+
+The correspondence between poses, depth images, and color images
+is determined based on the order of lines in the trajectory file and the alphabetical order of the files.
+
+Therefore, the structure of the dataset should look like this:
+```
+Example dataset
+├── color
+|   ├── 001.png
+|   ├── 002.png
+|   ├── ...
+├── depth
+|   ├── 001.pcd or 001.png
+|   ├── 002.pcd or 002.png
+|   ├── ...
+└── CameraTrajectory.txt
+```
+The number of color images, depth images (or PCDs) and poses
+in the trajectory file must be the same. The names of folders and the trajectory file are configurable.
+"""
 from vprdb.io.export_utils import export
 from vprdb.io.read_utils import read_dataset_from_depth, read_dataset_from_point_clouds

vprdb/metrics/__init__.py

@@ -11,6 +11,12 @@
 #  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
-from vprdb.metrics.frames_coverage import frames_coverage
-from vprdb.metrics.recall import recall
-from vprdb.metrics.spatial_coverage import spatial_coverage
+"""
+Metrics allow to evaluate the quality of created databases,
+as well as to estimate the accuracy of various VPR systems.
+"""
+from vprdb.metrics.frames_coverage_ import frames_coverage
+from vprdb.metrics.recall_ import recall
+from vprdb.metrics.spatial_coverage_ import spatial_coverage
+
+__all__ = ["frames_coverage", "recall", "spatial_coverage"]

vprdb/providers/__init__.py

@@ -11,6 +11,9 @@
 #  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
+"""
+Providers are designed as wrappers over various types of heavy data, to load them into RAM only when needed.
+"""
 from vprdb.providers.color_image_provider import ColorImageProvider
 from vprdb.providers.depth_image_provider import DepthImageProvider
 from vprdb.providers.point_cloud_provider import PointCloudProvider

vprdb/providers/color_image_provider.py

@@ -20,8 +20,12 @@
 
 @dataclass(frozen=True)
 class ColorImageProvider:
+    """Color image provider is a wrapper for color images"""
+
     path: Path
+    """Path to the file on the hard drive"""
 
     @property
     def color_image(self) -> NDArray[Shape["*, *, 3"], UInt8]:
+        """Returns image in OpenCV format"""
         return cv2.imread(str(self.path), cv2.IMREAD_COLOR)

vprdb/providers/depth_image_provider.py

@@ -21,12 +21,18 @@
 
 @dataclass(frozen=True)
 class DepthImageProvider:
+    """Depth image provider is a wrapper for depth images"""
+
     path: Path
+    """Path to the file on the hard drive"""
     intrinsics: NDArray[Shape["3, 3"], Float]
+    """Intrinsic camera parameters"""
     depth_scale: int
+    """Depth scale for transforming depth"""
 
     @property
     def point_cloud(self) -> o3d.geometry.PointCloud:
+        """Returns Open3D point cloud constructed from depth image"""
         depth_image = cv2.imread(str(self.path), cv2.IMREAD_ANYDEPTH)
         height, width = depth_image.shape
         depth_image = o3d.geometry.Image(depth_image)

vprdb/providers/point_cloud_provider.py

@@ -19,8 +19,12 @@
 
 @dataclass(frozen=True)
 class PointCloudProvider:
+    """PointCloudProvider provider is a wrapper for point clouds"""
+
     path: Path
+    """Path to the file on the hard drive"""
 
     @property
     def point_cloud(self) -> o3d.geometry.PointCloud:
+        """Returns Open3D point cloud"""
         return o3d.io.read_point_cloud(str(self.path))

vprdb/reduction_methods/__init__.py

@@ -15,3 +15,5 @@
 from vprdb.reduction_methods.distance_vector import DistanceVector
 from vprdb.reduction_methods.dominating_set import DominatingSet
 from vprdb.reduction_methods.every_nth import EveryNth
+
+__all__ = ["CubeDivision", "DistanceVector", "DominatingSet", "EveryNth"]

vprdb/vpr_systems/__init__.py

@@ -11,6 +11,9 @@
 #  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
+""" The `vpr_systems` contains a set of tools for the VPR task. """
 from vprdb.vpr_systems.cos_place import CosPlace
 from vprdb.vpr_systems.netvlad import NetVLAD
 from vprdb.vpr_systems.superglue import SuperGlue
+
+__all__ = ["CosPlace", "NetVLAD", "SuperGlue"]

vprdb/vpr_systems/cos_place/__init__.py

@@ -12,3 +12,5 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 from vprdb.vpr_systems.cos_place.cos_place import CosPlace
+
+__all__ = ["CosPlace"]

vprdb/vpr_systems/cos_place/cos_place.py

@@ -36,6 +36,10 @@
 
 
 class CosPlace:
+    """
+    Implementation of [CosPlace](https://github.com/gmberton/CosPlace) global localization method.
+    """
+
     def __init__(self, backbone: str, fc_output_dim: int, path_to_weights: str):
         self.backbone = backbone
         self.fc_output_dim = fc_output_dim

vprdb/vpr_systems/netvlad/__init__.py

@@ -12,3 +12,5 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 from vprdb.vpr_systems.netvlad.netvlad import NetVLAD
+
+__all__ = ["NetVLAD"]

vprdb/vpr_systems/netvlad/netvlad.py

@@ -46,6 +46,10 @@
 
 
 class NetVLAD:
+    """
+    Implementation of [NetVLAD](https://github.com/QVPR/Patch-NetVLAD) global localization method.
+    """
+
     def __init__(
         self,
         path_to_weights: str,

vprdb/vpr_systems/superglue/__init__.py

@@ -12,3 +12,5 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 from vprdb.vpr_systems.superglue.superglue import SuperGlue
+
+__all__ = ["SuperGlue"]

vprdb/vpr_systems/superglue/superglue.py

@@ -53,6 +53,11 @@
 
 
 class SuperGlue:
+    """
+    Implementation of [SuperGlue](https://github.com/magicleap/SuperGluePretrainedNetwork)
+    matcher with SuperPoint extractor.
+    """
+
     def __init__(
         self,
         path_to_sp_weights,