Skip to content

leftfield-geospatial/orthority

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Tests codecov PyPI version conda-forge Documentation Status License: AGPL v3

Orthority

banner

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.

Installation

Orthority is a python 3 package that can be installed with pip or conda.

pip

pip install orthority

conda

conda install -c conda-forge orthority

Quick start

Command line interface

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:

oty --help

and help on an oty sub-command with:

oty <sub-command> --help

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:

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:

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:

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.

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:

oty rpc --dem dem.tif source.tif

As above, but refine the RPC camera model with GCPs in source.tif tags:

oty rpc --dem dem.tif --gcp-refine tags source.tif

Pan-sharpen the multispectral image ms.tif with the panchromatic image pan.tif:

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:

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:

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 for usage and reference documentation.

Contributing

Contributions are welcome - the online documentation has a guide. Please report bugs and make feature requests with the github issue tracker.

Licensing

Orthority is licensed under the GNU Affero General Public License v3.0 (AGPLv3).

Portions of the AGPLv3 licensed OpenDroneMap software, and BSD-style licensed OpenSfM library have been adapted and included in the Orthority package.

Acknowledgements

Special thanks to Yu-Huang Wang & the OpenDroneMap Community, National Geo-spatial Information and the Centre for Geographical Analysis for sharing imagery, DEM and aero-triangulation data that form part of the package test data.