GRASS GIS: m.toposu

NAME

m.toposu - Topology calculation for surface units

KEYWORDS

vector, topology, areal units, MHYDAS

SYNOPSIS

m.toposu
m.toposu help
m.toposu [-canbsldz] input=name output=name dem=name [hydro=name] [inputman=name] [gu=name] ID=string [IDHYDRO=string] [POHYDRO=string] [IDGU=string] [step=float] [distreach=float] [slop_val=float] [colz=string] [ID_OUT=string] [AREA_OUT=string] [SLOPE_OUT=string] [FCDE_OUT=string] [FID_OUT=string] [FDIST_OUT=string] [PCSSORD_OUT=string] [COMMENT_OUT=string] [GUID_OUT=string] [--overwrite] [--verbose] [--quiet]

Flags:

-c: calculate altitude with one pixel on centroid for linear feature; default (no flag c) is mean feature altitude on centroid
-a: calculate altitude with one pixel on centroid for areal feature; default (no flag a and no flag n) is mean feature altitude on centroid
-n: calculate altitude with D-8-like neighbours on centroid for areal feature; default (no flag a and no flag n) is mean feature altitude on centroid
-b: neighbouring research with feature boundaries and one contact point ; default (no flag b) is classical (D8 modified) neighbouring research
-s: down neighbour choice by slope; default (no flag s) is down neighbour choice by difference altitude
-l: Treatment of the topology loops; default is no
-d: create output_dir layer (line topological direction layer between surface units centroids)
-z: join z attribute from INPUT for areal feature (use colz column);default (no flag a, no flag n and no flag z) is mean feature altitude on centroid
--overwrite: Allow output files to overwrite existing files
--verbose: Verbose module output
--quiet: Quiet module output

Parameters:

input=name: Input polygon vector name
output=name: Output polygon vector name
dem=name: Input DEM name
hydro=name: Input line hydrologic vector name
inputman=name: Input line direction vector name (manual topology)
gu=name: Input ground water vector name
ID=string: ID INPUT column name
IDHYDRO=string: ID HYDRO column name
POHYDRO=string: Column name of the Process Order of HYDRO objects
IDGU=string: ID Ground Water column name
step=float: distance (in meters) between each slope direction inside a SU (boundaries and one contact point topology); needed for flag b
distreach=float: distance in meters for a possible contact between a SU and a reach
slop_val=float: Replacement value for null or negative calculated slope (must be > 0; default value is 0.0001)
colz=string: id z attribute column name (for flag z)
ID_OUT=string: id OUTPUT column name; Default: SELF_ID
AREA_OUT=string: AREA OUTPUT column name; Default: USR_AREA
SLOPE_OUT=string: SLOPE OUTPUT column name; Default: USR_SLOP
FCDE_OUT=string: Flow Code OUTPUT column name; Default: FLOW_CDE
FID_OUT=string: Flow ID OUTPUT column name; Default: FLOW_ID
FDIST_OUT=string: Flow Distance OUTPUT column name; Default: FLOW_DST
PCSSORD_OUT=string: Process Order OUTPUT column name; Default: PCSS_ORD
COMMENT_OUT=string: Commentary OUTPUT column name; Default: COMMENT
GUID_OUT=string: ID GU OUTPUT column name; Default: EXHGW_ID

DESCRIPTION

m.toposu allows the user to calculate the oriented topology for an areal units layer. This topology is made for the MHYDAS model. Several options are possible, please read carefully the following paragraphs for choosing the right options for your calculations.

NOTES

Input and output layers

The input layer can be created by m.seg, but m.toposu script can also accept a simple polygon layer (just be sure that in that case layer geometry and topology are correct). The output layer will contain the following columns (columns are created during this process):

- $ID_OUT : uniq Object ID

- $AREA_OUT : Area (square meters)

- $SLOPE_OUT : Slope (m/m)

- $FCDE_OUT : Downstream feature type unit (R for reach segment and S for surface unit) for surface exchange

