Tutorial 1: Quick Start

Tutorial 1: Quick Start#

This notebook mirrors the quick-start flow from the getting started guide.

What is floodsr?#

floodsr is a flood-depth resolution enhancement tool. It takes a low-resolution depth raster and reconstructs a higher-resolution result using terrain context from a DEM.

Using this tutorial#

There are three common ways to run this tutorial (i.e., execution contexts):

  • command line (CLI): proceed by copy/pasting the below commands from your web-browser into your terminal. NOTE for most terminals you’ll need to remove the prefix ! from each command.

  • local notebook (Jupyter): Use the button to save this notebook as an .ipynb file to your local machine (may need to click save as) and open it with your local Jupyter kernel. see Local notebook (Jupyter) for details.

  • hosted notebook (Colab): Use the button to open this tutorial on Google Colab.

Install floodsr#

Don’t be scared. Install is super easy.

The appropriate installation steps depend on your execution context, which is described in detail in :ref:basic_install. Here are the basic steps for each:

  • command line (CLI): first, ensure pipx is installed and on PATH, then run pipx install floodsr. see Command line (CLI) for more details.

  • local notebook (Jupyter): same as above. then either follow the additional steps in Local notebook (Jupyter) to properly set up your environment, or be lazy and uncomment the below Jupyter cell and run.

  • hosted notebook (Colab): uncomment the below colab cell and run. see Hosted notebook (Colab) for details.

command line (CLI) install: run pipx install floodsr in your terminal

Local notebook (Jupyter) magic install

# %pip install -q floodsr

Hosted notebook (Colab) install

# !python -m pip install -q floodsr

prove the install#

run the below command to confirm the install worked and floodsr is on your PATH:

!floodsr --help

Download test data#

Before running commands, download a small example dataset into your current working directory.

from urllib.request import urlretrieve

urlretrieve(
    "https://github.com/cefect/floodsr/releases/download/v0.0.3/hires002_dem.tif",
    "hires002_dem.tif",
)
urlretrieve(
    "https://github.com/cefect/floodsr/releases/download/v0.0.3/lowres032.tif",
    "lowres032.tif",
)

List available models#

Before running inference, inspect the manifest to see which model versions are available.

!floodsr models list

Fetch model weights#

Fetch the default model into the local cache.

!floodsr models fetch --no-progress ResUNet_16x_DEM

Run tohr with a local DEM#

Now let’s run the to high resolution tohr command to enhance the resolution of our low-resolution depth raster against the hi-res DEM.

!floodsr tohr --in lowres032.tif --dem hires002_dem.tif

If you inspect your working directory, you should see a new file called lowres032_sr.tif. This is the output of the tohr command, and should match the resolution of the DEM (2m in this case). Because we didn’t specify an output path, floodsr defaulted to writing the output to the same directory as the input, with _sr appended to the filename.

Hooray! You just ran your first floodsr command. You deserve some 🍰.

Run tohr with fetched HRDEM data#

Passing --fetch-hrdem tells tohr to attempt to fetch the HRDEM data for your raster extents. Of course, this will only work if your raster extents overlap with the coverage of the HRDEM data. Otherwise, you’ll get an error.

!floodsr tohr --in lowres032.tif --fetch-hrdem

Next steps#

To help you on your hi-res flood journey, now is a good time to get familar with:

  • the User Guide for a more detailed walkthrough of the above steps and concepts.

  • the CLI Reference for a detailed reference of all available commands and options.

Or continue with the next tutorial notebook