asf_tools is a Python package for working with Synthetic Aperture Radar (SAR) data.
It was designed for working with datasets generated by
HyP3, but several of the tools have the
potential to be used with a variety of rasters, including non-SAR datasets.
In order to easily manage dependencies, we recommend using dedicated project
environments via Anaconda/Miniconda.
It is also possible to use Python virtual environments,
but installation of non-python dependencies (e.g., gdal) can be challenging.
asf_tools can be installed into a conda environment with:
conda install -c conda-forge asf_tools
or into a virtual environment with:
python -m pip install asf_tools
We also publish a Docker image for asf_tools, with all the dependencies
pre-installed, to the GitHub Container Registry:
https://github.com/ASFHyP3/asf-tools/pkgs/container/asf-tools.
You can pull an image with the latest released version of asf_tools with the command:
docker pull ghcr.io/asfhyp3/asf-tools:latest
Or, the development version with:
docker pull ghcr.io/asfhyp3/asf-tools:test
And then run the container with:
docker run --rm -it ghcr.io/asfhyp3/asf-tools:latest
which will drop you into a bash shell inside the container with an active asf-tools conda environment.
To move data between your local (host) machine and the container, you can mount a volume with:
docker run --rm -it -v /path/to/data:/home/conda/data ghcr.io/asfhyp3/asf-tools:latest
The make_composite tool allows you to create a local-resolution-weighted composite
from a set of Sentinel-1 RTC products (D. Small, 2012).
It is intended to be used with RTC products generated by ASF HyP3.
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
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.
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.
Warning
The HydroSAR codes (flood_map, water_map and hand modules) are being
moved to the HydroSAR project repository
and will be provided in a new pip/conda installable package hydrosar.
The asf_tools.hydrosar subpackage will be removed in a future release.
The water_map tool allows you to create a surface water extent map from a Sentinel-1
dual-pol (VV+VH) RTC product. It is intended to be used with RTC products generated by
ASF HyP3.
Additionally, a HAND (height above nearest drainage) GeoTIFF that is pixel aligned to the RTC images is required, and preferably derived from the same DEM used to correct the RTC images -- the quality of the HAND used is directly tied to the quality of the output water extent map.
To make a water extent map, run:
water_map [OUT_RASTER] [VV_RASTER] [VH_RASTER] [HAND_RASTER]
For more information and to see the options available, see:
water_map --help
For details on the algorithm see the asf_tools.water_map.make_water_map docstring.
Warning
The HydroSAR codes (flood_map, water_map and hand modules) are being
moved to the HydroSAR project repository
and will be provided in a new pip/conda installable package hydrosar.
The asf_tools.hydrosar subpackage will be removed in a future release.
The flood_map tool allows you to create an estimated flood depth map from the surface
water extent map created by the water_map tool.
Additionally, a HAND (height above nearest drainage) GeoTIFF that is pixel aligned to
the surface water extent map is required. An ideal candidate is the HAND image created
by the water_map tool.
To make a flood depth map, run:
flood_map [OUT_RASTER] [SURFACE_WATER_MAP] [HAND_RASTER]
For more information and to see the options available, see:
flood_map --help
For details on the algorithm see the asf_tools.flood_map.make_flood_map docstring.
The asf_tools.watermasking sub-package allows you to create a watermasking dataset
over an arbitrary ROI using OpenStreetMap and ESA WorldCover data.
Note, this program requires osmium-tool. See the watermasking subpackage readme
for more information on setup and usage.