- $FID_OUT : ID unit for surface exchange

- $FDIST_OUT : Distance (m) between centroids of the unit and its downstream unit

- $PCSSORD_OUT : Object Process Order

- $GUID_OUT : ID unit for underground exchanges

- $COMMENT_OUT : Commentary

If the user wants to have xml files or fluidx files for the OpenFluid version 1.5 or superior, please use m.definput to create these files.

Flag -d allows the user to create the line topological direction layer which links surface units centroids (rooted topological tree); the layer will have OUTPUT_dir name.

Calculated slopes are always positive (no negative or null value); for negative or null slopes, user can manage its own value by slop_val option (default value is 0.0001).

$FDIST_OUT parameter is calculated with x,y and z coordinates of centroids of the linear or areal units (AND not only with x and y coordinates). If using Flag -d, differences can appear between $FDIST_OUT parameter and length of linear features of the topological direction layer because of taking account into the z coordinate of the points in $FDIST_OUT parameter calculation.

Concerning reach network

The HYDRO layer is optional; if the user provides it, the layer must be created by m.toporeach. The layer must contain the following columns which are needed for this procedure:

- IDHYDRO : unique Hydro object ID

- POHYDRO : Hydro object Process Order

DISTREACH option :
The user can set the distreach value which allows to have a buffer distance between areal unit boundaries and Hydro objects. Even if a Hydro object is not a right topological neighbour, the distreach allows to consider it like a neighbour.

Potential topological neighbours without distreach (left) ; Potential topological neighbours with distreach (right)

On the left figure, without distreach option, the topological neighbours of the unit number 2 are the units 1 and 3. Even if the reach 4 is near the boundary of the unit 2, this reach will not be found by the algorithm because it is not a topological neighbour. On the right figure, if distance d (which represents the distance between reach segment and boundary of the unit 2) is smaller than the distreach value , reach 4 is considered by the algorithm as a topological neighbour of unit 2. The option is usefull when the geometry of these linear objects don't coincide exactly with polygon boundaries (due to different digitalizations).

Flag C :
m.toposu needs to know reach segment elevation. Two options are possible to calculate these values with the help of DEM : if flag c is set, just the one pixel on centroid reach is used to know the elevation of reach. If this flag is not set, all the DEM pixels which are in contact with the whole reach are used to calculate the mean elevation of the reach.

Flag c set: pixel in contact with reach centroid is only used (left) ; Flag c not set: pixels in contact whith whole reach are used (right)

Concerning groundwater layer

Groundwater layer is optional but if the user wants the underground-surface topology, GU and IDGU (unique ID Groundwater Object column name) must be provided. Topological relations are based on the following spatial analysis : for each SU centroid, algorithm indicates which GU polygon contains this point.

Options for topology parametrization

INPUTMAN option :
This algorithm use the difference elevation between SU to calculate oriented topology, which is based on DEM values. If the user doesn't want to use DEM values for the whole spatial domain or part of it, he can provided personal oriented topology preferences. If INPUTMAN layer is provided the algorithm considers this layer in priority to create oriented topology. For SU which aren't concerned by INPUTMAN orientation, the DEM value is used to find the downstream neighbour. With this option, the user can have : a whole automatized oriented topology calculation with DEM (with no INPUTMAN layer provided), a hybrid procedure (with a manual topology for part of the spatial domain which is concerned by INPUTMAN orientation and with DEM values for the rest of the domain) or a whole manual procedure (if INPUTMAN orientations concerned the whole domain). INPUTMAN layer is a simple linear layer : to indicate orientation topology between two units (areal to areal or areal to linear), the user just "draws" a line which crosses the two units (see following figure for details); just be careful to the line orientations.

INPUTMAN layer (in red arrows), SU layer (in grey color) and RS layer (in blue lines)

INPUTMAN layer is represented by the red arrows : unit 15 has the unit 14 which is its downstream unit because a red arrow crosses these two units, and unit 14 go into the reach ( INPUTMAN is used with distreach value to find which reach segment is near the end of the arrow). Unit 17 has no arrow to find its downstream unit, so the DEM value will be used to find it.

