doc updates

leftfield-geospatial · May 13, 2024 · 2d830a5 · 2d830a5
1 parent 9e162fc
commit 2d830a5
Show file tree

Hide file tree

Showing 27 changed files with 97 additions and 82 deletions.
diff --git a/README.rst b/README.rst
@@ -8,7 +8,7 @@ Orthority
 
 .. description_start
 
-Orthority provides a command line interface and Python API for orthorectifying drone and aerial imagery, given a camera model and DEM. It supports common frame camera models. Camera parameters can be read from various file formats, or image EXIF / XMP tags.
+Orthority provides a command line interface and Python API for orthorectifying drone, aerial and satellite imagery, given a camera model and DEM. It supports common frame, and RPC camera models. Camera parameters can be read from various file formats, or image tags.
 
 .. description_end
 

diff --git a/docs/background/camera_models.rst b/docs/background/camera_models.rst
@@ -16,10 +16,10 @@ The *interior* component describes the relationship between :ref:`camera <backgr
 Exterior parameters
 ~~~~~~~~~~~~~~~~~~~
 
-The *exterior* component describes the relationship between :ref:`world <background/coordinates:world coordinates>` and :ref:`camera <background/coordinates:camera coordinates>` coordinates. It is an affine transform consisting of a translation and rotation.  Orthority represents exterior parameters as a :ref:`world <background/coordinates:world coordinates>` coordinate (*x*, *y*, *z*) camera position, and (*omega*, *phi*, *kappa*) camera orientation, where the (*omega*, *phi*, *kappa*) angles rotate from :ref:`camera <background/coordinates:camera coordinates>` to :ref:`world <background/coordinates:world coordinates>` coordinates.  Parameter values can be read from supported :doc:`files <../file_formats/index>`, or specified directly with the :mod:`~orthority.camera` API.
+The *exterior* component describes the relationship between :ref:`world <background/coordinates:world coordinates>` and :ref:`camera <background/coordinates:camera coordinates>` coordinates. It is an affine transform consisting of a translation and rotation.  Orthority represents exterior parameters as a world coordinate (*x*, *y*, *z*) camera position, and (*omega*, *phi*, *kappa*) camera orientation, where the (*omega*, *phi*, *kappa*) angles rotate from camera to world coordinates.  Parameter values can be read from supported :doc:`files <../file_formats/index>`, or specified directly with the :mod:`~orthority.camera` API.
 
 
 RPC cameras
 -----------
 
-The RPC (rational polynomial coefficient) camera model represents the relationship between :ref:`world <background/coordinates:world coordinates>` and :ref:`pixel <background/coordinates:pixel coordinates>` as the ratio of two polynomials.  It is a general (non-physical) model typically used for describing narrow field of view and push-broom satellite cameras.
+The RPC (rational polynomial coefficient) camera model represents the relationship between :ref:`world <background/coordinates:world coordinates>` and :ref:`pixel <background/coordinates:pixel coordinates>` coordinates as the ratio of two polynomials.  It is a general (non-physical) model typically used for describing narrow field of view and push-broom satellite cameras.
diff --git a/docs/background/dem.rst b/docs/background/dem.rst
diff --git a/docs/background/index.rst b/docs/background/index.rst
@@ -1,13 +1,12 @@
 Background
 ==========
 
-Terminology and background information relevant to command line and API users:
+Terminology and background information:
 
 .. toctree::
     :maxdepth: 1
 
     coordinates
     camera_models
-    dem
     vertical_crs
     path_uri
diff --git a/docs/background/path_uri.rst b/docs/background/path_uri.rst
@@ -1,6 +1,6 @@
 File paths and URIs
 ===================
 
-Command line and API file parameters can be specified by local file paths or remote URIs.  Orthority uses `fsspec <https://github.com/fsspec/filesystem_spec>`__ for file IO.  fsspec provides built-in support for `a number of remote file systems <https://filesystem-spec.readthedocs.io/en/stable/api.html#implementations>`__.  Support for other remote systems, including cloud storage, is available by installing `the relevant extension package <https://filesystem-spec.readthedocs.io/en/latest/api.html#other-known-implementations>`__.  See the `fsspec documentation <https://filesystem-spec.readthedocs.io/en/stable/features.html#configuration>`__ if your file system requires credentials or other configuration.
+Command line and API file parameters can be specified by local file paths or remote URIs.  Orthority uses `fsspec <https://github.com/fsspec/filesystem_spec>`__ for file IO, which provides built-in support for `a number of remote file systems <https://filesystem-spec.readthedocs.io/en/stable/api.html#implementations>`__.  Support for other remote systems, including cloud storage, is available by installing `the relevant extension package <https://filesystem-spec.readthedocs.io/en/latest/api.html#other-known-implementations>`__.  See the `fsspec documentation <https://filesystem-spec.readthedocs.io/en/stable/features.html#configuration>`__ if your file system requires credentials or other configuration.
 
 On the :doc:`command line <../cli/index>`, ``SOURCE`` images can be specified with local or remote wildcard patterns.  Note that some file systems, like HTTP, are read-only and don't support wildcards.
