Metadata-Version: 2.5
Name: fractionalcover3
Version: 2.0.0
Summary: Python package to produce land cover fractions from satellite imagery.
Project-URL: Homepage, https://gitlab.com/jrsrp/themes/cover/fractionalcover3
Project-URL: Documentation, https://jrsrp.gitlab.io/themes/cover/fractionalcover/
Author: Joint Remote Sensing Research Program
Maintainer-email: Robert Denham <robert.denham@uq.edu.au>
License-Expression: MIT
License-File: LICENSE.txt
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Requires-Python: >=3.10
Requires-Dist: ai-edge-litert
Requires-Dist: ml-dtypes
Requires-Dist: numpy
Provides-Extra: cli
Requires-Dist: click; extra == 'cli'
Requires-Dist: coloredlogs; extra == 'cli'
Requires-Dist: rios; extra == 'cli'
Requires-Dist: scipy; extra == 'cli'
Provides-Extra: rsc
Requires-Dist: click; extra == 'rsc'
Requires-Dist: coloredlogs; extra == 'rsc'
Requires-Dist: rios; extra == 'rsc'
Requires-Dist: rsc; extra == 'rsc'
Requires-Dist: rss-da; extra == 'rsc'
Requires-Dist: scipy; extra == 'rsc'
Description-Content-Type: text/markdown

# 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](https://numpy.org/) and
[LiteRT](https://ai.google.dev/edge/litert/next/overview), which are installed
automatically:

```
python -m pip install fractionalcover3
```

This is all you need to use `unmix_fractional_cover` (see [Basic Usage](#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:

| Extra   | Installs                                    | Availability             |
|---------|---------------------------------------------|--------------------------|
| `cli`   | `click`, `coloredlogs`, `scipy`, `rios`     | public                   |
| `rsc`   | everything in `cli`, plus `rsc` and `rss-da` | internal to the JRSRP    |

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](https://www.rioshome.org/) 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](https://www.jrsrp.org.au/) 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](#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:

```python
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:

```python
bare 0.12142971
green 0.23126282
dry 0.6459608
total 0.99865335
```



## Development

This project uses [uv](https://docs.astral.sh/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}
}
```
