Merge pull request #59 from MrClock8163/feature-apps

First applications

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,11 +47,11 @@ 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: |
           python -m pip install --upgrade pip
           python -m pip install --group linting
           python -c "print('=========== ${{ matrix.tool }} ===========')"
-          python -m ${{ matrix.tool }} src/ tests/ examples/
+          python -m ${{ matrix.tool }} src/ tests/

.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

@@ -1,5 +1,14 @@
 # Changelog
 
+## v0.7.0
+
+### Added
+
+- `retry` option to `open_serial`
+- Morse CLI application (`geocompy.apps.morse`)
+- Interactive Terminal CLI application (`geocompy.apps.terminal`)
+- Set Measurement CLI applications (`geocompy.apps.setmeasurement...`)
+
 ## v0.6.0
 
 ### Added

README.md

@@ -29,14 +29,20 @@ the GSI Online command set is used for communication.
 - Primitives for relevant data
 - Command building and parsing through function calls
 - Multiple supported protocols (e.g. GeoCom, GSI Online)
+- Command line applications
 
 ## Requirements
 
 To use the package, Python 3.11 or higher is required.
+
 For the platform independent serial communication, GeoComPy relies on the
 [pySerial](https://pypi.org/project/pyserial/) package to provide the
 necessary abstractions.
 
+The command line applications might require additional dependencies, that
+are not installed by default. The requirements for these can be found in
+the relevant documentation.
+
 ## Installation
 
 The preferred method to install GeoComPy is through PyPI, where both wheel
@@ -46,6 +52,14 @@ and source distributions are made available.
 python -m pip install geocompy
 ```
 
+The dependencies of the command line applications are not installed by
+default. To make the CLI apps usable either install the dependencies
+manually, or install GeoComPy with the ``apps`` extra.
+
+```shell
+python -m pip install geocompy[apps]
+```
+
 If not yet published changes/fixes are needed, that are only available in
 source, GeoComPy can also be installed locally from source, without any
 external tools. Once the repository is cloned to a directory, it can be

docs/apps/morse.rst

@@ -0,0 +1,21 @@
+Morse
+=====
+
+.. versionadded:: 0.7.0
+
+.. code-block:: shell
+    :caption: Invoking the application
+
+    python -m geocompy.apps.morse
+
+The Morse CLI application is a (admittedly not very useful) demo program,
+that relays a Morse encoded ASCII message through the speakers of a total
+station. The signals are played with the man-machine interface beep signals
+of the instrument.
+
+Usage
+-----
+
+.. argparse::
+    :module: geocompy.apps.morse
+    :func: cli

docs/apps/setmeasurement/index.rst

@@ -0,0 +1,19 @@
+Set Measurement
+===============
+
+.. versionadded:: 0.6.0
+
+The set measurement CLI applications provide a simple way to conduct monitoring
+measurements to a set of predefined target points, using a GeoCom capable
+total station.
+
+.. note::
+
+    The various subcommands are available as CLI submodules.
+
+.. toctree::
+    :maxdepth: 1
+
+    setup
+    measure
+    process

docs/apps/setmeasurement/measure.rst

@@ -0,0 +1,77 @@
+Measure
+=======
+
+.. code-block:: shell
+    :caption: Invoking the application
+
+    python -m geocompy.apps.setmeasurement.measure -h
+
+Once the target definition JSON is created, the measurement sets can
+be started. In each measurement session the time, internal temperature
+and battery level are recorded at start. For each target the horizontal angle,
+zenith angle and slope distance are recorded.
+
+Order
+-----
+
+The measurement order can have a significant effect on the time it takes to
+complete a full cycle. The fastest order of face 1-2 measurement pairs is
+``ABba`` or ``ABab``, that involve the smallest number of face changes. Other
+orders might be benefitial if the targets cannot be occupied for the duration
+of the full cycle. The figure below illustrates the different supported
+measurement patterns. The default order is ``ABba``.
+
+.. note::
+    
+    The measurement order has the most significant effect on overall cycle
+    duration with older instruments, where the switch between two faces is
+    usuallay takes around 5-6 seconds. These small intervals can add up over
+    long sets or surveys.
+
+.. image:: order.png
+   :width: 400
+   :align: center
+   :alt: Set measurement order
+
+Results
+-------
+
+The results from each session are saved into a separate JSON file. These
+can be later merged for processing if necessary.
+
+Scheduling
+----------
+
+Periodic measurement sessions can be echieved by settings up a scheduled
+task in the scheduler tool of the respective operating system of the
+controlling computer (e.g. Task Scheduler on Windows, crontab on Linux).
+
+Examples
+--------
+
+.. code-block:: shell
+    :caption: Logging to file
+
+    python -m geocompy.apps.setmeasurement.measure --debug COM3 targets.json results >> tps.log 2>&1
+
+.. code-block:: shell
+    :caption: Enabling connection retries and timeout recovery attempts (might be useful with bluetooth connections)
+
+    python -m geocompy.apps.setmeasurement.measure -r 3 -sat COM3 targets.json results
+
+.. code-block:: shell
+    :caption: Measuring to just a subset of the targets
+
+    python -m geocompy.apps.setmeasurement.measure -pt "P1,P2,P8" COM3 targets.json results
+
+.. code-block:: shell
+    :caption: Measuring in face 1 only
+
+    python -m geocompy.apps.setmeasurement.measure -o ABCD COM3 targets.json results
+
+Usage
+-----
+
+.. argparse::
+    :module: geocompy.apps.setmeasurement.measure
+    :func: cli

docs/apps/setmeasurement/order.png

@@ -0,0 +1,58 @@
+Process
+=======
+
+.. code-block:: shell
+    :caption: Invoking the application
+
+    python -m geocompy.apps.setmeasurement.process -h
+
+.. caution::
+    :class: warning
+
+    The Set Measurement processing requires
+    `jsonschema <https://pypi.org/project/jsonschema/>`_ and
+    `jmespath <https://pypi.org/project/jmespath/>`_ to be installed.
+
+    Install them manually, or install GeoComPy with the ``apps`` extra.
+
+    .. code-block:: shell
+
+        pip install geocompy[apps]
+
+After set measurements are done, the results need to be processed. Thanks
+to the easily usable JSON format, this can be done with custom scripts if
+needed. For more general use cases, a few processing commands are available
+here.
+
+Merging
+-------
+
+The results of every set measurement session are saved to a separate file.
+When multiple sessions are measured using the same targets from the same
+station, the data files need to be merged to process them together.
+
+.. note::
+
+    The merge will be refused if the station information, or the target
+    points do not match between the targeted sessions.
+
+Validation
+----------
+
+After the measurement sessions are finished, it might be useful to validate,
+that each session succeeded, no points were skipped.
+
+Calculation
+-----------
+
+The most common calculation needed after set measurements is the determination
+of the target coordinates, from results of multiple measurement sessions and/or
+cycles. The resulting coordinates (as well as their deviations) are saved
+to a simple CSV file.
+
+Usage
+-----
+
+.. argparse::
+    :module: geocompy.apps.setmeasurement.process
+    :func: cli

docs/apps/setmeasurement/process.rst

@@ -0,0 +1,59 @@
+Setup
+=====
+
+.. code-block:: shell
+    :caption: Invoking the application
+
+    python -m geocompy.apps.setmeasurement.setup -h
+
+The targets first must be defined in a JSON format, providing the point
+IDs, prism types and their 3D coordinates in an arbitrary coordinate
+system. This module can be used to create such a definition.
+
+.. note::
+
+    A station setup and orientation must be in the same system as the
+    targets. If there is no predefined coordinate system, an arbitrary
+    local, station centered setup can be used as well.
+
+Usage
+-----
+
+.. argparse::
+    :module: geocompy.apps.setmeasurement.setup
+    :func: cli
+
+    measure : @replace
+        The program will give instructions in the terminal at each step. For
+        each point an ID is requested, then the target must be aimed at.
+
+        .. caution::
+            :class: warning
+
+            The appropriate prism type needs to be set on the instrument before
+            recording each target point. The program will automatically request
+            the type from the instrument after the point is measured.
+    
+    import : @replace
+        If a coordinate list already exists with the target points, it can
+        be imported from CSV format.
+
+        As a CSV file may contain any number and types of columns, the
+        mapping to the relevant columns can be given with a column spec.
+        A column spec is a string, with each character representing a
+        column type.
+
+        - ``P``: point ID
+        - ``E``: easting
+        - ``N``: northing
+        - ``Z``: up/height
+        - ``_``: ignore/skip column
+
+        Every column spec must specify the ``PENZ`` fields in the appropriate
+        order.
+
+        Examples:
+
+        - ``PENZ``: standard column order
+        - ``P_ENZ``: skipping 2nd column containing point codes
+        - ``EN_Z_P``: mixed column order and skipping