doc updates and improvements

dugalh · dugalh · commit 84dabc923d81 · 2024-09-20T11:02:52.000+02:00
diff --git a/site/contact.rst b/site/contact.rst
@@ -32,5 +32,9 @@
             <td class="contact-type fas fa-phone"></td>
             <td class="contact-val"><a href="tel:+27828439679">+27 82 843 9679</a></td>
         </tr>
+        <tr>
+            <td class="contact-type fa-brands fa-github"></td>
+            <td class="contact-val"><a href="https://github.com/leftfield-geospatial">GitHub</a></td>
+        </tr>
     </table>
 
diff --git a/site/index.rst b/site/index.rst
@@ -3,6 +3,8 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+.. include:: shared.txt
+
 .. toctree::
    :maxdepth: 1
    :hidden:
@@ -25,13 +27,13 @@
         :fas:`door-open` **Welcome**
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-        Leftfield is a small research and software development company specialising in geospatial and earth observation applications, and offering assistance with:
+        Leftfield is a small research and software development company specialising in geospatial and earth observation applications.  Expert assistance can be provided with:
 
         * Creating operational software.
         * Applied research and method design.
         * Documentation and publication.
 
-        Collaborative in nature, and aligned with scientific best practice, Leftfield supports the open source model.  Through it's work, Leftfield aims to contribute toward a sane and vibrant living planet.  Please get :doc:`in touch <contact>` if you would like to find out more.
+        Collaborative in nature, Leftfield supports the open source model, and is the creator of the Orthority_, Homonim_ and Geedim_ projects.  Through it's work, Leftfield aims to contribute toward a sane and vibrant living planet.  Please get :doc:`in touch <contact>` if you would like to find out more.
 
 .. grid:: 1 3 3 3
     :gutter: 2
diff --git a/site/portfolio/biome_wide_thicket_agc.rst b/site/portfolio/biome_wide_thicket_agc.rst
@@ -1,4 +1,4 @@
 Biome-wide aboveground carbon mapping in thicket
 ------------------------------------------------
 
-As an experiment in extending the :doc:`farm-scale aboveground carbon (AGC) model <thicket_agc>` with `Google Earth Engine (GEE) <https://earthengine.google.com>`_, the univariate WorldView-3 model developed in that study was re-calibrated to Landsat-8 imagery, and applied to the thicket biome.  The resulting AGC map can be browsed via the `GEE app <https://dugalh.users.earthengine.app/view/thicket-aboveground-carbon>`_ (it might take a minute to load).  Importantly, this should be regarded as a prototype - AGC estimates outside the :ref:`GEF-5 SLM study area <gef5_slm_study_area>` are unvalidated.
+As an experiment in extending the :doc:`farm-scale aboveground carbon (AGC) model <thicket_agc>` with `Google Earth Engine (GEE) <https://earthengine.google.com>`_, the univariate linear model developed in that study was re-calibrated to Landsat-8 imagery, and applied to the thicket biome.  The resulting AGC map can be browsed with the `GEE app <https://dugalh.users.earthengine.app/view/thicket-aboveground-carbon>`_ (it might take a minute to load).  The app code is available `here <https://github.com/leftfield-geospatial/extend-thicket-agc>`_.  Note that this should be regarded as a prototype - AGC estimates outside the :ref:`GEF-5 SLM study area <gef5_slm_study_area>` are unvalidated.
diff --git a/site/portfolio/geedim.rst b/site/portfolio/geedim.rst
@@ -1,10 +1,6 @@
-Search, composite and download `GEE`_ imagery
----------------------------------------------
+.. include:: ../shared.txt
 
-The |geedim|_ package was developed as a companion to |homonim|_ for sourcing cloud/shadow-free reference imagery.  Beyond the |homonim|_ context, it is generally useful for searching, compositing and downloading GEE_ (Google Earth Engine) imagery.  It works around the `Earth Engine size limit <https://developers.google.com/earth-engine/apidocs/ee-image-getdownloadurl>`_ by downloading images as separate tiles, then re-assembling into an image file on the client.  Cloud/shadow masking, and cloud/shadow-free compositing are implemented for `selected Landsat and Sentinel-2 collections <https://geedim.readthedocs.io/en/latest/index.html#cloud-shadow-support>`_ using bundled quality data, as well as a method based on `cloud probability <https://developers.google.com/earth-engine/datasets/catalog/COPERNICUS_S2_CLOUD_PROBABILITY>`_ data for Sentinel-2.  |geedim|_ is distributed as a python package.  The `command line interface (CLI) <https://geedim.readthedocs.io/en/latest/cli.html>`_ provides access to most of the functionality.  See the `online documentation <https://geedim.readthedocs.io/en/latest/index.html>`_ for more detail on its use.
+Earth Engine search and download
+--------------------------------
 
