Running FILL and FLOW

FILL takes as input an elevation grid and outputs a flow direction grid directions.asc and a filled elevation grid elevations.asc. FILL can also create a special file called the flowStream which contains all the information required by FLOW (filled elevations, flow directions) but in the internal format of TerraFlow. FLOW takes as input the flowStream produced by FILL and outputs the flow accumulation grid cnew.asc.

Before running TerraFlow the user should set two environment variables:

• OUTDIR: the directory where the output grids elevations.asc, directions.asc and cnew.asc are placed.
• AMI_SINGLE_DEVICE: the directory where TPIE intermediate files are placed.

Example:

• setenv OUTDIR /var/tmp/
• setenv AMI_SINGLE_DEVICE /var/tmp/

Space requirements: Make sure there is sufficient available space in $OUTDIR to hold the three output grids elevations.asc, directions.asc and cnew.asc. Make sure there is sufficient available space in $AMI_SINGLE_DEVICE to hold the TPIE intermediate files (approx 40N bytes for FILL and approx 50N for FLOW, where N is the number of cells of the input grid).

Example runs

Assume that the input DEM is /data/testdem.asc and the amount of available memory on the machine is 100MB.

• Run FILL with the -z flowStream= option to create a flowStream. For instance,
  • fill -m 100M -v -f /data/testdem.asc -z flowStream=/output/testdemFlowstrMFD

    Action: Use at most 100MB of main memory at all times. Verbose mode is on. Use input DEM /data/testdem.asc. Use default output paths: place the filled DEM in $OUTDIR/elevations.asc and the flow directions in $OUTDIR/directions.asc. Compute MFD directions. Place run stats file in ./stats.out. Create a flowStream in /output/testdemFlowstrMFD.

  • fill -m 100M -v -f /data/testdem.asc -z flowStream=/output/testdemFlowstrSFD -z sfd

    Action: As above, but compute SFD directions and place the flowStream in /output/testdemFlowstrSFD.

• Run FLOW using the flowStream generated by FILL. This is a shortcut and saves conversion time between input grid format (ascii, bil) and FLOW internal format (TPIE stream). For instance,
  • flow -m 100M -v -e /data/testdem.asc -t /output/testdemFlowstrMFD

    Action: Use at most 100MB of main memory at all times. Verbose mode is on. Use the flowStream /output/testdemFlowstrMFD and the header of /data/testdem.asc. Create and place the flow accumulation grid in $OUTDIR/cnew.asc. Use MFD to push flow downslope: that is, for each cell, push flow in the directions indicated by the (precomputed multiple flow directions in the) flowStream.

  • flow -m 100M -v -e /data/testdem.asc -t /output/testdemFlowstrSFD

    Action: As above, just that now the SFD flowStream testdemFlowStrSFD is used. Push flow to the directions indicated by the flowStream and, in addition, to all other downslope neighbors.

  • flow -m 100M -v -e /data/testdem.asc -t /output/testdemfFlowstrMFD -c 0

    Action: As above, but use SFD to push flow. The flowStream used contains MFD directions, so choose a dominant direction. If instead testdemFlowStrSFDif the flowStream computed by FILL contains SFD directions then just use that direction).

The user has the option to run FLOW without running FILL first. Say for instance that the filled elevation grid, the flow direction grid and the flow accumulation grid were computed with other software like ArcInfo, which uses D8-type algorithms (i.e. pushes flow downslope using SFD). Running FLOW results in a different flow accumulation grid computed by extending the input flow directions to all downslope neighbors.

Example:

• flow -m 100M -v -e /data/testdem.asc -d /data/flowdir.asc -a /data/flowaccu.asc

FILL options

• -h
  List all the options of FILL.
• -m
  Set the amount of main memory to be used by the program. Should be the amount of main memory available at run time on the machine where program is run. Default value: 300MB.
  Examples: -m 314572800, -m 300M
• -f
  Set the input DEM grid. Default value: null.
  Examples: -f /data/dem.asc
• -o
  Set the output filled DEM grid. Default value: $OUTDIR/elevations.asc.
  Examples: -o /data/filled_dem.asc
• -d
  Set the output flow direction grid. Default value: $OUTDIR/directions.asc.
  Examples: -o /data/flowdir.asc
• -s
  Set the name of the stats file for the run. Default value: ./stats.out.
  Examples: -s /output/statsrun1.out
• -v
  Set verbose mode on.
  Examples: -v
• -z flowStream=
  Create a file which encapsulates all the information needed by FLOW, like filled elevation, directions etc (we call this file the flowStream). Save it under the given name. Default value: flowStream is not created.
  Examples: -z flowStream=/output/flowstr
• -z sfd
  Compute SFD directions. Default value: MFD directions.
  Examples: -z sfd

  Debug options

• -V
  Set very verbose mode on.
  Examples: -V All the following debug options enable starting the program "in the middle". Used when the program crashes to figure out when and what went wrong.
• -z saveBoundaryStream=
• -z loadBoundaryStream=
• -z saveLabeledWater=
• -z loadLabeledWater=
• -z saveMergedWater
• -z loadMergedWater=
• -z maxWatershedCount=

FLOW options

• -h
  List all the options of FLOW.
• -m
  Set the amount of main memory to be used by the program. Should be the amount of main memory available at run time on the machine where program is run. Default value: 300MB.
  Examples: -m 314572800, -m 300M
• -t
  Set the input flowStream. Default value: null. The flowStream must be created by running FILL with -z flowStream= option.
  Note: This option requires the -e option. FLOW has all the information in the flowStream, except for the header of the grid, which it reads from the DEM.
  Example: -t /output/flowStr -e /data/dem.asc
• -e
  Set the input filled DEM grid. Default value: null.
  Examples: -e /output/elevations.asc
• -d
  Set the input flow direction grid. Default value: null.
  Note: This option requires the -e -a options. It is used only when the user wants to run FLOW without using FILL outputs. In this casethe user must provide a filled DEM, a flow direction and a flow accumulation grid computed with other software.
  Examples: -d /output/directions.asc
• -a
  Set the input flow accumulation grid. Default value: null.
  Note: This option requires the -e -d options. It is used only when the user wants to run FLOW without using FILL outputs. In this case must provide a filled DEM, a flow direction and a flow accumulation grid computed with other software.
  Examples: -a /output/flowaccu.asc
• -v
  Set verbose mode on.
  Examples: -v
• -c
  If flow accumulation of a cell is bigger than this value, switch to SFD. Default value: infinit (never switch to SFD).
  Example: -c 1

  Debug options

• -l
  Enable loading the sorted sweep stream from disk.
  Example: -l -W /output/flow_sorted_sweep
• -w
  Enable saving the sorted sweep stream to disk.
  Example: -w -W /output/flow_sorted_sweep
• -W
  Set the name of the sorted sweep stream.
• -s
  Set the size of the priority queue use during sweeping.

Configuring TerraFlow

TerraFlow can be configured by setting/unsetting flags in the file stepConfig.H.

Things which can be configured include:

• what outputs are computed (flow, tci, tan beta, contour)
• the type of the flow accumulation (int, float)
• input grid type (ascii, bil)
• output grids type (ascii, bil)

Here is a sample of stepConfig.H. For more info contact {laura , rajiv}.