Fractionalcover version 3

Vegetation fractional cover package.

Description

Vegetation fractional cover represents the exposed proportion of green, non-green, and bare cover within each pixel. Landsat-scale ground cover information is important for soil erosion and nutrient flux estimates into the stream network, as well as assessing the impact of human activities.

The fractional cover v3.0 model is a Multi Layer Perceptron (neural network) model architecture that uses surface reflectance to estimate the three cover fractions of bare ground, photosynthetic vegetation (PV) and non-photosynthetic vegetation (NPV). The MLP model was trained with Tensorflow using Landsat TM, ETM+ and OLI surface reflectance and a collection of 4000 field observations of overstorey and ground cover. The field observations covered a wide variety of vegetation, soil and climate types across Australia, collected between 1997 and 2018 following the procedure outlined in:

Muir, J., Schmidt, M., Tindall, D., Trevithick, R., Scarth, P. and Stewart, J.B., 2011. Field measurement of fractional ground cover: a technical handbook supporting ground cover monitoring for Australia. Australian Bureau of Agricultural and Resource Economics and Sciences (ABARES): Canberra, Australia.

Installation

The core package needs only numpy and LiteRT, which are installed automatically:

python -m pip install fractionalcover3

This is all you need to use unmix_fractional_cover (see Basic Usage).

Optional extras

The package also includes two scripts, compute_fractionalcover.py and qv_fractionalcover_sentinel2.py, which produce fractional cover images from RSC standard Landsat and Sentinel-2 surface reflectance. Their dependencies are provided by two extras:

Both scripts also need the GDAL Python bindings, which are not installed by either extra because they must match the version of your system GDAL library. Install them first:

python -m pip install numpy setuptools wheel
python -m pip install gdal[numpy]==$(gdal-config --version) --no-build-isolation

The raster processing package RIOS is not on PyPI. With uv it is installed from GitHub automatically; with pip, install it first:

python -m pip install git+https://github.com/ubarsc/rios@rios-2.1.1
python -m pip install fractionalcover3[cli]

The scripts will only run with the rsc extra installed. The rsc and rss-da packages are internal to the JRSRP and are only available from a private package index, so contact the authors for access. Use uv rather than pip to install this extra: an unrelated package called rsc exists on PyPI, and the project configuration makes uv fetch rsc from the private index only. See Development for the commands.

Without access to these packages, the scripts are still included as templates for writing similar scripts that operate on complete images.

Basic Usage

The main function in the package is unmix_fractional_cover, which takes a numpy 3d array for surface reflectance (scaled between 0 and 1), and produces a 3d array of fractional cover. The output has 3 bands, one for each bare, green and non-green components.

The unmixing uses a tensorflow model. This is supplied as a ai_edge_litert.compiled_model.CompiledModel object. There are four models provided with the package, each at varying levels of complexity. These can be selected by number, with 1 the simplest and 4 the most complex.

The simplest example might look like:

from fractionalcover3.unmixcover import unmix_fractional_cover
from fractionalcover3 import data
import numpy as np
inref = np.array([562, 825, 1088, 2056, 2951, 2187]) * 0.0001
inref.shape = (6, 1, 1)

# use the default model provided
fractions = unmix_fractional_cover(inref,
                                       fc_model=data.get_model()
                                  )
for i,fraction in enumerate(['bare','green','dry']):
  print(fraction, fractions[i,0,0])
print('total', fractions.sum())

Output should be:

bare 0.12142971
green 0.23126282
dry 0.6459608
total 0.99865335

Development

This project uses uv. GDAL is not installed by uv sync, as the Python bindings must match the version of your system GDAL library, so it is installed separately afterwards. Use uv run --no-sync to run the tests, otherwise uv will remove the GDAL bindings again.

uv sync --extra cli
uv pip install setuptools wheel
uv pip install "gdal[numpy]==$(gdal-config --version)" --no-build-isolation-package gdal
uv run --no-sync pytest

The tests that need the internal JRSRP packages (rsc and rss-da) are skipped unless they are installed, and are not run by the public CI pipeline. If you have access to the private package index, set your credentials and install the rsc extra instead, then run the full test suite locally before merging:

export UV_INDEX_JRSRP_USERNAME=<your_username>
export UV_INDEX_JRSRP_PASSWORD=<your_token>
uv sync --extra rsc --no-install-package gdal
uv pip install setuptools wheel
uv pip install "gdal[numpy]==$(gdal-config --version)" --no-build-isolation-package gdal
uv run --no-sync pytest

Updating uv.lock (for example after changing dependencies with uv lock or uv add) also requires access to the private index, as the lock file includes the rsc extra.

How to Cite this Package

You can cite this package using the DOI:

@misc{scarthp2022,
  title={JRSRP} {F}ractional {C}over 3.0,
  author={Peter Scarth, Robert Denham, Fiona Watson},
  year={2022},
  month={08},
  howpublished={\url{https://gitlab.com/jrsrp/themes/cover/fractionalcover3}},
  doi={10.5281/zenodo.7008343}
}