diff --git a/docs/background/vertical_crs.rst b/docs/background/vertical_crs.rst
@@ -1,7 +1,7 @@
 Vertical CRS
 ============
 
-DEM and :ref:`world coordinate <background/coordinates:world coordinates>` heights may have different vertical coordinate systems e.g. heights may be referenced to different datums (ellipsoid or geoid) and have different units.  Accurate orthorectification requires conversion of heights into a common system.  When both the DEM and world / ortho CRS have a defined vertical system (either as a 3D geographic CRS, or a 2D+1D compound CRS), this conversion is performed automatically. Otherwise, DEM and world vertical systems are assumed the same, and no conversion is performed.
+DEM and :ref:`world coordinate <background/coordinates:world coordinates>` heights may have different vertical coordinate systems e.g. heights may be referenced to different datums (ellipsoid or geoid) and have different units.  Accurate orthorectification requires conversion of heights into a common system.  When both the DEM and world / ortho CRS have a defined vertical system (either as a 3D CRS, or a 2D+1D compound CRS), this conversion is performed automatically. Otherwise, DEM and world vertical systems are assumed the same, and no conversion is performed.
 
 .. note::
 

diff --git a/docs/cli/simple_ortho.rst b/docs/cli/simple_ortho.rst
@@ -5,7 +5,7 @@ simple-ortho
 
 .. deprecated:: 0.3.0
 
-    The ``simple-ortho`` command is deprecated and will be removed in future.  Please switch to |oty|_ and its sub-commands.
+    The ``simple-ortho`` command is deprecated and will be removed in future.  Please switch to ``oty`` and its sub-commands.
 
 .. argparse::
     :module: orthority.cli

diff --git a/docs/conf.py b/docs/conf.py
@@ -53,6 +53,7 @@
     'rasterio': ('https://rasterio.readthedocs.io/en/stable/', None),
     'gdal': ('https://gdal.org/', None),
     'fsspec': ('https://filesystem-spec.readthedocs.io/en/latest/', None),
+    'affine': ('https://affine.readthedocs.io/en/latest/', None),
 }
 
 # -- Options for pygments -----------------------------------------------------

diff --git a/docs/file_formats/oty_int.rst b/docs/file_formats/oty_int.rst
@@ -1,7 +1,7 @@
 Orthority interior parameters
 =============================
 
-This is the native Orthority format for frame camera :ref:`interior parameters <background/camera_models:interior parameters>`.  It is a YAML file containing a nested dictionary that is based on the OpenDroneMap / OpenSfM :file:`cameras.json` format.  The root level consists of one or more camera ID keys and the corresponding parameter dictionary values.  Parameter dictionaries define parameter name - value pairs for a camera.  The basic layout is:
+This is the native Orthority format for frame camera :ref:`interior parameters <background/camera_models:interior parameters>`.  It is a YAML file containing a nested dictionary based on the OpenDroneMap / OpenSfM :file:`cameras.json` format.  The root level consists of one or more camera ID keys and the corresponding parameter dictionary values.  Parameter dictionaries define parameter name - value pairs for a camera.  The basic layout is:
 
 .. code-block:: yaml
 
@@ -38,7 +38,7 @@ Camera IDs can be used in exterior parameters to refer to a specific camera in m
     * - ``k1``, ``k2``, …
       - Optional distortion coefficients for the camera ``type``.  Values default to zero if not supplied.
 
-Available camera types and their distortion coefficients are detailed below:
+Available frame camera types and their distortion coefficients are detailed below:
 
 .. list-table::
     :widths: auto