-.. |geedim| replace:: ``geedim``
-.. _geedim: https://github.com/leftfield-geospatial/geedim
-.. |homonim| replace:: ``homonim``
-.. _homonim: https://github.com/leftfield-geospatial/homonim
-.. _GEE: https://earthengine.google.com
+Geedim_ was developed as a companion to :doc:`Homonim <homonim>` for acquiring cloud/shadow-free reference imagery.  It is a command line toolkit and library that allows searching, compositing and downloading `Google Earth Engine <https://earthengine.google.com>`__ satellite imagery.  Cloud/shadow masking and cloud/shadow-free compositing is supported on selected image collections.  It is used for these functions outside of the Homonim context too.  The `online documentation <https://geedim.readthedocs.io/en/latest/index.html>`_ gives more detail on its capabilities and use.
diff --git a/site/portfolio/homonim.rst b/site/portfolio/homonim.rst
@@ -1,38 +1,23 @@
-Correct imagery to surface reflectance
---------------------------------------
+.. include:: ../shared.txt
 
-This method uses a fusion approach to correct imagery to approximate surface reflectance.  It requires a concurrent and co-located reference reflectance image with which to fuse the source.  Since the method's `initial conception <https://doi.org/10.1080/01431161.2018.1528404>`_ with my PhD supervisor, `Adriaan van Niekerk <https://scholar.google.co.za/citations?user=bUalpwUAAAAJ&hl=en>`_, it has evolved into the |homonim|_ package, and proved effective for a `range of imagery and problems <https://homonim.readthedocs.io/en/latest/case_studies.html>`_.
+Surface reflectance correction
+------------------------------
 
-.. figure:: ../_images/homonim-block_diagram.webp
-    :align: right
-    :class: dark-light
-    :width: 520
-    :alt: Block diagram
-
-Spatially varying local linear models are used to approximate the relationship between source and reference images.  Images and model parameters are resampled or re-projected between the source and reference image CRS's (coordinate reference systems) to allow model estimation and application (as shown in the diagram).  Typically the reference has a lower resolution than the source image. Suitable sources of reference imagery are e.g. the `MODIS <https://developers.google.com/earth-engine/datasets/catalog/MODIS_061_MCD43A4>`_, `Landsat <https://developers.google.com/earth-engine/datasets/catalog/LANDSAT_LC08_C02_T1_L2>`_, or `Sentinel-2 <https://developers.google.com/earth-engine/datasets/catalog/COPERNICUS_S2_SR_HARMONIZED>`_ satellites.  The |geedim|_ companion tool was created for downloading these, and other satellite images.
-
-|homonim|_ can help improve accuracy and stability of classification and regression applications, and is suited to the harmonisation of multi-sensor images.  It is available as a `python package <https://homonim.readthedocs.io/en/latest/installation.html>`_.  There are more details on its use and functioning in the `online documentation <https://homonim.readthedocs.io/en/latest/index.html>`_.
-
-Example
-^^^^^^^
-
-A mosaic of NGI_ aerial imagery before and after correction with |homonim|_.
+The Homonim_ command line tool and library implements a method for surface reflectance correction `initially conceived <https://doi.org/10.1080/01431161.2018.1528404>`__ with my `PhD supervisor <https://scholar.google.co.za/citations?user=bUalpwUAAAAJ&hl=en>`__.
+The method fuses source imagery with a concurrent reference reflectance image to approximate surface reflectance.  It has been tested on a `range of imagery and applications <https://homonim.readthedocs.io/en/latest/case_studies.html>`_.  You can read more about its use and functioning in the `online documentation <https://homonim.readthedocs.io/en/latest/index.html>`_.
 
 .. figure:: ../_images/homonim-source_mosaic.webp
     :align: center
     :class: dark-light
     :width: 580
     :alt: Source mosaic
 
+    Aerial mosaic before correction.
+
 .. figure:: ../_images/homonim-corrected_mosaic.webp
     :align: center
     :class: dark-light
     :width: 580
     :alt: Corrected mosaic
 
-.. |geedim| replace:: ``geedim``
-.. _geedim: https://github.com/leftfield-geospatial/geedim
-.. |homonim| replace:: ``homonim``
-.. _homonim: https://github.com/leftfield-geospatial/homonim
-.. _NGI: https://ngi.dalrrd.gov.za/index.php/what-we-do/aerial-photography-and-imagery
-
+    Aerial mosaic after correction.
diff --git a/site/portfolio/index.rst b/site/portfolio/index.rst
@@ -18,49 +18,49 @@
     :gutter: 2
 
     .. grid-item-card::
-        :link: homonim
+        :link: simple_ortho
         :link-type: doc
 
