Merge pull request #1 from lukasalexanderweber/pip_package

prepare pip package

Author: lukasalexanderweber

README.md

@@ -1,2 +1,71 @@
 # stitching
-Fast and Robust Image Stitching
+
+A Python package for fast and robust Image Stitching. A modularized and continuing work based on opencv's [stitching module](https://github.com/opencv/opencv/tree/4.x/modules/stitching) and the [stitching_detailed.py](https://github.com/opencv/opencv/blob/4.x/samples/python/stitching_detailed.py) python command line tool. 
+
+![inputs](https://github.com/lukasalexanderweber/stitching_tutorial/blob/master/docs/static_files/inputs.png?raw=true) 
+
+![result](https://github.com/lukasalexanderweber/stitching_tutorial/blob/master/docs/static_files/panorama.png?raw=true) 
+
+## Installation
+
+Use pip to install stitching from [PyPI](https://pypi.org/project/stitching/).
+
+```bash
+pip install stitching
+```
+
+## Usage
+
+```python
+import stitching
+
+stitcher = stitching.Stitcher()
+panorama = stitcher.stitch(["img1.jpg", "img2.jpg", "img3.jpg"])
+
+```
+
+or using the [command line tool](https://github.com/lukasalexanderweber/stitching/blob/main/stitching_tool.py)
+
+
+```
+python stitching_tool.py -h
+python stitching_tool.py img1.jpg img2.jpg img3.jpg
+```
+
+## Tutorial
+
+This package provides utility functions to deeply analyse what's happening behind the stitching. A tutorial was created as [Jupyter Notebook](https://github.com/lukasalexanderweber/stitching_tutorial). The preview is [here](https://github.com/lukasalexanderweber/stitching_tutorial/blob/master/docs/Stitching%20Tutorial.md).
+
+You can e.g. visualize the RANSAC matches between the images or the seam lines where the images are blended:
+
+![matches1](https://github.com/lukasalexanderweber/stitching_tutorial/blob/master/docs/static_files/matches1.png?raw=true) 
+![matches2](https://github.com/lukasalexanderweber/stitching_tutorial/blob/master/docs/static_files/matches2.png?raw=true) 
+![seams1](https://github.com/lukasalexanderweber/stitching_tutorial/blob/master/docs/static_files/seams1.png?raw=true) 
+![seams2](https://github.com/lukasalexanderweber/stitching_tutorial/blob/master/docs/static_files/seams2.png?raw=true) 
+
+## Literature
+
+This package was developed and used for our paper 'Automatic stitching of fragmented construction plans of hydraulic structures' https://doi.org/10.1002/bate.202200010
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
+
+Please make sure to update tests as appropriate.
+
+Run tests using
+
+```bash
+python -m unittest
+```
+
+Build with
+
+```bash
+python -m build
+```
+
+## License
+
+[Apache License 2.0](https://github.com/lukasalexanderweber/lir/blob/main/LICENSE)
+

pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=42"]
+build-backend = "setuptools.build_meta"

setup.cfg

@@ -0,0 +1,28 @@
+[metadata]
+name = stitching
+version = attr: stitching.__version__
+description = A Python package for fast and robust Image Stitching 
+long_description = file: README.md
+long_description_content_type = text/markdown
+author = Lukas Weber
+author_email = l.a.weber@outlook.de
+license = Apache License 2.0
+license_file = LICENSE
+platforms = any
+classifiers =
+    Programming Language :: Python :: 3 :: Only
+project_urls =
+	Source = https://github.com/lukasalexanderweber/stitching
+    Bug Tracker = https://github.com/lukasalexanderweber/stitching/issues
+
+[options]
+packages = find:
+install_requires =
+    opencv-python>=4.0.1
+	largestinteriorrectangle
+include_package_data = True
+zip_safe = False
+
+[options.packages.find]
+include = stitching
+exclude = tests

stitching/__init__.py

@@ -0,0 +1,3 @@
+from .stitcher import Stitcher
+
+__version__ = "0.0.1"

stitching/blender.py

@@ -0,0 +1,55 @@
+import cv2 as cv
+import numpy as np
+
+
+class Blender:
+    """https://docs.opencv.org/4.x/d6/d4a/classcv_1_1detail_1_1Blender.html"""  # noqa
+
+    BLENDER_CHOICES = ('multiband', 'feather', 'no',)
+    DEFAULT_BLENDER = 'multiband'
+    DEFAULT_BLEND_STRENGTH = 5
+
+    def __init__(self, blender_type=DEFAULT_BLENDER,
+                 blend_strength=DEFAULT_BLEND_STRENGTH):
+        self.blender_type = blender_type
+        self.blend_strength = blend_strength
+        self.blender = None
+
+    def prepare(self, corners, sizes):
+        dst_sz = cv.detail.resultRoi(corners=corners, sizes=sizes)
+        blend_width = (np.sqrt(dst_sz[2] * dst_sz[3]) *
+                       self.blend_strength / 100)
+
+        if self.blender_type == 'no' or blend_width < 1:
+            self.blender = cv.detail.Blender_createDefault(
+                cv.detail.Blender_NO
+                )
+
+        elif self.blender_type == "multiband":
+            self.blender = cv.detail_MultiBandBlender()
+            self.blender.setNumBands(int((np.log(blend_width) /
+                                          np.log(2.) - 1.)))
+
+        elif self.blender_type == "feather":
+            self.blender = cv.detail_FeatherBlender()
+            self.blender.setSharpness(1. / blend_width)
+
+        self.blender.prepare(dst_sz)
+
+    def feed(self, img, mask, corner):
+        self.blender.feed(cv.UMat(img.astype(np.int16)), mask, corner)
+
+    def blend(self):
+        result = None
+        result_mask = None
+        result, result_mask = self.blender.blend(result, result_mask)
+        result = cv.convertScaleAbs(result)
+        return result, result_mask
+
+    @classmethod
+    def create_panorama(cls, imgs, masks, corners, sizes):
+        blender = cls("no")
+        blender.prepare(corners, sizes)
+        for img, mask, corner in zip(imgs, masks, corners):
+            blender.feed(img, mask, corner)
+        return blender.blend()

stitching/camera_adjuster.py

@@ -0,0 +1,49 @@
+from collections import OrderedDict
+import cv2 as cv
+import numpy as np
+
+from .stitching_error import StitchingError
+
+
+class CameraAdjuster:
+    """https://docs.opencv.org/4.x/d5/d56/classcv_1_1detail_1_1BundleAdjusterBase.html"""  # noqa
+
+    CAMERA_ADJUSTER_CHOICES = OrderedDict()
+    CAMERA_ADJUSTER_CHOICES['ray'] = cv.detail_BundleAdjusterRay
+    CAMERA_ADJUSTER_CHOICES['reproj'] = cv.detail_BundleAdjusterReproj
+    CAMERA_ADJUSTER_CHOICES['affine'] = cv.detail_BundleAdjusterAffinePartial
+    CAMERA_ADJUSTER_CHOICES['no'] = cv.detail_NoBundleAdjuster
+
+    DEFAULT_CAMERA_ADJUSTER = list(CAMERA_ADJUSTER_CHOICES.keys())[0]
+    DEFAULT_REFINEMENT_MASK = "xxxxx"
+
+    def __init__(self,
+                 adjuster=DEFAULT_CAMERA_ADJUSTER,
+                 refinement_mask=DEFAULT_REFINEMENT_MASK):
+
+        self.adjuster = CameraAdjuster.CAMERA_ADJUSTER_CHOICES[adjuster]()
+        self.set_refinement_mask(refinement_mask)
+        self.adjuster.setConfThresh(1)
+
+    def set_refinement_mask(self, refinement_mask):
+        mask_matrix = np.zeros((3, 3), np.uint8)
+        if refinement_mask[0] == 'x':
+            mask_matrix[0, 0] = 1
+        if refinement_mask[1] == 'x':
+            mask_matrix[0, 1] = 1
+        if refinement_mask[2] == 'x':
+            mask_matrix[0, 2] = 1
+        if refinement_mask[3] == 'x':
+            mask_matrix[1, 1] = 1
+        if refinement_mask[4] == 'x':
+            mask_matrix[1, 2] = 1
+        self.adjuster.setRefinementMask(mask_matrix)
+
+    def adjust(self, features, pairwise_matches, estimated_cameras):
+        b, cameras = self.adjuster.apply(features,
+                                         pairwise_matches,
+                                         estimated_cameras)
+        if not b:
+            raise StitchingError("Camera parameters adjusting failed.")
+
+        return cameras

stitching/camera_estimator.py

@@ -0,0 +1,28 @@
+from collections import OrderedDict
+import cv2 as cv
+import numpy as np
+
+from .stitching_error import StitchingError
+
+
+class CameraEstimator:
+    """https://docs.opencv.org/4.x/df/d15/classcv_1_1detail_1_1Estimator.html"""  # noqa
+
+    CAMERA_ESTIMATOR_CHOICES = OrderedDict()
+    CAMERA_ESTIMATOR_CHOICES['homography'] = cv.detail_HomographyBasedEstimator
+    CAMERA_ESTIMATOR_CHOICES['affine'] = cv.detail_AffineBasedEstimator
+
+    DEFAULT_CAMERA_ESTIMATOR = list(CAMERA_ESTIMATOR_CHOICES.keys())[0]
+
+    def __init__(self, estimator=DEFAULT_CAMERA_ESTIMATOR, **kwargs):
+        self.estimator = CameraEstimator.CAMERA_ESTIMATOR_CHOICES[estimator](
+            **kwargs
+            )
+
+    def estimate(self, features, pairwise_matches):
+        b, cameras = self.estimator.apply(features, pairwise_matches, None)
+        if not b:
+            raise StitchingError("Homography estimation failed.")
+        for cam in cameras:
+            cam.R = cam.R.astype(np.float32)
+        return cameras

stitching/camera_wave_corrector.py

@@ -0,0 +1,29 @@
+from collections import OrderedDict
+import cv2 as cv
+import numpy as np
+
+
+class WaveCorrector:
+    """https://docs.opencv.org/4.x/d7/d74/group__stitching__rotation.html#ga8faf9588aebd5aeb6f8c649c82beb1fb"""  # noqa
+
+    WAVE_CORRECT_CHOICES = OrderedDict()
+    WAVE_CORRECT_CHOICES['horiz'] = cv.detail.WAVE_CORRECT_HORIZ
+    WAVE_CORRECT_CHOICES['vert'] = cv.detail.WAVE_CORRECT_VERT
+    WAVE_CORRECT_CHOICES['auto'] = cv.detail.WAVE_CORRECT_AUTO
+    WAVE_CORRECT_CHOICES['no'] = None
+
+    DEFAULT_WAVE_CORRECTION = list(WAVE_CORRECT_CHOICES.keys())[0]
+
+    def __init__(self, wave_correct_kind=DEFAULT_WAVE_CORRECTION):
+        self.wave_correct_kind = WaveCorrector.WAVE_CORRECT_CHOICES[
+            wave_correct_kind
+            ]
+
+    def correct(self, cameras):
+        if self.wave_correct_kind is not None:
+            rmats = [np.copy(cam.R) for cam in cameras]
+            rmats = cv.detail.waveCorrect(rmats, self.wave_correct_kind)
+            for idx, cam in enumerate(cameras):
+                cam.R = rmats[idx]
+            return cameras
+        return cameras