diff --git a/docs/getting_started/api/camera.rst b/docs/getting_started/api/camera.rst
@@ -48,7 +48,7 @@ Parameter IO
 
 Internally, camera factories use the :mod:`~orthority.param_io` module to read and interpret parameter files.
 
-The ``io_kwargs`` argument can be used in :class:`~orthority.factory.FrameCameras` or :meth:`~orthority.factory.FrameCameras.from_images` to pass keyword arguments to the :class:`~orthority.param_io.FrameReader` sub-class corresponding to the exterior (and possibly interior) parameter file format.
+The ``io_kwargs`` argument can be used in :class:`~orthority.factory.FrameCameras` or :meth:`~orthority.factory.FrameCameras.from_images` to pass keyword arguments to the :class:`~orthority.param_io.FrameReader` sub-class corresponding to the exterior parameter file format.
 
 E.g. to create a factory from image EXIF / XMP tags and pass an explicit world / ortho CRS to :class:`~orthority.param_io.ExifReader`:
 
@@ -97,6 +97,18 @@ Camera models can also be created from :doc:`image RPC tags / sidecar files <../
     :start-after: [create tag]
     :end-before: [end create tag]
 
+Parameter IO
+~~~~~~~~~~~~
+
+The ``io_kwargs`` argument can be used in :meth:`~orthority.factory.RpcCameras.from_images` to pass keyword arguments to :meth:`~orthority.param_io.read_im_rpc_param`.
+
+E.g. to display a progress bar while reading image RPC tags / sidecar files:
+
+.. literalinclude:: ../../scripts/api_rpc.py
+    :language: python
+    :start-after: [io_kwargs]
+    :end-before: [end io_kwargs]
+
 Camera options
 ~~~~~~~~~~~~~~
 

diff --git a/docs/getting_started/api/index.rst b/docs/getting_started/api/index.rst
@@ -17,7 +17,7 @@ Or, with conda_:
 
 .. note::
 
-    If you're using the Orthority and Rasterio_ packages together, Orthority should be imported first.
+    If you're using the Orthority and Rasterio_ packages together, Orthority should be imported first to configure the PROJ setting for :doc:`vertical CRS transformations <../../background/vertical_crs>`.
 
 .. toctree::
     :maxdepth: 1

diff --git a/docs/getting_started/cli/algorithm_config.rst b/docs/getting_started/cli/algorithm_config.rst
@@ -1,4 +1,4 @@
-.. include:: ../../shared.txt
+.. include:: shared.txt
 
 Algorithm configuration
 =======================
@@ -13,5 +13,5 @@ Interpolation methods for remapping the source image and reprojecting the DEM ar
 
 .. code-block:: bash
 
-    oty odm --dataset-dir odm --interp lanczos --dem-interp lanczos --per-band --overwrite
+    oty odm --dataset-dir odm --interp lanczos --dem-interp lanczos --per-band
 
diff --git a/docs/getting_started/cli/basic_orthorectification.rst b/docs/getting_started/cli/basic_orthorectification.rst
@@ -1,4 +1,5 @@
 .. include:: ../../shared.txt
+.. include:: shared.txt
 
 Basic orthorectification
 ========================
@@ -8,7 +9,7 @@ Basic orthorectification
 ``oty frame``
 -------------
 
-|oty frame|_ uses interior and exterior parameter files to specify :ref:`frame camera models <background/camera_models:frame cameras>`.  Here we orthorectify `NGI <https://ngi.dalrrd.gov.za/index.php/what-we-do/aerial-photography-and-imagery>`__ aerial images using the associated DEM, :doc:`Orthority format <../../file_formats/oty_int>` interior parameters, and :doc:`CSV format <../../file_formats/csv>` exterior parameters.  Ortho images are placed in the current directory:
+|oty frame|_ uses interior and exterior parameter files to specify :ref:`frame camera models <background/camera_models:frame cameras>`.  Here we orthorectify NGI_ aerial images using the associated DEM, :doc:`Orthority format <../../file_formats/oty_int>` interior parameters, and :doc:`CSV format <../../file_formats/csv>` exterior parameters.  Ortho images are placed in the current directory:
 
 .. code-block:: bash
 
@@ -24,20 +25,22 @@ In order of priority, the world / ortho CRS is read from:
     * :doc:`CSV format <../../file_formats/csv>` with ``latitude``, ``longitude``, ``altitude``, ``roll``, ``pitch`` & ``yaw`` fields.
 #. Source image CRS metadata, if any.
 