-        **Correct imagery to surface reflectance**
-        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+        **Orthorectification toolkit**
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-        .. image:: ../_images/homonim-thumbnail.webp
+        .. image:: ../_images/simple_ortho-thumbnail.webp
             :align: center
+            :width: 85 %
             :class: dark-light
-            :width: 100 %
             :alt: Thumbnail
 
-        An end-user and research tool for harmonisation and surface reflectance correction of remotely sensed imagery.
+        A command line toolkit and library for orthorectification.
 
     .. grid-item-card::
-        :link: geedim
+        :link: homonim
         :link-type: doc
 
-        **Search, composite and download GEE imagery**
-        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+        **Surface reflectance correction**
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-        .. image:: ../_images/geedim-thumbnail.webp
-            :align: left
-            :width: 45 %
+        .. image:: ../_images/homonim-thumbnail.webp
+            :align: center
             :class: dark-light
+            :width: 100 %
             :alt: Thumbnail
 
-        A command line tool and python library for searching, compositing and downloading Google Earth Engine imagery.  Supports cloud and shadow masking, and cloud/shadow-free compositing.
+        A method and software package for surface reflectance correction.
 
     .. grid-item-card::
-        :link: simple_ortho
+        :link: geedim
         :link-type: doc
 
-        **Orthorectification of aerial images**
-        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+        **Earth Engine search and download tool**
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-        .. image:: ../_images/simple_ortho-thumbnail.webp
-            :align: center
-            :width: 85 %
+        .. image:: ../_images/geedim-thumbnail.webp
+            :align: left
+            :width: 45 %
             :class: dark-light
             :alt: Thumbnail
 
-        A command line tool and python library for orthorectification of aerial and other imagery.
+        A command line tool and library for searching, compositing and downloading cloud/shadow-free satellite imagery from Google Earth Engine.
 
     .. grid-item-card::
         :link: thicket_agc
@@ -75,7 +75,7 @@
             :width: 80 %
             :alt: Thumbnail
 
-        A machine learning method for mapping aboveground carbon in thicket, developed on data from a small site in the Baviaanskloof, South Africa.
+        A machine learning method for mapping aboveground carbon in thicket, developed on data from the Baviaanskloof, South Africa.
 
     .. grid-item-card::
         :link: biome_wide_thicket_agc
diff --git a/site/portfolio/simple_ortho.rst b/site/portfolio/simple_ortho.rst
@@ -1,22 +1,14 @@
-Orthorectification of aerial images
------------------------------------
+.. include:: ../shared.txt
 
-|simple-ortho|_ `orthorectifies <https://trac.osgeo.org/ossim/wiki/orthorectification>`_ aerial, and other imagery with known `pinhole camera model <https://en.wikipedia.org/wiki/Pinhole_camera_model>`_, and DEM (digital elevation model).  It works well with NGI_ aerial imagery, and together with |homonim|_ provides an open source processing chain for converting these valuable data into "science ready" surface reflectance imagery.  Currently, |simple-ortho|_ is available as a python library and command line tool via `GitHub <https://github.com/leftfield-geospatial/simple-ortho>`_.  It makes use of the `OpenCV <https://opencv.org/>`_ and `rasterio <https://github.com/rasterio/rasterio>`_ packages for efficient reading, processing and writing of images.
+Orthorectification
+------------------
 
-Example
-^^^^^^^
-
-A mosaic of four NGI_ aerial images captured over the Kouga river in the Baviaanskloof, South Africa: in raw form (*Source*), orthorectified with |simple-ortho|_ (*Orthorectified*), and corrected to surface reflectance with |homonim|_ (*Corrected*).
+Orthority_ is a command line toolkit and library for `orthorectifying <https://trac.osgeo.org/ossim/wiki/orthorectification>`__ remotely sensed imagery.  It was originally developed as a research tool for processing NGI_ aerial imagery.  Since then it has been expanded to support a range of imagery and camera models, and to provide orthorectification related methods like pan-sharpening.  Together with :doc:`Homonim <homonim>`, it provides an open source toolchain for converting remotely sensed images into "science ready" surface reflectance data.
 
 .. figure:: ../_images/simple_ortho-example.webp
     :align: center
     :class: dark-light
     :target: ../_images/simple_ortho-example.webp
     :alt: Orthorectification and correction example
 
-.. |homonim| replace:: ``homonim``
-.. _homonim: https://github.com/leftfield-geospatial/homonim
-.. |simple-ortho| replace:: ``simple-ortho``
-.. _simple-ortho: https://github.com/leftfield-geospatial/simple-ortho
-.. _NGI: https://ngi.dalrrd.gov.za/index.php/what-we-do/aerial-photography-and-imagery
-
+    A mosaic of four NGI images (*Source*) that has been orthorectified with Orthority (*Orthorectified*), then corrected to surface reflectance with Homonim (*Corrected*).
diff --git a/site/portfolio/thicket_agc.rst b/site/portfolio/thicket_agc.rst
@@ -1,9 +1,7 @@
 Farm-scale aboveground carbon mapping in thicket
 ------------------------------------------------
 
