|Tests| |codecov| |PyPI version| |conda-forge version| |docs| |License: AGPL v3|
homonim
=======
.. image:: https://raw.githubusercontent.com/leftfield-geospatial/homonim/main/docs/readme_eg.webp
:alt: example
.. short_descr_start
Correct aerial and satellite imagery to surface reflectance.
.. short_descr_end
.. description_start
Description
-----------
``homonim`` provides a command line interface and API for correcting remotely sensed imagery to approximate surface reflectance. It implements a form of *spectral harmonisation*, that adjusts for spatially varying atmospheric and anisotropic (BRDF) effects, by *fusion* with satellite surface reflectance data. Manual reflectance measurements and target placements are not required.
``homonim`` is useful for pre-processing in quantitative mapping applications, and for reducing seamlines and other visual artefacts in image mosaics. It can be applied to multi-spectral drone, aerial and satellite imagery. The consistency of multi-temporal and multi-sensor data can improved through its use.
.. description_end
See the documentation site for more detail: https://homonim.readthedocs.io/.
.. install_start
Installation
------------
``homonim`` is available as a python 3 package, via `pip <https://pip.pypa.io/>`_ or `conda <https://docs.conda.io/projects/miniconda>`_.
pip
~~~
.. code:: shell
pip install homonim
conda
~~~~~
.. code:: shell
conda install -c conda-forge homonim
.. install_end
Getting started
---------------
Command line interface
~~~~~~~~~~~~~~~~~~~~~~
.. cli_start
``homonim`` command line functionality is accessed through the commands:
- ``fuse``: Correct image(s) to surface reflectance.
- ``compare``: Compare image(s) with a reference.
- ``stats``: Report parameter statistics.
Get help on ``homonim`` with:
.. code:: shell
homonim --help
and help on a ``homonim`` command with:
.. code:: shell
homonim <command> --help
.. cli_end
Examples
^^^^^^^^
Correct *source.tif* to surface reflectance by fusion with *reference.tif*, using the default settings:
.. code:: shell
homonim fuse source.tif reference.tif
Correct images matching *source\*.tif* to surface reflectance by fusion with *reference.tif*. Use a 5 x 5 pixel kernel and the ``gain-blk-offset`` model for correction, and place corrected images in the *./corrected* directory:
.. code:: shell
homonim fuse -k 5 5 -m gain-blk-offset -od ./corrected source*.tif reference.tif
Statistically compare *source.tif* and *corrected.tif* with *reference.tif*.
.. code:: shell
homonim compare source.tif corrected.tif reference.tif
API
~~~
Example
^^^^^^^
Surface reflectance correction of an aerial image using a Sentinel-2 reference.
.. comment
The code below is copied from docs/examples/api_example and # [*] comments removed
.. api_example_start
.. code:: python
from pathlib import Path
from homonim import RasterFuse, RasterCompare, Model
# urls of source and reference test images
src_file = (
'https://raw.githubusercontent.com/leftfield-geospatial/homonim/main/'
'tests/data/source/ngi_rgb_byte_1.tif'
)
ref_file = (
'https://raw.githubusercontent.com/leftfield-geospatial/homonim/main/'
'tests/data/reference/sentinel2_b432_byte.tif'
)
# path to corrected file to create
corr_file = './corrected.tif'
# Correct src_file to surface reflectance by fusion with ref_file, using the
# `gain-blk-offset` model and a kernel of 5 x 5 pixels.
with RasterFuse(src_file, ref_file) as fuse:
fuse.process(corr_file, Model.gain_blk_offset, (5, 5), overwrite=True)
.. api_example_end
Reference imagery
~~~~~~~~~~~~~~~~~
`geedim <https://github.com/leftfield-geospatial/geedim>`_ can be used as a companion tool for searching and downloading cloud-free reference imagery. Alternatively, satellite imagery is available from a number of sources, including the `Google <https://developers.google.com/earth-engine/datasets>`_, `Amazon <https://aws.amazon.com/earth/>`_ and `Microsoft <https://planetarycomputer.microsoft.com/catalog>`_ repositories.
Usage
-----
See the documentation `here <https://homonim.readthedocs.io/>`_.
Terminology
-----------
``homonim`` is shorthand for *homogenise image* and is a reference to `the paper <https://www.researchgate.net/publication/328317307_Radiometric_homogenisation_of_aerial_images_by_calibrating_with_satellite_data>`_ on which it is based.
Credits
-------
``homonim`` relies on these excellent packages:
- `rasterio <https://github.com/rasterio/rasterio>`__
- `opencv <https://github.com/opencv/opencv>`__
- `numpy <https://github.com/numpy/numpy>`__
License
-------
``homonim`` is licensed under the terms of the `AGPLv3 <https://www.gnu.org/licenses/agpl-3.0.en.html>`__. This project is developed in collaboration with `InnovUS <https://www.innovus.co.za/>`__ at Stellenbosch University, alternative licenses can be arranged by `contacting <mailto:madeleink@sun.ac.za>`__ them.
Citation
--------
Please cite use of the code as:
- Dugal Harris & Adriaan Van Niekerk (2019) Radiometric homogenisation of aerial images by calibrating with satellite data, *International Journal of Remote Sensing*, **40:7**, 2623-2647, DOI: https://doi.org/10.1080/01431161.2018.1528404.
Bibtex::
@article{doi:10.1080/01431161.2018.1528404,
author = {Dugal Harris and Adriaan Van Niekerk},
title = {Radiometric homogenisation of aerial images by calibrating with satellite data},
journal = {International Journal of Remote Sensing},
volume = {40},
number = {7},
pages = {2623-2647},
year = {2019},
publisher = {Taylor & Francis},
doi = {10.1080/01431161.2018.1528404},
URL = {https://doi.org/10.1080/01431161.2018.1528404},
}
.. |Tests| image:: https://github.com/leftfield-geospatial/homonim/actions/workflows/run-unit-tests.yml/badge.svg
:target: https://github.com/leftfield-geospatial/homonim/actions/workflows/run-unit-tests.yml
.. |codecov| image:: https://codecov.io/gh/leftfield-geospatial/homonim/branch/main/graph/badge.svg?token=A01698K96C
:target: https://codecov.io/gh/leftfield-geospatial/homonim
.. |License: AGPL v3| image:: https://img.shields.io/badge/License-AGPL_v3-blue.svg
:target: https://www.gnu.org/licenses/agpl-3.0
.. |PyPI version| image:: https://img.shields.io/pypi/v/homonim?color=blue
:target: https://pypi.org/project/homonim/
.. |conda-forge version| image:: https://img.shields.io/conda/vn/conda-forge/homonim.svg?color=blue
:alt: conda-forge
:target: https://anaconda.org/conda-forge/homonim
.. |docs| image:: https://readthedocs.org/projects/homonim/badge/?version=latest
:target: https://homonim.readthedocs.io/en/latest/?badge=latest
Raw data
{
"_id": null,
"home_page": "",
"name": "homonim",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "drone,aerial,satellite,image,surface reflectance,correction,harmonization,anisotropy,brdf,atmospheric correction",
"author": "Leftfield Geospatial",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/b0/30/4f80d397ac967666ad1e39e169611df8b4f794db7939d6e7197ae422250d/homonim-0.4.0.tar.gz",
"platform": null,
"description": "|Tests| |codecov| |PyPI version| |conda-forge version| |docs| |License: AGPL v3|\n\nhomonim\n=======\n\n.. image:: https://raw.githubusercontent.com/leftfield-geospatial/homonim/main/docs/readme_eg.webp\n :alt: example\n\n\n.. short_descr_start\n\nCorrect aerial and satellite imagery to surface reflectance.\n\n.. short_descr_end\n.. description_start\n\nDescription\n-----------\n\n``homonim`` provides a command line interface and API for correcting remotely sensed imagery to approximate surface reflectance. It implements a form of *spectral harmonisation*, that adjusts for spatially varying atmospheric and anisotropic (BRDF) effects, by *fusion* with satellite surface reflectance data. Manual reflectance measurements and target placements are not required.\n\n``homonim`` is useful for pre-processing in quantitative mapping applications, and for reducing seamlines and other visual artefacts in image mosaics. It can be applied to multi-spectral drone, aerial and satellite imagery. The consistency of multi-temporal and multi-sensor data can improved through its use.\n\n.. description_end\n\nSee the documentation site for more detail: https://homonim.readthedocs.io/.\n\n.. install_start\n\nInstallation\n------------\n\n``homonim`` is available as a python 3 package, via `pip <https://pip.pypa.io/>`_ or `conda <https://docs.conda.io/projects/miniconda>`_.\n\npip\n~~~\n\n.. code:: shell\n\n pip install homonim\n\nconda\n~~~~~\n\n.. code:: shell\n\n conda install -c conda-forge homonim\n\n.. install_end\n\nGetting started\n---------------\n\nCommand line interface\n~~~~~~~~~~~~~~~~~~~~~~\n\n.. cli_start\n\n``homonim`` command line functionality is accessed through the commands:\n\n- ``fuse``: Correct image(s) to surface reflectance.\n- ``compare``: Compare image(s) with a reference.\n- ``stats``: Report parameter statistics.\n\nGet help on ``homonim`` with:\n\n.. code:: shell\n\n homonim --help\n\nand help on a ``homonim`` command with:\n\n.. code:: shell\n\n homonim <command> --help\n\n.. cli_end\n\nExamples\n^^^^^^^^\n\nCorrect *source.tif* to surface reflectance by fusion with *reference.tif*, using the default settings:\n\n.. code:: shell\n\n homonim fuse source.tif reference.tif\n\nCorrect images matching *source\\*.tif* to surface reflectance by fusion with *reference.tif*. Use a 5 x 5 pixel kernel and the ``gain-blk-offset`` model for correction, and place corrected images in the *./corrected* directory:\n\n.. code:: shell\n\n homonim fuse -k 5 5 -m gain-blk-offset -od ./corrected source*.tif reference.tif\n\nStatistically compare *source.tif* and *corrected.tif* with *reference.tif*.\n\n.. code:: shell\n\n homonim compare source.tif corrected.tif reference.tif\n\n\nAPI\n~~~\n\nExample\n^^^^^^^\n\nSurface reflectance correction of an aerial image using a Sentinel-2 reference.\n\n.. comment\n The code below is copied from docs/examples/api_example and # [*] comments removed\n\n.. api_example_start\n\n.. code:: python\n\n from pathlib import Path\n from homonim import RasterFuse, RasterCompare, Model\n\n # urls of source and reference test images\n src_file = (\n 'https://raw.githubusercontent.com/leftfield-geospatial/homonim/main/'\n 'tests/data/source/ngi_rgb_byte_1.tif'\n )\n ref_file = (\n 'https://raw.githubusercontent.com/leftfield-geospatial/homonim/main/'\n 'tests/data/reference/sentinel2_b432_byte.tif'\n )\n\n # path to corrected file to create\n corr_file = './corrected.tif'\n\n # Correct src_file to surface reflectance by fusion with ref_file, using the\n # `gain-blk-offset` model and a kernel of 5 x 5 pixels.\n with RasterFuse(src_file, ref_file) as fuse:\n fuse.process(corr_file, Model.gain_blk_offset, (5, 5), overwrite=True)\n\n.. api_example_end\n\nReference imagery\n~~~~~~~~~~~~~~~~~\n\n`geedim <https://github.com/leftfield-geospatial/geedim>`_ can be used as a companion tool for searching and downloading cloud-free reference imagery. Alternatively, satellite imagery is available from a number of sources, including the `Google <https://developers.google.com/earth-engine/datasets>`_, `Amazon <https://aws.amazon.com/earth/>`_ and `Microsoft <https://planetarycomputer.microsoft.com/catalog>`_ repositories.\n\n\nUsage\n-----\n\nSee the documentation `here <https://homonim.readthedocs.io/>`_.\n\nTerminology\n-----------\n\n``homonim`` is shorthand for *homogenise image* and is a reference to `the paper <https://www.researchgate.net/publication/328317307_Radiometric_homogenisation_of_aerial_images_by_calibrating_with_satellite_data>`_ on which it is based.\n\nCredits\n-------\n\n``homonim`` relies on these excellent packages:\n\n- `rasterio <https://github.com/rasterio/rasterio>`__\n- `opencv <https://github.com/opencv/opencv>`__\n- `numpy <https://github.com/numpy/numpy>`__\n\nLicense\n-------\n\n``homonim`` is licensed under the terms of the `AGPLv3 <https://www.gnu.org/licenses/agpl-3.0.en.html>`__. This project is developed in collaboration with `InnovUS <https://www.innovus.co.za/>`__ at Stellenbosch University, alternative licenses can be arranged by `contacting <mailto:madeleink@sun.ac.za>`__ them.\n\nCitation\n--------\n\nPlease cite use of the code as:\n\n- Dugal Harris & Adriaan Van Niekerk (2019) Radiometric homogenisation of aerial images by calibrating with satellite data, *International Journal of Remote Sensing*, **40:7**, 2623-2647, DOI: https://doi.org/10.1080/01431161.2018.1528404.\n\nBibtex::\n\n @article{doi:10.1080/01431161.2018.1528404,\n author = {Dugal Harris and Adriaan Van Niekerk},\n title = {Radiometric homogenisation of aerial images by calibrating with satellite data},\n journal = {International Journal of Remote Sensing},\n volume = {40},\n number = {7},\n pages = {2623-2647},\n year = {2019},\n publisher = {Taylor & Francis},\n doi = {10.1080/01431161.2018.1528404},\n URL = {https://doi.org/10.1080/01431161.2018.1528404},\n }\n\n\n.. |Tests| image:: https://github.com/leftfield-geospatial/homonim/actions/workflows/run-unit-tests.yml/badge.svg\n :target: https://github.com/leftfield-geospatial/homonim/actions/workflows/run-unit-tests.yml\n.. |codecov| image:: https://codecov.io/gh/leftfield-geospatial/homonim/branch/main/graph/badge.svg?token=A01698K96C\n :target: https://codecov.io/gh/leftfield-geospatial/homonim\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.. |PyPI version| image:: https://img.shields.io/pypi/v/homonim?color=blue\n :target: https://pypi.org/project/homonim/\n.. |conda-forge version| image:: https://img.shields.io/conda/vn/conda-forge/homonim.svg?color=blue\n :alt: conda-forge\n :target: https://anaconda.org/conda-forge/homonim\n.. |docs| image:: https://readthedocs.org/projects/homonim/badge/?version=latest\n :target: https://homonim.readthedocs.io/en/latest/?badge=latest\n",
"bugtrack_url": null,
"license": "AGPL-3.0-or-later",
"summary": "Correct aerial and satellite imagery to surface reflectance.",
"version": "0.4.0",
"project_urls": {
"Changelog": "https://github.com/leftfield-geospatial/homonim/releases",
"Documentation": "https://homonim.readthedocs.io",
"Homepage": "https://github.com/leftfield-geospatial/homonim",
"Issues": "https://github.com/leftfield-geospatial/homonim/issues",
"Source": "https://github.com/leftfield-geospatial/homonim"
},
"split_keywords": [
"drone",
"aerial",
"satellite",
"image",
"surface reflectance",
"correction",
"harmonization",
"anisotropy",
"brdf",
"atmospheric correction"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0383373a09ee5d0ac2ee680d614b109f62074f001c89e0cb3f067366c9e4826f",
"md5": "664156ea9528bfe7bb6e5bcbc443403e",
"sha256": "e88fa194b55740197946f19339740456293a9d5455f6546708643bd452330413"
},
"downloads": -1,
"filename": "homonim-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "664156ea9528bfe7bb6e5bcbc443403e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 72330,
"upload_time": "2024-02-22T19:48:23",
"upload_time_iso_8601": "2024-02-22T19:48:23.401203Z",
"url": "https://files.pythonhosted.org/packages/03/83/373a09ee5d0ac2ee680d614b109f62074f001c89e0cb3f067366c9e4826f/homonim-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b0304f80d397ac967666ad1e39e169611df8b4f794db7939d6e7197ae422250d",
"md5": "fbb5c6d6e724dd6ae1280442bccc731c",
"sha256": "7b7f69627ba26179558740e4c770e264b3455edf3bcc5f79d5a1fc400011a824"
},
"downloads": -1,
"filename": "homonim-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "fbb5c6d6e724dd6ae1280442bccc731c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 81294,
"upload_time": "2024-02-22T19:48:24",
"upload_time_iso_8601": "2024-02-22T19:48:24.815991Z",
"url": "https://files.pythonhosted.org/packages/b0/30/4f80d397ac967666ad1e39e169611df8b4f794db7939d6e7197ae422250d/homonim-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-22 19:48:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "leftfield-geospatial",
"github_project": "homonim",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "homonim"
}
JSON
