|Tests| |codecov| |PyPI version| |conda-forge version| |docs| |License: AGPL v3|
Orthority
=========
.. image:: https://raw.githubusercontent.com/leftfield-geospatial/orthority/main/docs/readme_banner.webp
:alt: banner
.. description_start
Orthority provides a command line toolkit 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. Related algorithms including RPC refinement and pan-sharpening, are also provided.
.. description_end
.. installation_start
Installation
------------
Orthority is a python 3 package that can be installed with `pip <https://pip.pypa.io/>`_ or `conda <https://docs.anaconda.com/free/miniconda/>`_.
pip
~~~
.. code-block:: bash
pip install orthority
conda
~~~~~
.. code-block:: bash
conda install -c conda-forge orthority
.. installation_end
Quick start
-----------
Command line interface
~~~~~~~~~~~~~~~~~~~~~~
.. cli_start
Orthority command line functionality is accessed with the ``oty`` command, and its sub-commands:
- ``frame``: Orthorectify images with frame camera model(s) defined by interior and exterior parameter files.
- ``exif``: Orthorectify images with frame camera model(s) defined by image EXIF / XMP tags.
- ``odm``: Orthorectify images in a processed OpenDroneMap dataset that includes a DSM.
- ``rpc``: Orthorectify images with RPC camera models defined by image tags / sidecar files or parameter files.
- ``sharpen``: Pan-sharpen an image using the Gram-Schmidt method.
Get help on ``oty`` with:
.. code-block:: bash
oty --help
and help on an ``oty`` sub-command with:
.. code-block:: bash
oty <sub-command> --help
.. cli_end
Options for configuring output images are common to all sub-commands.
.. note::
The ``simple-ortho`` command is deprecated and will be removed in future. Please switch to ``oty`` and its sub-commands.
Examples
^^^^^^^^
Orthorectify ``source.tif`` with the DEM in ``dem.tif``, and frame camera model defined by ``int_param.yaml`` and ``ext_param.geojson`` interior and exterior parameters:
.. code-block:: bash
oty frame --dem dem.tif --int-param int_param.yaml --ext-param ext_param.geojson source.tif
Orthorectify ``source.tif`` with the DEM in ``dem.tif``, and frame camera model defined by ``source.tif`` EXIF / XMP tags:
.. code-block:: bash
oty exif --dem dem.tif source.tif
As above, but the create the ortho image with ``bilinear`` interpolation, a 0.5 m pixel size and ``deflate`` compression:
.. code-block:: bash
oty exif --dem dem.tif --interp bilinear --res 0.5 --compress deflate source.tif
Orthorectify images in the OpenDroneMap dataset ``odm``, with the dataset DSM and camera models. Ortho images are placed in ``odm/orthority``.
.. code-block:: bash
oty odm --dataset-dir odm --out-dir odm/orthority
Orthorectify ``source.tif`` with the DEM in ``dem.tif``, and RPC camera model defined by ``source.tif`` tags / sidecar files:
.. code-block:: bash
oty rpc --dem dem.tif source.tif
As above, but refine the RPC camera model with GCPs in ``source.tif`` tags:
.. code-block:: bash
oty rpc --dem dem.tif --gcp-refine tags source.tif
Pan-sharpen the multispectral image ``ms.tif`` with the panchromatic image ``pan.tif``:
.. code-block:: bash
oty sharpen --pan pan.tif --multispectral ms.tif --out-file pan_sharp.tif
API
~~~
Orthorectify an image using interior and exterior parameter files to generate the camera model:
.. below copied from docs/scripts/api_ortho.py
.. code-block:: python
import orthority as oty
# URLs of required files
url_root = 'https://raw.githubusercontent.com/leftfield-geospatial/orthority/main/tests/data/'
src_file = url_root + 'ngi/3324c_2015_1004_05_0182_RGB.tif' # aerial image
dem_file = url_root + 'ngi/dem.tif' # DEM covering imaged area
int_param_file = url_root + 'io/ngi_int_param.yaml' # interior parameters
ext_param_file = url_root + 'io/ngi_xyz_opk.csv' # exterior parameters
# create a camera model for src_file from interior & exterior parameters
cameras = oty.FrameCameras(int_param_file, ext_param_file)
camera = cameras.get(src_file)
# create Ortho object and orthorectify
ortho = oty.Ortho(src_file, dem_file, camera=camera, crs=cameras.crs)
ortho.process('ortho.tif')
Pan-sharpen a multispectral image with the matching panchromatic image:
.. below copied from docs/scripts/api_pan_sharp.py
.. code-block:: python
import orthority as oty
# URLs of required files
url_root = 'https://raw.githubusercontent.com/leftfield-geospatial/orthority/main/tests/data/'
pan_file = url_root + 'pan_sharp/pan.tif' # panchromatic drone image
ms_file = url_root + 'pan_sharp/ms.tif' # multispectral (RGB) drone image
# create PanSharpen object and pan-sharpen
pan_sharp = oty.PanSharpen(pan_file, ms_file)
pan_sharp.process('pan_sharp.tif')
Documentation
-------------
See `orthority.readthedocs.io <https://orthority.readthedocs.io/>`__ for usage and reference documentation.
Contributing
------------
Contributions are welcome - the online documentation has a `guide <https://orthority.readthedocs.io/en/latest/contributing.html>`__. Please report bugs and make feature requests with the `github issue tracker <https://github.com/leftfield-geospatial/orthority/issues>`__.
Licensing
---------
Orthority is licensed under the `GNU Affero General Public License v3.0 (AGPLv3) <LICENSE>`__.
Portions of the `AGPLv3 <https://github.com/OpenDroneMap/ODM/blob/master/LICENSE>`__ licensed `OpenDroneMap software <https://github.com/OpenDroneMap/ODM>`__, and `BSD-style <https://github.com/mapillary/OpenSfM/blob/main/LICENSE>`__ licensed `OpenSfM library <https://github.com/mapillary/OpenSfM>`__ have been adapted and included in the Orthority package.
Acknowledgements
----------------
Special thanks to `Yu-Huang Wang <https://community.opendronemap.org/t/2019-04-11-tuniu-river-toufeng-miaoli-county-taiwan/3292>`__ & the `OpenDroneMap Community <https://community.opendronemap.org/>`__, `National Geo-spatial Information <https://ngi.dalrrd.gov.za/index.php/what-we-do/aerial-photography-and-imagery>`__ and the `Centre for Geographical Analysis <https://www0.sun.ac.za/cga/>`__ for sharing imagery, DEM and aero-triangulation data that form part of the package test data.
.. |Tests| image:: https://github.com/leftfield-geospatial/orthority/actions/workflows/run-unit-tests_pypi.yml/badge.svg
:target: https://github.com/leftfield-geospatial/orthority/actions/workflows/run-unit-tests_pypi.yml
.. |codecov| image:: https://codecov.io/gh/leftfield-geospatial/orthority/branch/main/graph/badge.svg?token=YPZAQS4S15
:target: https://codecov.io/gh/leftfield-geospatial/orthority
.. |PyPI version| image:: https://img.shields.io/pypi/v/orthority?color=blue
:target: https://pypi.org/project/orthority/
.. |conda-forge version| image:: https://img.shields.io/conda/vn/conda-forge/orthority.svg?color=blue
:alt: conda-forge
:target: https://anaconda.org/conda-forge/orthority
.. |docs| image:: https://readthedocs.org/projects/orthority/badge/?version=latest
:target: https://orthority.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. |License: AGPL v3| image:: https://img.shields.io/badge/License-AGPL_v3-blue.svg
:target: https://www.gnu.org/licenses/agpl-3.0
Raw data
{
"_id": null,
"home_page": null,
"name": "orthority",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "orthorectify, orthorectification, georeference, uav, drone, aerial, satellite, exif, xmp, image, rpc",
"author": "Leftfield Geospatial",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/d7/51/1e31914eeb84dc3ee3da2518f813c073c7ed4183d9b6b25cf283e34c7435/orthority-0.5.0.tar.gz",
"platform": null,
"description": "|Tests| |codecov| |PyPI version| |conda-forge version| |docs| |License: AGPL v3|\n\nOrthority\n=========\n\n.. image:: https://raw.githubusercontent.com/leftfield-geospatial/orthority/main/docs/readme_banner.webp\n :alt: banner\n\n.. description_start\n\nOrthority provides a command line toolkit 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. Related algorithms including RPC refinement and pan-sharpening, are also provided.\n\n.. description_end\n\n.. installation_start\n\nInstallation\n------------\n\nOrthority is a python 3 package that can be installed with `pip <https://pip.pypa.io/>`_ or `conda <https://docs.anaconda.com/free/miniconda/>`_.\n\npip\n~~~\n\n.. code-block:: bash\n\n pip install orthority\n\nconda\n~~~~~\n\n.. code-block:: bash\n\n conda install -c conda-forge orthority\n\n.. installation_end\n\nQuick start\n-----------\n\nCommand line interface\n~~~~~~~~~~~~~~~~~~~~~~\n\n.. cli_start\n\nOrthority command line functionality is accessed with the ``oty`` command, and its sub-commands:\n\n- ``frame``: Orthorectify images with frame camera model(s) defined by interior and exterior parameter files.\n- ``exif``: Orthorectify images with frame camera model(s) defined by image EXIF / XMP tags.\n- ``odm``: Orthorectify images in a processed OpenDroneMap dataset that includes a DSM.\n- ``rpc``: Orthorectify images with RPC camera models defined by image tags / sidecar files or parameter files.\n- ``sharpen``: Pan-sharpen an image using the Gram-Schmidt method.\n\nGet help on ``oty`` with:\n\n.. code-block:: bash\n\n oty --help\n\nand help on an ``oty`` sub-command with:\n\n.. code-block:: bash\n\n oty <sub-command> --help\n\n.. cli_end\n\nOptions for configuring output images are common to all sub-commands.\n\n.. note::\n\n The ``simple-ortho`` command is deprecated and will be removed in future. Please switch to ``oty`` and its sub-commands.\n\nExamples\n^^^^^^^^\n\nOrthorectify ``source.tif`` with the DEM in ``dem.tif``, and frame camera model defined by ``int_param.yaml`` and ``ext_param.geojson`` interior and exterior parameters:\n\n.. code-block:: bash\n\n oty frame --dem dem.tif --int-param int_param.yaml --ext-param ext_param.geojson source.tif\n\nOrthorectify ``source.tif`` with the DEM in ``dem.tif``, and frame camera model defined by ``source.tif`` EXIF / XMP tags:\n\n.. code-block:: bash\n\n oty exif --dem dem.tif source.tif\n\nAs above, but the create the ortho image with ``bilinear`` interpolation, a 0.5 m pixel size and ``deflate`` compression:\n\n.. code-block:: bash\n\n oty exif --dem dem.tif --interp bilinear --res 0.5 --compress deflate source.tif\n\nOrthorectify images in the OpenDroneMap dataset ``odm``, with the dataset DSM and camera models. Ortho images are placed in ``odm/orthority``.\n\n.. code-block:: bash\n\n oty odm --dataset-dir odm --out-dir odm/orthority\n \nOrthorectify ``source.tif`` with the DEM in ``dem.tif``, and RPC camera model defined by ``source.tif`` tags / sidecar files:\n \n.. code-block:: bash\n\n oty rpc --dem dem.tif source.tif\n\nAs above, but refine the RPC camera model with GCPs in ``source.tif`` tags:\n\n.. code-block:: bash\n\n oty rpc --dem dem.tif --gcp-refine tags source.tif\n\nPan-sharpen the multispectral image ``ms.tif`` with the panchromatic image ``pan.tif``:\n\n.. code-block:: bash\n\n oty sharpen --pan pan.tif --multispectral ms.tif --out-file pan_sharp.tif\n\n\nAPI\n~~~\n\nOrthorectify an image using interior and exterior parameter files to generate the camera model:\n\n.. below copied from docs/scripts/api_ortho.py\n\n.. code-block:: python\n\n import orthority as oty\n\n # URLs of required files\n url_root = 'https://raw.githubusercontent.com/leftfield-geospatial/orthority/main/tests/data/'\n src_file = url_root + 'ngi/3324c_2015_1004_05_0182_RGB.tif' # aerial image\n dem_file = url_root + 'ngi/dem.tif' # DEM covering imaged area\n int_param_file = url_root + 'io/ngi_int_param.yaml' # interior parameters\n ext_param_file = url_root + 'io/ngi_xyz_opk.csv' # exterior parameters\n\n # create a camera model for src_file from interior & exterior parameters\n cameras = oty.FrameCameras(int_param_file, ext_param_file)\n camera = cameras.get(src_file)\n\n # create Ortho object and orthorectify\n ortho = oty.Ortho(src_file, dem_file, camera=camera, crs=cameras.crs)\n ortho.process('ortho.tif')\n\n\nPan-sharpen a multispectral image with the matching panchromatic image:\n\n.. below copied from docs/scripts/api_pan_sharp.py\n\n.. code-block:: python\n\n import orthority as oty\n\n # URLs of required files\n url_root = 'https://raw.githubusercontent.com/leftfield-geospatial/orthority/main/tests/data/'\n pan_file = url_root + 'pan_sharp/pan.tif' # panchromatic drone image\n ms_file = url_root + 'pan_sharp/ms.tif' # multispectral (RGB) drone image\n\n # create PanSharpen object and pan-sharpen\n pan_sharp = oty.PanSharpen(pan_file, ms_file)\n pan_sharp.process('pan_sharp.tif')\n\nDocumentation\n-------------\n\nSee `orthority.readthedocs.io <https://orthority.readthedocs.io/>`__ for usage and reference documentation.\n\nContributing\n------------\n\nContributions are welcome - the online documentation has a `guide <https://orthority.readthedocs.io/en/latest/contributing.html>`__. Please report bugs and make feature requests with the `github issue tracker <https://github.com/leftfield-geospatial/orthority/issues>`__.\n\nLicensing\n---------\n\nOrthority is licensed under the `GNU Affero General Public License v3.0 (AGPLv3) <LICENSE>`__.\n\nPortions of the `AGPLv3 <https://github.com/OpenDroneMap/ODM/blob/master/LICENSE>`__ licensed `OpenDroneMap software <https://github.com/OpenDroneMap/ODM>`__, and `BSD-style <https://github.com/mapillary/OpenSfM/blob/main/LICENSE>`__ licensed `OpenSfM library <https://github.com/mapillary/OpenSfM>`__ have been adapted and included in the Orthority package.\n\nAcknowledgements\n----------------\n\nSpecial thanks to `Yu-Huang Wang <https://community.opendronemap.org/t/2019-04-11-tuniu-river-toufeng-miaoli-county-taiwan/3292>`__ & the `OpenDroneMap Community <https://community.opendronemap.org/>`__, `National Geo-spatial Information <https://ngi.dalrrd.gov.za/index.php/what-we-do/aerial-photography-and-imagery>`__ and the `Centre for Geographical Analysis <https://www0.sun.ac.za/cga/>`__ for sharing imagery, DEM and aero-triangulation data that form part of the package test data.\n\n.. |Tests| image:: https://github.com/leftfield-geospatial/orthority/actions/workflows/run-unit-tests_pypi.yml/badge.svg\n :target: https://github.com/leftfield-geospatial/orthority/actions/workflows/run-unit-tests_pypi.yml\n.. |codecov| image:: https://codecov.io/gh/leftfield-geospatial/orthority/branch/main/graph/badge.svg?token=YPZAQS4S15\n :target: https://codecov.io/gh/leftfield-geospatial/orthority\n.. |PyPI version| image:: https://img.shields.io/pypi/v/orthority?color=blue\n :target: https://pypi.org/project/orthority/\n\n.. |conda-forge version| image:: https://img.shields.io/conda/vn/conda-forge/orthority.svg?color=blue\n :alt: conda-forge\n :target: https://anaconda.org/conda-forge/orthority\n\n.. |docs| image:: https://readthedocs.org/projects/orthority/badge/?version=latest\n :target: https://orthority.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n.. |License: AGPL v3| image:: https://img.shields.io/badge/License-AGPL_v3-blue.svg\n :target: https://www.gnu.org/licenses/agpl-3.0\n",
"bugtrack_url": null,
"license": "AGPL-3.0-or-later",
"summary": "Orthorectification of drone, aerial and satellite imagery.",
"version": "0.5.0",
"project_urls": {
"Changelog": "https://github.com/leftfield-geospatial/orthority/releases",
"Documentation": "https://orthority.readthedocs.org",
"Homepage": "https://github.com/leftfield-geospatial/orthority",
"Issues": "https://github.com/leftfield-geospatial/orthority/issues",
"Source": "https://github.com/leftfield-geospatial/orthority"
},
"split_keywords": [
"orthorectify",
" orthorectification",
" georeference",
" uav",
" drone",
" aerial",
" satellite",
" exif",
" xmp",
" image",
" rpc"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d6f792833c1852972f109b00545b072e948d6729313fe083c8aee89a6cf7050e",
"md5": "2248aadff5f0c6cc26d1551f61da935b",
"sha256": "ca2d81637be75062e514ee1f7968586f5e1917a16dadf2c9961c617899984306"
},
"downloads": -1,
"filename": "orthority-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2248aadff5f0c6cc26d1551f61da935b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 94873,
"upload_time": "2024-09-15T10:56:11",
"upload_time_iso_8601": "2024-09-15T10:56:11.881916Z",
"url": "https://files.pythonhosted.org/packages/d6/f7/92833c1852972f109b00545b072e948d6729313fe083c8aee89a6cf7050e/orthority-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d7511e31914eeb84dc3ee3da2518f813c073c7ed4183d9b6b25cf283e34c7435",
"md5": "09aa3c4c61c61dde6837649030800ef1",
"sha256": "a6f77243fc3cecbee619784d97ec7d83f879f16773477d858aea8cd23629fed3"
},
"downloads": -1,
"filename": "orthority-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "09aa3c4c61c61dde6837649030800ef1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 136572,
"upload_time": "2024-09-15T10:56:13",
"upload_time_iso_8601": "2024-09-15T10:56:13.553534Z",
"url": "https://files.pythonhosted.org/packages/d7/51/1e31914eeb84dc3ee3da2518f813c073c7ed4183d9b6b25cf283e34c7435/orthority-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-15 10:56:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "leftfield-geospatial",
"github_project": "orthority",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "orthority"
}
JSON
