## ASF Tools for Python

[![PyPI license](https://img.shields.io/pypi/l/asf_tools.svg)](https://pypi.python.org/pypi/asf_tools/)
[![PyPI pyversions](https://img.shields.io/pypi/pyversions/asf_tools.svg)](https://pypi.python.org/pypi/asf_tools/)
[![PyPI version](https://img.shields.io/pypi/v/asf_tools.svg)](https://pypi.python.org/pypi/asf_tools/)
[![Conda version](https://img.shields.io/conda/vn/conda-forge/asf_tools)](https://anaconda.org/conda-forge/asf_tools)
[![Conda platforms](https://img.shields.io/conda/pn/conda-forge/asf_tools)](https://anaconda.org/conda-forge/asf_tools)

`asf_tools` is a Python package for working with Synthetic Aperture Radar (SAR) data.
It was designed for working with datasets generated by
[HyP3](https://hyp3-docs.asf.alaska.edu/), but several of the tools have the
potential to be used with a variety of rasters, including non-SAR datasets.


## Install

`asf_tools` can be installed via [Anaconda/Miniconda](https://docs.conda.io/en/latest/index.html):

```
conda install -c conda-forge asf_tools
```

Or using [`pip`](https://pypi.org/project/asf_tools/):

```
python -m pip install asf_tools
```

## Quick Usage

### Local Resolution Weighted Composite

The `make_composite` tool allows you to create a local-resolution-weighted composite from a set of Sentinel-1 RTC
products ([D. Small, 2012](https://doi.org/10.1109/IGARSS.2012.6350465)). It is intended to be used with RTC products generated by [ASF HyP3](https://hyp3-docs.asf.alaska.edu/using/vertex).

You will need to request RTC products using the `Include Scattering Area` option, then download and unzip them into an empty directory.

To generate a composite of the co-polarization images, navigate to the directory containing the unzipped RTC products and run:
```
make_composite VV-composite */*VV.tif
```

To generate a composite of the cross-polarization images, navigate to the directory containing the unzipped RTC products and run:
```
make_composite VH-composite */*VH.tif
```

#### Usage Tip
Because the imagery has been radiometrically terrain corrected (RTC), geometric and radiometric distortions have been removed from the files to be composited.  One the strong points of LRW composites is that you combine both ascending and descending datatakes into a single product.  In this manner no layover or shadow masks are required - what is shadowed on an ascending pass is visible in a descending pass and vice-versa.  Thus, not only is it possible to combine ascending and descending, but it is highly encouraged.  Using many datatakes from both the ascending and descending satellite passes will make the best composites possible.

#### About Local Resolution Weighting (LRW)
In an LRW composite, each satellite pass contributes to creating the output pixels.  The amount of this contribution is scaled by the inverse of the scattering area used during terrain correction (thus the need for requesting the area map option of HyP3 RTC).  The inverse of the surface scattering area, also referred to as local resolution, is multiplied by each pixel's backscatter value.  The results of all of the images covering any single pixel are then summed. This total is then divided by the sum of the weights used to get the output average backscatter.