-Large portions of the semi-arid thicket biome (South Africa) have been degraded, mostly by poorly managed goat-farming.  Restoration work and research is ongoing, and much needed for improving ecosystem function and mitigating climate change.  Aboveground carbon (AGC) maps are important tools required for restoration monitoring and funding.  As part of the `GEF-5 SLM (sustainable land management) project <https://www.thegef.org/projects-operations/projects/5327>`_, this work developed an AGC mapping approach for a ±3000 ha study area in the Baviaanskloof.
-
-Using `species-specific allometric equations <https://doi.org/10.1016/j.foreco.2019.05.048>`_, AGC ground truth for 85 study area plots was produced from `field sampling data gathered by Sustainable Landscape Solutions <https://github.com/leftfield-geospatial/map-thicket-agc/blob/main/docs/gef5_slm_final_report_c_baselines_may2020.pdf>`_.  Spatial accuracy of ground truth and remotely sensed imagery was emphasised to ensure the accurate location of field plot data in images.  Ground truth plots are shown on a DSM (digital surface model) derived from multi-view NGI_ imagery, below.
+As part of the `GEF-5 SLM (sustainable land management) project <https://www.thegef.org/projects-operations/projects/5327>`_, this work developed an aboveground carbon mapping approach for thicket in a ±3000 ha study area in the Baviaanskloof.  Field methods were used to gather AGC ground truth for number of plots:
 
 .. _gef5_slm_study_area:
 
@@ -13,8 +11,4 @@ Using `species-specific allometric equations <https://doi.org/10.1016/j.foreco.2
     :width: 640
     :alt: Study area ground truth map
 
-Various AGC estimation approaches were evaluated using the ground truth.  These included the use of remotely sensed plant volume found from NGI image-derived `DTM and DSM <https://en.wikipedia.org/wiki/Digital_elevation_model#Terminology>`_ surfaces, and features extracted from multispectral imagery.  A multivariate linear regression model using features extracted from a multispectral `WorldView-3 <https://en.wikipedia.org/wiki/WorldView-3>`_ image was the best performing method.  Univariate linear models based on WorldView-3 and multispectral NGI images also performed well.  In the context of the need for cost-effective biome-wide AGC maps at repeated intervals, the use of multi-spectral satellite imagery was favoured as the approach most likely to scale to these requirements.
-
-While thicket allometric models for AGC are complex at the plant-scale, the success of linear models in this study suggests the relationship between remotely sensed variables and thicket AGC may be relatively simple at a landscape-scale.  The `code repository  <https://github.com/leftfield-geospatial/map-thicket-agc>`_, `related paper <https://doi.org/10.1117/1.JRS.15.038502>`_, and `project report <https://github.com/leftfield-geospatial/map-thicket-agc/blob/main/docs/gef5_slm_remote_sensing_of_agc_in_thicket_nov2019.pdf>`_ contain more details on the imagery, method and performance.
-
-.. _NGI: https://ngi.dalrrd.gov.za/index.php/what-we-do/aerial-photography-and-imagery
+Various approaches for modelling AGC were evaluated using the ground truth.  Straightforward linear regression models using high resolution multispectral satellite (WorldView-3) imagery performed well. The `code repository  <https://github.com/leftfield-geospatial/map-thicket-agc>`_ and  `related paper <https://doi.org/10.1117/1.JRS.15.038502>`_ contain more details on the data, method and performance.
diff --git a/site/profile.rst b/site/profile.rst
@@ -7,4 +7,4 @@
     :align: left
     :width: 25 %
 
-Leftfield was started by myself, Dugal Harris.  I am an electronic engineer with a PhD in geoinformatics.  My work experience has centered around the fields of remote sensing, machine learning and image processing; spanning both research and operational projects.  Currently, I develop mainly in `python <https://www.python.org/>`_, but am also fluent in `C++ <https://en.wikipedia.org/wiki/C%2B%2B>`_; and have explored a number of other languages.  I am based in Rheenendal, South Africa.
+Leftfield was started by myself, Dugal Harris.  I am an electronic engineer with a PhD in geoinformatics.  My work experience has centered around the fields of machine learning and image processing; spanning both research and operational projects.  I particularly enjoy applied problems with a theoretical component.  Currently, I develop mainly in `python <https://www.python.org/>`_, but am also fluent in `C++ <https://en.wikipedia.org/wiki/C%2B%2B>`_; and have explored a number of other languages.  I am based in Rheenendal, South Africa.
