[panorama] added docs

Author: MrClock8163

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,61 @@
+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 very practical, and more of a proof of
+    concept, as capturing the full view takes impractically long time.
+
+Images that are taken at angles that deviate from the horizontal position
+cover a wider horizontal angle area. To avoid taking unnecessary images, the
+top and bottom rows have fewer images.
+
+.. image:: image_positions.png
+
+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_process
+    :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

docs/latexindex.rst

@@ -107,7 +107,7 @@ def cli(
     )
 
 
-@cli.group("measure")  # type: ignore[misc]
+@cli.group("measure", aliases=["capture"])  # type: ignore[misc]
 def cli_measure() -> None:
     """Conduct measurements."""