SU elevation using flags A, N or Z :
Three choices to calculate SU elevation are possible (see following figure to detail) :

- Flag A is set : just the DEM pixel on contact with SU centroid is used to calculate SU elevation

- Flag N is set : the DEM pixel on contact with SU centroid and its 8 neighbours are used to calculate SU elevation

- Flag Z is set : using the colz option, the user can provided a vector with z value already stored; no altitude calculation

- No Flags set (default method) : the whole DEM pixels in contact with the SU are used to calculate the SU elevation

Flag A set (left) ; Flag N set (middle) ; Flags A and N NOT set, default method (right)

Neighbouring research with Flag B :
Two choices are possible to find downstream neighbours of a unit (See following figure for details):

- Flag B is set : For each unit, in a first step, the lowest point on unit boundary (in comparison to centroid elevation) is found, and in a second step, the algorithm searches which neighbouring unit (linear or areal) share this point. step option is used to create virtual points along boundaries (step value is the distance between each point). This method is quite slow, especially if step value is small.

- Flag B is NOT set (default method) : For each unit, the algorithm searches all neighbours (linear and areal) and choose the downstream unit which has the tallest elevation difference.

Flag B set (left) ; Flags B NOT set, default method (right)

On left figure, using Flag B, grey dashed arrows represent the whole potential directions, the black plain arrow the tallest elevation difference. The black dashed arrow shows the topology connection between the centroid of this unit and the centroid of its downstream unit. On right figure, when Flag B is not set, labels are elevation values : even if the tallest elevation difference could be between the grey unit and the unit with 78 m elevation; the chosen direction is between the grey unit and the blue reach segment (reach segment in this case has the priority ahead of this lowest neighbour unit)

Downstream unit choice with Flag S :
The downstream unit choice is made with two possibilities :

- Flag S is set : the slope between unit centroid (in case of Flag B no set) or between unit centroid and points on boundary (in case of Flag B is set) is calculated; and tallest slope is chosen to identify the downstream unit.

- Flag S is NOT set : the downstream unit is chosen by calculating only the tallest elevation difference value (distance between points is not taken into account).

Concerning loop treatment

Oriented topology relations need to build a perfect rooted tree. After calculting oriented topology for each areal unit, loops between units can appear (due to low quality DEM or reach network between units missed out) : these relations can be between two or more units (i.e. in the left following figure, the unit 6 has as downstream unit the unit 5, and the unit 5 the unit 6). Using Flag L allows to treat these loops with the following steps :

1. Identify the clusters of areal units involved in loops (left following figure),

2. Merge these areal units into a single areal entity (middle following figure),

3. Select the neighboring unit of this entity with the greatest decrease in elevation,

4. Eliminate the loops by forcing the areal unit(s) of the cluster that share a boundary with the selected unit to flow in this unit (right following figure),

5. Repeat 1 through 4 until no loops remain.

Topology before loop treatment (left) ; Step 2 of the loop treatment (middle); Step 4 of the loop treatment (right)

Treated loops are known and, after treatment, if the same loop is met again, procedure is stopped with warning message for the user.

EXAMPLES

Using DEM value for whole spatial domain

GRASS 6.3.0 :~ > m.toposu -c -a -b -s -l input=surface_units output=surface_units2 dem=MNT hydro=reachs gu=groundW ID=SELF_ID IDHYDRO=IDH POHYDRO=POH IDGU=IDG step=2 distreach=1

Using input line direction vector, DEM value

GRASS 6.3.0 :~ > m.toposu -c -a -b -s -l input=surface_units output=surface_units2  dem=MNT hydro=reachs inputman=lineIN ID=SELF_ID IDHYDRO=IDH POHYDRO=POH step=2 distreach=1

AUTHORS

Michael Rabotin, UMR LISAH, Montpellier, France

rabotin@supagro.inra.fr

Last Changed: 04 July 2011

Main index