From 2d830a50b7e26ed2c2d78978573a01dbf21e8753 Mon Sep 17 00:00:00 2001 From: Dugal Harris Date: Mon, 13 May 2024 18:36:51 +0200 Subject: [PATCH] doc updates --- README.rst | 2 +- docs/background/camera_models.rst | 4 ++-- docs/background/dem.rst | 4 ---- docs/background/index.rst | 3 +-- docs/background/path_uri.rst | 2 +- docs/background/vertical_crs.rst | 2 +- docs/cli/simple_ortho.rst | 2 +- docs/conf.py | 1 + docs/file_formats/oty_int.rst | 4 ++-- docs/getting_started/api/camera.rst | 14 ++++++++++++- docs/getting_started/api/index.rst | 2 +- docs/getting_started/cli/algorithm_config.rst | 4 ++-- .../cli/basic_orthorectification.rst | 15 ++++++++------ docs/getting_started/cli/camera_config.rst | 4 ++-- docs/getting_started/cli/index.rst | 2 +- docs/getting_started/cli/model_export.rst | 6 +++--- docs/getting_started/cli/ortho_config.rst | 5 +++-- docs/getting_started/cli/shared.txt | 14 +++++++++++++ docs/scripts/api_rpc.py | 5 +++++ docs/shared.txt | 15 -------------- orthority/camera.py | 6 +++--- orthority/cli.py | 4 ++-- orthority/errors.py | 2 +- orthority/factory.py | 16 +++++++-------- orthority/ortho.py | 19 +++++++++--------- orthority/param_io.py | 20 +++++++++---------- tests/conftest.py | 2 +- 27 files changed, 97 insertions(+), 82 deletions(-) delete mode 100644 docs/background/dem.rst create mode 100644 docs/getting_started/cli/shared.txt diff --git a/README.rst b/README.rst index f253ca3..df4bb1d 100644 --- 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 index 8abae44..d71b311 100644 --- 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 ` and :ref:`camera ` coordinates. It is an affine transform consisting of a translation and rotation. Orthority represents exterior parameters as a :ref:`world ` coordinate (*x*, *y*, *z*) camera position, and (*omega*, *phi*, *kappa*) camera orientation, where the (*omega*, *phi*, *kappa*) angles rotate from :ref:`camera ` to :ref:`world ` 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 ` and :ref:`camera ` 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 ` and :ref:`pixel ` 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 ` and :ref:`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. diff --git a/docs/background/dem.rst b/docs/background/dem.rst deleted file mode 100644 index c7b8ff8..0000000 --- a/docs/background/dem.rst +++ /dev/null @@ -1,4 +0,0 @@ -DEM -=== - -The DEM used for orthorectification should be a raster in a `GDAL supported format `__ with height units and datum as defined by its :doc:`vertical CRS `. When no vertical CRS is defined, DEM heights are assumed to be in the same vertical system as the :ref:`world coordinate ` *z* axis. For best results, DEM heights should include vegetation and buildings i.e. the DEM should be a digital surface model (DSM). While there are no requirements for the DEM resolution and CRS, higher DEM resolutions generally produce more accurate ortho images, and orthorectification is faster when DEM and world / ortho CRS are the same. diff --git a/docs/background/index.rst b/docs/background/index.rst index 53660ee..16f9413 100644 --- 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 index b351b30..14588f3 100644 --- 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 `__ for file IO. fsspec provides built-in support for `a number of remote file systems `__. Support for other remote systems, including cloud storage, is available by installing `the relevant extension package `__. See the `fsspec documentation `__ 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 `__ for file IO, which provides built-in support for `a number of remote file systems `__. Support for other remote systems, including cloud storage, is available by installing `the relevant extension package `__. See the `fsspec documentation `__ 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 index 7dc5bc2..beede77 100644 --- a/docs/background/vertical_crs.rst +++ b/docs/background/vertical_crs.rst @@ -1,7 +1,7 @@ Vertical CRS ============ -DEM and :ref:`world coordinate ` 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 ` 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 index 2164eee..5cc292b 100644 --- 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 index 9fa1bf2..84b6140 100644 --- 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 index b74492f..f8b712f 100644 --- 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 `. 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 `. 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 index 31b8ce2..7a869cc 100644 --- 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 index 3251b66..4c88ff7 100644 --- 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 index 4555b4c..9360bce 100644 --- 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 index 0d8dcaf..15f1105 100644 --- 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 `. 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: +|oty frame|_ uses interior and exterior parameter files to specify :ref:`frame camera models `. 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 `__ 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 `: +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 `: .. 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 `__ 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 index c58f7f9..0d1d0f2 100644 --- 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 index 394a2f1..395d8db 100644 --- 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 index eb8d13c..6e5699e 100644 --- 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 index 3507fc7..5531c73 100644 --- 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,7 +18,7 @@ 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. @@ -25,5 +26,5 @@ Internal overviews are added by default. This can be changed with ``--no-build- .. 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 new file mode 100644 index 0000000..41e8b96 --- /dev/null +++ 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 index 1f7eec0..32ffc07 100644 --- 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 index f47a0f1..75eea0f 100644 --- 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 diff --git a/orthority/camera.py b/orthority/camera.py index 139c179..2bfc4e5 100644 --- a/orthority/camera.py +++ b/orthority/camera.py @@ -346,7 +346,7 @@ def remap( coordinate pixels are mapped to ``nodata``. :param nodata: Value to use for masking invalid pixels in the remapped image. If set to None (the - default), a value based on the ``image`` data type is chosen automatically. + default), a value based on the ``im_array`` data type is chosen automatically. :param interp: Interpolation method to use for remapping. :param kwargs: @@ -1078,12 +1078,12 @@ def remap( coordinate pixels are mapped to ``nodata``. :param nodata: Value to use for masking invalid pixels in the remapped image. If set to None (the - default), a value based on the ``image`` data type is chosen automatically. + default), a value based on the ``im_array`` data type is chosen automatically. :param interp: Interpolation method to use for remapping. :param kernel_size: Kernel (width, height) size in pixels, used for dilating the nodata mask. Removes - blurring of boundary pixels with nodata areas in an undistorted ``image``. Not used + blurring of boundary pixels with nodata areas in an undistorted ``im_array``. Not used if blurring could not have occurred (e.g. if :attr:`~FrameCamera.distort` is True). :return: diff --git a/orthority/cli.py b/orthority/cli.py index a2bda2a..4371198 100644 --- a/orthority/cli.py +++ b/orthority/cli.py @@ -166,7 +166,7 @@ def _crs_cb(ctx: click.Context, param: click.Parameter, crs: str): def _src_files_cb( ctx: click.Context, param: click.Parameter, src_files: Sequence[str] ) -> Sequence[OpenFile]: - """Click callback to form a list of source file OpenFile instances. ``src_files`` can be a + """Click callback to form a list of source image OpenFile instances. ``src_files`` can be a list of file paths / URIs, or a list of path / URI glob patterns. """ if not src_files or len(src_files) == 0: @@ -176,7 +176,7 @@ def _src_files_cb( except Exception as ex: raise click.BadParameter(str(ex), param=param) if len(src_files) == 0: - raise click.BadParameter('No source file(s) found.', param=param) + raise click.BadParameter('No source image(s) found.', param=param) return src_files diff --git a/orthority/errors.py b/orthority/errors.py index 6d68bc7..01fa169 100644 --- a/orthority/errors.py +++ b/orthority/errors.py @@ -31,7 +31,7 @@ class CrsMissingError(OrthorityError): class CameraInitError(OrthorityError): - """Raised when a camera's exterior parameters have not been initialised.""" + """Raised when a camera's parameters have not been initialised.""" class OrthorityWarning(RuntimeWarning): diff --git a/orthority/factory.py b/orthority/factory.py index 37e7ca6..765f210 100644 --- a/orthority/factory.py +++ b/orthority/factory.py @@ -39,7 +39,7 @@ def __init__(self, **kwargs): @property @abstractmethod def filenames(self) -> set[str]: - """Filenames for which there are cameras.""" + """Set of filenames that have cameras.""" pass @abstractmethod @@ -81,12 +81,12 @@ class FrameCameras(Cameras): Exterior parameter file or dictionary. If a file, can be a path or URI string, an :class:`~fsspec.core.OpenFile` object or a file object, opened in text mode ('rt'). :param io_kwargs: - Optional dictionary of keyword arguments for the - :class:`~orthority.param_io.FrameReader` sub-class corresponding to the exterior (and - possibly interior) parameter file format. Should exclude ``ext_param`` or ``int_param`` - file names, which are passed internally. If ``ext_param`` is a dictionary, - these arguments are not passed to the :class:`~orthority.param_io.FrameReader` sub-class, - but :attr:`FrameCameras.crs` is set with the value of a 'crs' argument. + Optional dictionary of keyword arguments for the :class:`~orthority.param_io.FrameReader` + sub-class corresponding to the exterior parameter file format. Should exclude + ``ext_param`` or ``int_param`` file names, which are passed internally. If ``ext_param`` + is a dictionary, these arguments are not passed to the + :class:`~orthority.param_io.FrameReader` sub-class, but :attr:`FrameCameras.crs` is set + with the value of a ``crs`` argument. :param cam_kwargs: Optional dictionary of keyword arguments for the :class:`~orthority.camera.FrameCamera` class. Should exclude interior and exterior @@ -290,7 +290,7 @@ def from_images( :class:`~orthority.param_io.read_im_rpc_param`. Should exclude ``files`` which is passed internally. :param cam_kwargs: - Optional dictionary of additional arguments for the :class:`~orthority.camera.RpcCamera` + Optional dictionary of keyword arguments for the :class:`~orthority.camera.RpcCamera` class. Should exclude ``im_size`` and ``rpc`` which are passed internally. """ io_kwargs = io_kwargs or {} diff --git a/orthority/ortho.py b/orthority/ortho.py index e2abf61..61e25f7 100644 --- a/orthority/ortho.py +++ b/orthority/ortho.py @@ -56,12 +56,12 @@ class Ortho: Source image to be orthorectified. Can be a path or URI string, an :class:`~fsspec.core.OpenFile` object in binary mode ('rb'), or a dataset reader. :param dem_file: - DEM image covering the source image. Can be a path or URI string, + DEM file covering the source image. Can be a path or URI string, an :class:`~fsspec.core.OpenFile` object in binary mode ('rb'), or a dataset reader. :param camera: Source image camera model. :param crs: - CRS of the ``camera`` world coordinates and ortho image as an EPSG, proj4 or WKT string, + CRS of the ``camera`` world coordinates, and ortho image, as an EPSG, proj4 or WKT string, or :class:`~rasterio.crs.CRS` object. If set to None (the default), the CRS will be read from the source image if possible. If the source image is not projected in the world / ortho CRS, ``crs`` should be supplied. @@ -599,9 +599,9 @@ def process( The source image is read and processed band-by-band, or all bands at once, depending on the value of ``per_band``. If necessary, the portion of the DEM stored internally is - reprojected to the ortho CRS and resolution. Using the camera model and DEM, the ortho - image is remapped from the source image tile-by-tile. Up to N ortho tiles are processed - concurrently, where N is the number of CPUs. + reprojected to the world / ortho CRS and ortho resolution. Using the camera model and + DEM, the ortho image is remapped from the source image tile-by-tile. Up to N ortho tiles + are processed concurrently, where N is the number of CPUs. .. note:: @@ -611,11 +611,10 @@ def process( Ortho image file to create. Can be a path or URI string, or an :class:`~fsspec.core.OpenFile` object in binary mode ('wb'). :param resolution: - Ortho image pixel (x, y) size in units of the world / ortho CRS (usually meters). If - set to None (the default), an approximate ground sampling distance is used as the - resolution. + Ortho image pixel (x, y) size in units of the world / ortho CRS. If set to None (the + default), an approximate ground sampling distance is used as the resolution. :param interp: - Interpolation method to use for remapping the source to ortho image. + Interpolation method for remapping the source to ortho image. :param dem_interp: Interpolation method for reprojecting the DEM. :param per_band: @@ -624,7 +623,7 @@ def process( :param write_mask: Mask valid ortho pixels with an internal mask (True), or with a nodata value based on ``dtype`` (False). An internal mask helps remove nodata noise caused by lossy - compression. If set to None (the default), the mask will be written when jpeg + compression. If set to None (the default), the mask will be written when JPEG compression is used. :param dtype: Ortho image data type ('uint8', 'uint16', 'float32' or 'float64'). If set to None ( diff --git a/orthority/param_io.py b/orthority/param_io.py index 18d02b9..ccf6682 100644 --- a/orthority/param_io.py +++ b/orthority/param_io.py @@ -208,7 +208,7 @@ def _read_exif_ext_param( def read_oty_int_param(file: str | PathLike | OpenFile | IO[str]) -> dict[str, dict[str, Any]]: """ - Read interior parameters for one or more camera from an :doc:`Orthority interior parameter + Read interior parameters for one or more cameras from an :doc:`Orthority interior parameter file <../file_formats/oty_int>`. :param file: @@ -273,7 +273,7 @@ def parse_yaml_param(yaml_param: dict, cam_id: str = None) -> dict[str, Any]: def read_osfm_int_param(file: str | PathLike | OpenFile | IO[str]) -> dict[str, dict[str, Any]]: """ - Read interior parameters for one or more camera, from an OpenDroneMap :file:`cameras.json` or + Read interior parameters for one or more cameras, from an OpenDroneMap :file:`cameras.json` or OpenSfM :file:`reconstruction.json` file. See the :doc:`format documentation <../file_formats/opensfm>` for supported camera models. @@ -358,7 +358,7 @@ def _read_im_rpc_param( def read_oty_rpc_param(file: str | PathLike | OpenFile | IO[str]) -> dict[str, dict[str, Any]]: """ - Read RPC parameters for one or more camera from an :doc:`Orthority RPC file + Read RPC parameters for one or more cameras from an :doc:`Orthority RPC file <../file_formats/oty_rpc>`. :param file: @@ -647,7 +647,7 @@ def _rpy_to_opk( class FrameReader(ABC): """ - Base frame camera parameter reader class. + Base frame camera parameter reader. :param crs: CRS of the world coordinate system as an EPSG, WKT or proj4 string; or @@ -708,12 +708,12 @@ class CsvReader(FrameReader): :param crs: CRS of the world coordinate system as an EPSG, WKT or proj4 string; or :class:`~rasterio.crs.CRS` object. If set to None (the default), and the file contains - (x, y, z) world coordinate positions, a CRS can be provided via a '.prj' sidecar file - (i.e. a text file defining a CRS string, and having the same path as ``file``, - but a '.prj' extension). If set to None, and the file contains (``latitude``, - ``longitude``, ``altitude``) **and** (``roll``, ``pitch``, ``yaw``) fields, a UTM CRS - will be auto-determined. If the file contains (``latitude``, ``longitude``, ``altitude``) - **or** (``roll``, ``pitch``, ``yaw``) fields, ``crs`` should be supplied. + (x, y, z) world coordinate positions, a CRS can be provided via a :file:`.prj` sidecar + file (i.e. a text file defining a CRS string, and having the same path as ``file``, + but a :file:`.prj` extension). If set to None, and the file contains (latitude, + longitude, altitude) **and** (roll, pitch, yaw) fields, a UTM CRS will be + auto-determined. If the file contains (latitude, longitude, altitude) **or** (roll, + pitch, yaw) fields (but not both), ``crs`` should be supplied. :param lla_crs: Geographic CRS associated with any (latitude, longitude, altitude) position and/or (roll, pitch, yaw) values in the file (as an EPSG, WKT or proj4 string; or diff --git a/tests/conftest.py b/tests/conftest.py index 0770914..02f1389 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -71,7 +71,7 @@ def sinusoid(shape: tuple[int, int]) -> np.ndarray: def ortho_bounds(camera: Camera, z: float = Ortho._egm_minmax[0]) -> tuple: - """Return (left, bottom, right, top) ortho bounds for the given ``camera`` at z=``z``.""" + """Return (left, bottom, right, top) ortho bounds for the given ``camera`` at ``z``.""" w, h = np.array(camera.im_size) - 1 ji = np.array( [[0, 0], [w / 2, 0], [w, 0], [w, h / 2], [w, h], [w / 2, h], [0, h], [0, h / 2]]