MrClock8163 · MrClock8163 · Oct 6, 2025 · Aug 26, 2025 · Aug 26, 2025 · Aug 26, 2025
diff --git a/.github/workflows/run-tests.yml b/.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: |

diff --git a/.readthedocs.yaml b/.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

diff --git a/CHANGELOG.md b/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`)

diff --git a/README.md b/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).
diff --git a/docs/commands/panorama/image_positions.png b/docs/commands/panorama/image_positions.png
diff --git a/docs/commands/panorama/index.rst b/docs/commands/panorama/index.rst
@@ -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
diff --git a/docs/commands/panorama/measure.rst b/docs/commands/panorama/measure.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
diff --git a/docs/commands/panorama/process.rst b/docs/commands/panorama/process.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
diff --git a/docs/index.rst b/docs/index.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

diff --git a/docs/latexindex.rst b/docs/latexindex.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

diff --git a/pyproject.toml b/pyproject.toml
@@ -22,6 +22,7 @@ dependencies = [
     "toml ~= 0.10.2",
     "PyYAML ~= 6.0.2",
     "numpy ~= 2.0",
+    "pillow ~= 11.0",
     "cloup ~= 3.0.7",
     "click-extra ~= 5.0.2"
 ]
@@ -59,6 +60,12 @@ Changelog = "https://instrumentman.readthedocs.io/latest/changelog"
 [project.scripts]
 iman = "instrumentman:cli"
 
+[project.optional-dependencies]
+all = ["instrumentman[panorama]"]
+panorama = [
+    "opencv-python~=4.8"
+]
+
 [dependency-groups]
 testing = [
     "pytest ~= 8.4.1"

diff --git a/src/instrumentman/__init__.py b/src/instrumentman/__init__.py
@@ -22,6 +22,7 @@
 from . import station
 from . import protocoltest
 from . import inclination
+from . import panorama
 from . import filetransfer
 from . import jobs
 from . import datatransfer
@@ -107,7 +108,7 @@ def cli(
     )
 
 
-@cli.group("measure")  # type: ignore[misc]
+@cli.group("measure", aliases=["capture"])  # type: ignore[misc]
 def cli_measure() -> None:
     """Conduct measurements."""
 
@@ -117,7 +118,7 @@ def cli_convert() -> None:
     """Convert between various file formats."""
 
 
-@cli.group("calculate", aliases=["calc"])  # type: ignore[misc]
+@cli.group("calculate", aliases=["calc", "process"])  # type: ignore[misc]
 def cli_calc() -> None:
     """Preform calculations from measurement results."""
 
@@ -173,9 +174,11 @@ def cli_startup() -> None:
 cli_measure.add_command(setmeasurement.cli_measure)
 cli_measure.add_command(setup.cli_measure)
 cli_measure.add_command(inclination.cli_measure)
+cli_measure.add_command(panorama.cli_measure)
 cli_calc.add_command(setmeasurement.cli_calc)
 cli_calc.add_command(inclination.cli_calc)
 cli_calc.add_command(station.cli_calc)
+cli_calc.add_command(panorama.cli_calc)
 cli_test.add_command(protocoltest.cli_geocom)
 cli_test.add_command(protocoltest.cli_gsidna)
 cli_merge.add_command(setmeasurement.cli_merge)