-In the first example, the world / ortho CRS is read from the CSV file's :file:`.prj` sidecar file.
+In the first example, the world / ortho CRS is read from exterior parameters in CSV format with ``x``, ``y`` & ``z`` fields and a  :file:`.prj` sidecar file.
 
-The next example orthorectifies drone images with `OpenDroneMap <https://github.com/OpenDroneMap/ODM>`__ generated DEM and interior parameters.  Exterior parameters are in CSV format with ``x``, ``y`` & ``z`` fields, but no :file:`.prj` sidecar file.  The world / ortho CRS cannot be read from the input files, so it is specified with :option:`--crs <oty-frame --crs>`:
+In the next example, exterior parameters are in CSV format with ``x``, ``y`` & ``z`` fields, but no :file:`.prj` sidecar file.  The world / ortho CRS cannot be read from the input files, so it is specified with :option:`--crs <oty-frame --crs>`:
 
 .. code-block:: bash
 
     oty frame --dem odm/odm_dem/dsm.tif --int-param odm/opensfm/reconstruction.json --ext-param io/odm_xyz_opk.csv --crs EPSG:32651 odm/images/*.tif
 
-See the :doc:`file format documentation <../../file_formats/index>` for details on supported frame camera parameter formats.
+.. note::
+
+    See the :doc:`file format documentation <../../file_formats/index>` for supported parameter formats.
 
 ``oty exif``
 ------------
 
-Frame camera models can be derived from image EXIF / XMP tags with |oty exif|_.  The :doc:`EXIF / XMP documentation <../../file_formats/exif_xmp>` describes the required tags.  This example orthorectifies drone imagery using an `OpenDroneMap <https://github.com/OpenDroneMap/ODM>`__ generated DSM.  Ortho images are placed in the current directory:
+Frame camera models can be derived from image EXIF / XMP tags with |oty exif|_.  The :doc:`EXIF / XMP documentation <../../file_formats/exif_xmp>` describes the required tags.  This example orthorectifies drone imagery using an OpenDroneMap generated DSM.  Ortho images are placed in the current directory:
 
 .. code-block:: bash
 
@@ -51,7 +54,7 @@ The world / ortho CRS defaults to a UTM CRS whose zone covers the camera positio
 
 .. note::
 
-    EXIF / XMP tag values typically contain inaccuracies that can result in distortion and positioning errors in the ortho images.  This is a general limitation of this approach.
+    EXIF / XMP tag values typically contain inaccuracies that can result in distortion and positioning errors in the ortho images.  This is the case with the Orthority test data, and a general limitation of this approach.
 
 ``oty odm``
 -----------

diff --git a/docs/getting_started/cli/camera_config.rst b/docs/getting_started/cli/camera_config.rst
@@ -1,4 +1,4 @@
-.. include:: ../../shared.txt
+.. include:: shared.txt
 
 Frame camera configuration
 ==========================
@@ -15,7 +15,7 @@ To show the use of these options, we orthorectify the OpenDroneMap dataset using
 
 .. code-block:: bash
 
-    oty odm --dataset-dir odm --no-full-remap --alpha 0 --overwrite
+    oty odm --dataset-dir odm --no-full-remap --alpha 0
 
 .. note::
 

diff --git a/docs/getting_started/cli/index.rst b/docs/getting_started/cli/index.rst
@@ -1,4 +1,4 @@
-.. include:: ../../shared.txt
+.. include:: shared.txt
 
 Command line
 ============

diff --git a/docs/getting_started/cli/model_export.rst b/docs/getting_started/cli/model_export.rst
@@ -1,12 +1,12 @@
-.. include:: ../../shared.txt
+.. include:: shared.txt
 
 Camera model export
 ===================
 
-:doc:`Camera models <../../background/camera_models>` can be exported to Orthority format files by supplying the ``--export-params`` option to any of the |oty|_ orthorectification sub-commands.  When ``--export-params`` is supplied, the command exits after exporting, and no orthorectification is performed.  This example exports camera models derived from drone image EXIF / XMP tags.  Exported files are placed in the current directory:
+:doc:`Camera models <../../background/camera_models>` can be exported to Orthority format files by supplying the ``--export-params`` option to any of the |oty|_ orthorectification sub-commands.  When ``--export-params`` is supplied, the command exits after exporting, and no orthorectification is performed.  This example exports camera models derived from drone image EXIF / XMP tags:
 
 .. code-block:: bash
 
     oty exif --export-params odm/images/*.tif
 
-``--out-dir`` can be used to change the output directory, and ``--overwrite`` to replace existing files.
+The default output directory is specific to the |oty|_ sub-command. It can be changed with ``--out-dir``, and existing files replaced with ``--overwrite``.
diff --git a/docs/getting_started/cli/ortho_config.rst b/docs/getting_started/cli/ortho_config.rst
@@ -1,3 +1,4 @@
+.. include:: shared.txt
 .. include:: ../../shared.txt
 
 Ortho image configuration
@@ -17,13 +18,13 @@ The next example orthorectifies using EXIF / XMP tags, and configures the ortho
 
 .. code-block:: bash
 
-    oty exif --dem odm/odm_dem/dsm.tif --res 0.2 --dtype uint8 --compress deflate --overwrite odm/images/100_0005_0140.tif
+    oty exif --dem odm/odm_dem/dsm.tif --res 0.2 --dtype uint8 --compress deflate odm/images/100_0005_0140.tif
 
 Valid ortho pixels are masked with either an internal mask band or a nodata value.  By default, an internal mask is used when the ortho image is ``jpeg`` compressed.  This avoids ``jpeg`` artefacts in invalid areas.  When the ortho is ``deflate`` compressed, the default is use to a nodata value based on the data type.  Masking behaviour can be changed with ``--write-mask`` to write an internal mask, or ``--no-write-mask`` to use a nodata value.
 
 Internal overviews are added by default.  This can be changed with ``--no-build-ovw``.  In this example, we create an ortho image with ``deflate`` compression, nodata rather than internal masking, and no internal overviews:
 
 .. code-block:: bash
 
-    oty exif --dem odm/odm_dem/dsm.tif --compress deflate --no-write-mask --no-build-ovw --overwrite odm/images/100_0005_0140.tif
+    oty exif --dem odm/odm_dem/dsm.tif --compress deflate --no-write-mask --no-build-ovw odm/images/100_0005_0140.tif
 
diff --git a/docs/getting_started/cli/shared.txt b/docs/getting_started/cli/shared.txt
@@ -0,0 +1,14 @@
+.. |oty| replace:: ``oty``
+.. _oty: ../../cli/oty.html
+
+.. |oty frame| replace:: ``oty frame``
+.. _oty frame: ../../cli/frame.html
+
+.. |oty exif| replace:: ``oty exif``
+.. _oty exif: ../../cli/exif.html
+
+.. |oty odm| replace:: ``oty odm``
+.. _oty odm: ../../cli/odm.html
+
+.. |oty rpc| replace:: ``oty rpc``
+.. _oty rpc: ../../cli/rpc.html
diff --git a/docs/scripts/api_rpc.py b/docs/scripts/api_rpc.py
@@ -20,6 +20,11 @@
 camera = cameras.get(src_file)
 # [end create tag]
 
+# [io_kwargs]
+io_kwargs = dict(progress=True)
+cameras = oty.RpcCameras.from_images((src_file,), io_kwargs=io_kwargs)
+# [end io_kwargs]
+
 # [cam_kwargs]
 cam_kwargs = dict(crs='EPSG:32735')
 cameras = oty.RpcCameras.from_images((src_file,), cam_kwargs=cam_kwargs)

diff --git a/docs/shared.txt b/docs/shared.txt
@@ -1,18 +1,3 @@
-.. |oty| replace:: ``oty``
-.. _oty: ../../cli/oty.html
-
-.. |oty frame| replace:: ``oty frame``
-.. _oty frame: ../../cli/frame.html
-
-.. |oty exif| replace:: ``oty exif``
-.. _oty exif: ../../cli/exif.html
-
-.. |oty odm| replace:: ``oty odm``
-.. _oty odm: ../../cli/odm.html
-
-.. |oty rpc| replace:: ``oty rpc``
-.. _oty rpc: ../../cli/rpc.html
-
 .. _NGI: https://ngi.dalrrd.gov.za/index.php/what-we-do/aerial-photography-and-imagery
 .. _Rasterio: https://rasterio.readthedocs.io
 .. _GDAL: https://gdal.org