Merge pull request #33 from MrClock8163/feature/panorama

Panorama capture and processing

Author: MrClock8163

.github/workflows/run-tests.yml

@@ -23,7 +23,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Build and install package
-        run: python -m pip install .
+        run: python -m pip install .[all]
 
       - name: Test with pytest
         run: |
@@ -47,7 +47,7 @@ jobs:
           python-version: 3.x
 
       - name: Build and install package
-        run: python -m pip install .
+        run: python -m pip install .[all]
 
       - name: Running ${{ matrix.tool }}
         run: |

.readthedocs.yaml

@@ -8,7 +8,7 @@ build:
     pre_build:
       - python -m pip install --upgrade pip
       - python -m pip install --group documentation
-      - python -m pip install .
+      - python -m pip install .[all]
 
 sphinx:
   configuration: docs/conf.py

CHANGELOG.md

@@ -9,6 +9,8 @@ The project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- Added panorama capturing (`capture panorama`)
+- Added panorama processing (`process panorama`)
 - Added GeoCOM shutdown utility (`shutdown geocom`)
 - Added GeoCOM startup utility (`startup geocom`)
 - Added GSI Online DNA shutdown utility (`shutdown gsidna`)

README.md

@@ -55,7 +55,11 @@ cd Instrumentman
 python -m pip install .
 ```
 
+Some commands require additional dependencies, that are not installed by
+default with I-man. These are indicated in the documentations of the specific
+commands.
+
 ## License
 
-I-man is free and open source software, and it is distributed under the terms of the
-[MIT License](https://opensource.org/license/mit).
+I-man is free and open source software, and it is distributed under the terms
+of the [MIT License](https://opensource.org/license/mit).

docs/commands/panorama/image_positions.png

@@ -0,0 +1,18 @@
+:icon: material/panorama-variant-outline
+
+Panorama
+========
+
+For documentation purposes it might be useful to have an image of the measured
+area with the measured points annotated. Total stations with integrated cameras
+usually have a panorama capture on-board program, but it provides to way to
+annotate the recorded points.
+
+The panorama commands provide a way to capture frames of a panorama, and
+merge them together with optional point annotations.
+
+.. toctree::
+    :maxdepth: 1
+
+    measure
+    process

docs/commands/panorama/index.rst

@@ -0,0 +1,68 @@
+Measuring
+=========
+
+To create a panorama image from different images taken from a common center
+point, the orientatiobs of the images have to be known among other camera
+properties. The necessary data can be derived from independent calibration and
+screenshots during the on-board panorama program.
+
+To simplify the process, this command can be used to capture images with the
+necessary metadata automatically being recorded as reported by the instrument.
+
+Requirements
+------------
+
+- GeoCOM capable robotic total station with overview camera and imaging license
+
+Positions
+---------
+
+The program takes images in a region defined by a horizontal and vertical angle
+range. Two convenience settings exists (in addition to the default), that
+reduce the number of angle inputs needed for specific cases:
+
+- region: horizontal and vertical range is required (this is the default)
+- strip: 360 degree horizontal coverage with given vertical range
+- sphere: complete spherical panorama
+
+.. note::
+
+    The complete sphere panorama is not very practical, and more of a proof of
+    concept, as capturing the full view takes impractically long time.
+
+If adaptive FoV is enabled for the position layout generation, images that are
+taken at angles that deviate from the horizontal position are considered to
+cover a wider horizontal angle area. To avoid taking unnecessary images, the
+top and bottom rows have fewer images.
+
+.. image:: image_positions.png
+
+To reduce the parallax errors of close range objects caused by the camera
+offset, it is possible to increase the overlap between images (effectively
+reducing the motion between images), but this can significantly increase the
+required number of images and time (e.g. full sphere panorama with 30%
+overlap requires approximately 1500 images).
+
+Examples
+--------
+
+.. code-block:: shell
+    :caption: Capturing panorama with interactive region definition and default settings
+
+    iman capture panorama COM1 metadata.json
+
+.. code-block:: shell
+    :caption: Capturing full sphere panorama with custom file prefix
+
+    iman capture panorama --shape sphere --prefix panosphere_ COM1 metadata.json
+
+.. code-block:: shell
+    :caption: Capturing predefined 360 panorama strip
+
+    iman capture panorama --strip strip --vertical 70-00-00 110-00-00 COM1 metadata.json
+
+Usage
+-----
+
+.. click:: instrumentman.panorama:cli_measure
+    :prog: iman capture panorama

docs/commands/panorama/measure.rst

@@ -0,0 +1,58 @@
+Processing
+==========
+
+.. caution::
+    :class: warning
+
+    The panorama image processing requires extra dependencies.
+
+    - opencv-python
+
+    Install them manually, or install instrumentman with the 'panorama' extra:
+
+    .. code-block:: shell
+        
+        python -m pip install instrumentman[panorama]
+
+The processing command can be used to merge individual frames of a panorama
+capture into a single image, and optionally annotate points on it.
+
+The accuracy of the annotation is usually a few centimeters.
+
+Requirements
+------------
+
+- Image metadata JSON file
+- Images downloaded from the instrument
+
+Examples
+--------
+
+.. code-block:: shell
+    :caption: Merging images
+
+    iman process panorama metadata.json merged_panorama.jpg panorama*.jpg
+
+
+.. code-block:: shell
+    :caption: Merging images and annotating points
+
+    iman process panorama --annotate points.csv --fontsize 50 metadata.json merged_panorama.jpg panorama*.jpg
+
+.. code-block:: shell
+    :caption: Merging full sphere panorama with downscaling to fit into OpenCV limits
+
+    iman process panorama --scale 2000 metadata.json merged_panorama.jpg panorama*.jpg
+
+.. code-block:: text
+    :caption: Example points file for annotations (with the optional label column present)
+
+    P0001,1.0,1.0,0.0,BENCHMARK
+    P0002,1.0,2.0,1.0,BENCHMARK
+    P0003,1.0,2.0,3.0,TOPO
+
+Usage
+-----
+
+.. click:: instrumentman.panorama:cli_calc
+    :prog: iman process panorama

docs/commands/panorama/process.rst

@@ -41,6 +41,7 @@ Content
     commands/targets/index
     commands/sets/index
     commands/inclination/index
+    commands/panorama/index
     commands/protocoltest/index
     commands/files/index
     commands/data/index

docs/index.rst

@@ -26,6 +26,7 @@ Applications
     commands/targets/index
     commands/sets/index
     commands/inclination/index
+    commands/panorama/index
     commands/protocoltest/index
     commands/files/index
     commands/data/index