Prepare first release (#2)

* Cleaning up readme, working on example code

* Add example code

* Running example as part of test

* Adding license

* Bumping version

.gitignore

@@ -20,6 +20,7 @@ parts/
 sdist/
 var/
 wheels/
+wheelhouse/
 share/python-wheels/
 *.egg-info/
 .installed.cfg

LICENSE.txt

@@ -0,0 +1,60 @@
+Copyright (c) 2021, Jonas Schüpfer
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+----
+
+This binary distribution also bundles the following software:
+https://gitlab.com/srrg-software/srrg_hbst
+
+Copyright (c) 2018, Dominik Schlegel, Giorgio Grisetti
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

README.md

@@ -1,23 +1,48 @@
 # hbst-python
 
-## Installation
+Python bindings and pre-compiled binaries for the [Hamming Binary Search Tree (HBST)](https://gitlab.com/srrg-software/srrg_hbst)
+for visual place recognition with binary descriptors. The HBST algorithm and [paper](https://arxiv.org/abs/1802.09261)
+is not my work, if you use this library please cite the original authors:
 
+```
+@article{2018-schlegel-hbst, 
+  author  = {D. Schlegel and G. Grisetti}, 
+  journal = {IEEE Robotics and Automation Letters}, 
+  title   = {{HBST: A Hamming Distance Embedding Binary Search Tree for Feature-Based Visual Place Recognition}}, 
+  year    = {2018}, 
+  volume  = {3}, 
+  number  = {4}, 
+  pages   = {3741-3748}
+}
+```
 
-## Usage
 
+## Installation and Usage
 
-### Basic Example
+```bash
+pip install hbst-python
+```
 
+Note that currently only Linux x86_64 is supported.
 
-### Using OpenCV Descriptors
+To get started check out the [example](example/match.py) with OpenCV descriptors and HBST. Note that this matcher
+will only produce useful results with binary descriptors (e.g. ORB, BRISK or AKAZE). It is not suitable for SIFT,
+SURF and the likes.
 
 
-## Build
+## Development
 
+Development use cases are dockerized. The commands below will spawn the respective
+docker container mount the repo inside and get the job done.
 
-## References
+Syntax:
+```bash
+./build.sh [platform] [python-version]
+./test.sh [platform] [python-version]
+```
 
-
-https://gitlab.com/srrg-software/srrg_hbst
-
-https://gitlab.com/srrg-software/srrg_hbst_examples
+Example:
+```bash
+./build.sh x86_64 3.8
+./test.sh x86_64 3.8
+```

docker/python36/buster.Dockerfile

@@ -2,4 +2,4 @@ FROM python:3.6.15-slim-buster
 
 RUN pip install \
     pytest \
-    numpy
+    opencv-python-headless==4.*

docker/python37/buster.Dockerfile

@@ -2,4 +2,4 @@ FROM python:3.7.12-slim-buster
 
 RUN pip install \
     pytest \
-    numpy
+    opencv-python-headless==4.*

docker/python38/buster.Dockerfile

@@ -2,4 +2,4 @@ FROM python:3.8.12-slim-buster
 
 RUN pip install \
     pytest \
-    numpy
+    opencv-python-headless==4.*

docker/python39/buster.Dockerfile

@@ -2,4 +2,4 @@ FROM python:3.9.9-slim-buster
 
 RUN pip install \
     pytest \
-    numpy
+    opencv-python-headless==4.*

example/match.py

@@ -0,0 +1,45 @@
+import time
+
+import cv2 as cv
+
+from matcher import BruteForceMatcher, HbstMatcher
+
+
+def run() -> None:
+    train_paths = ["images/graf1.png", "images/leuvenA.jpg"]
+    test_paths = ["images/leuvenB.jpg"]
+
+    orb = cv.ORB_create(1000)
+    train_features = {}
+    for i, path in enumerate(train_paths):
+        im = cv.imread(path)
+        kps, descs = orb.detectAndCompute(im, mask=None)
+        train_features[i] = (kps, descs)
+
+    max_dist = 50  # hamming distance (number of bit flips)
+    matchers = [
+        BruteForceMatcher(orb.defaultNorm(), train_features, max_dist=max_dist),
+        HbstMatcher(orb.descriptorSize() * 8, train_features, max_dist=max_dist)
+    ]
+
+    for path in test_paths:
+        print(f"testing {path}")
+        print()
+
+        im = cv.imread(path)
+        _, query_descs = orb.detectAndCompute(im, mask=None)
+
+        for matcher in matchers:
+            t0 = time.time()
+            matches = matcher.match(query_descs)
+            dt = time.time() - t0
+
+            print(f"{matcher.__class__.__name__} took {dt:.3f} seconds")
+            counts_by_im_id = {im_id: len(ms) for im_id, (ms, _) in matches.items()}
+            for im_id, count in sorted(counts_by_im_id.items(), key=lambda x: -x[1]):
+                print(f"{count} matches with {train_paths[im_id]}")
+            print()
+
+
+if __name__ == "__main__":
+    run()

example/matcher.py

@@ -0,0 +1,86 @@
+from typing import Dict, List, Mapping, Tuple
+
+import cv2 as cv
+import hbst
+import numpy as np
+
+
+class Matcher(object):
+
+    def __init__(self, features: Dict[int, Tuple[List[cv.KeyPoint], np.ndarray]]) -> None:
+        self.features = features
+
+    def get_keypoint(self, im_id: int, desc_id: int) -> cv.KeyPoint:
+        return self.features[im_id][0][desc_id]
+
+    def get_descriptor(self, im_id: int, desc_id: int) -> np.ndarray:
+        return self.features[im_id][1][desc_id]
+
+    def match(self, query_descs: np.ndarray) -> Dict[int, Tuple[List[cv.DMatch], Mapping[int, cv.KeyPoint]]]:
+        raise NotImplementedError()
+
+
+class BruteForceMatcher(Matcher):
+
+    def __init__(self, norm: int, features: Dict[int, Tuple[List[cv.KeyPoint], np.ndarray]],
+                 max_dist: int = 25) -> None:
+        super().__init__(features)
+        self.bfm = cv.BFMatcher(norm)
+        self.max_dist = max_dist
+
+    def match(self, query_descs: np.ndarray) -> Dict[int, Tuple[List[cv.DMatch], Mapping[int, cv.KeyPoint]]]:
+        matches = {}
+        for key in self.features.keys():
+            matches[key] = self.match_single(key, query_descs)
+        return matches
+
+    def match_single(self, im_id: int, query_descs: np.ndarray) -> Tuple[List[cv.DMatch], Mapping[int, cv.KeyPoint]]:
+        kp, descs = self.features[im_id]
+        matches = self.bfm.knnMatch(query_descs, descs, k=2)
+        good_matches: List[cv.DMatch] = []
+        for m, n in matches:
+            if m.distance <= self.max_dist:
+                good_matches.append(m)
+        return good_matches, {k: v for k, v in enumerate(kp)}
+
+
+class HbstMatcher(Matcher):
+
+    def __init__(self, bits: int, features: Dict[int, Tuple[List[cv.KeyPoint], np.ndarray]],
+                 max_dist: int = 25, pad_if_required: bool = False) -> None:
+        super().__init__(features)
+        tree_cls = {128: hbst.BinaryTree128,
+                    256: hbst.BinaryTree256,
+                    488: hbst.BinaryTree488,
+                    512: hbst.BinaryTree512}.get(bits)
+        if tree_cls is None:
+            raise ValueError(f"No tree available with descriptor size of {bits} bits")
+
+        self.tree = tree_cls(pad_if_required)
+        self.max_dist = max_dist
+        for im_id, (_, descs) in features.items():
+            self.tree.add(im_id, np.arange(len(descs), dtype=np.uint64), descs)
+        self.tree.train(hbst.SplittingStrategy.SplitEven)
+
+    def match(self, query_descs: np.ndarray) -> Dict[int, Tuple[List[cv.DMatch], Mapping[int, cv.KeyPoint]]]:
+        all_matches = self.tree.match(np.arange(len(query_descs), dtype=np.uint64), query_descs,
+                                      max_distance=self.max_dist)
+        all_matches_by_im_id, _ = self.tree.partition_matches(all_matches)
+
+        matches_converted: Dict[int, Tuple[List[cv.DMatch], Mapping[int, cv.KeyPoint]]] = {}
+        for im_id, matches in all_matches_by_im_id.items():
+            dms = []
+            kps = {}
+
+            for m in matches:
+                for ref in m.match_refs:
+                    for image_id_, train_descriptor_id in ref.descriptor_id_by_image_id.items():
+                        dm = cv.DMatch(_distance=m.distance, _imgIdx=image_id_, _queryIdx=m.query_descriptor_id,
+                                       _trainIdx=train_descriptor_id)
+                        kp = self.get_keypoint(im_id, train_descriptor_id)
+                        dms.append(dm)
+                        kps[train_descriptor_id] = kp
+
+            matches_converted[im_id] = (dms, kps)
+
+        return matches_converted

example/requirements.txt

@@ -0,0 +1,2 @@
+hbst-python
+opencv-python

setup.py

@@ -1,5 +1,4 @@
 import os
-import re
 import subprocess
 import sys
 import shutil
@@ -9,7 +8,7 @@
 
 
 NAME = "hbst-python"
-VERSION = "0.0.1rc1"
+VERSION = "0.0.1"
 DEBUG = False
 
 
@@ -73,7 +72,7 @@ def finalize_options(self):
         pass
 
     def run(self):
-        for d in ("build", "dist", NAME.replace("-", "_")):
+        for d in ("build", "dist", NAME.replace("-", "_"), "wheelhouse"):
             if os.path.exists(d):
                 shutil.rmtree(d)
 
@@ -83,13 +82,20 @@ def run(self):
     version=VERSION,
     author="Jonas Schuepfer",
     author_email="[email protected]",
-    description="Python bindings for the original hamming distance embedding binary search tree for feature-based visual place recognition implementation",
-    long_description="",
+    description="Python bindings for hbst library for visual place recognition",
+    long_description=("Python bindings for the original implementation of the hamming distance embedding binary"
+                      "search tree for feature-based visual place recognition implementation,"
+                      "see https://gitlab.com/srrg-software/srrg_hbst"),
+    project_urls={"Source Code": "https://github.com/osanj/hbst-python"},
+    license="BSD",
+    platforms=["Linux"],
     ext_modules=[CMakeExtension(NAME)],
     cmdclass={
         "build_ext": CMakeBuild,
         "clean": CleanCommand
     },
+    license_files=("LICENSE.txt",),
+    install_requires=["numpy"],
     zip_safe=False,
     python_requires=">=3.6",
-)
+)

test-compose.yml

@@ -4,7 +4,7 @@ x-linux_x86_64_common: &linux_x86_64_common
   volumes:
     - .:/repo
   working_dir: /repo
-  command: bash -c "pip install ${WHEEL} && pytest -v tests"
+  command: bash -c "pip install ${WHEEL} && pytest -v tests && cd example && python3 match.py"
 
 services:
   linux_x86_64_python_36:

test.sh

@@ -8,7 +8,7 @@ PYTHON_3_9="3.9"
 
 PLAT=$1
 PYTHON=$2
-WHEEL_DIR=${3:-dist}
+WHEEL_DIR=${3:-wheelhouse}
 
 if [ -z "$PLAT" ] || [ -z "$PYTHON" ]; then
     echo "usage: $0 platform python-version"