gridadmin.h5

The gridadmin.h5 file contains the computational grid. This is all static data, i.e. the file contains no time series. It is the basis for interfacing with all of the other files.

The file is accessed through the class GridH5Admin.

Minimal example

from threedigrid.admin.gridadmin import GridH5Admin

# Instantiate GridH5Admin objects
gridadmin_filename = r"C:\3Di\My Model\gridadmin.h5"
ga = GridH5Admin(gridadmin_filename)

# Query some model meta data
ga.has_groundwater
>>> False
ga.has_1d
>>> True

# Get flowlines with KCU value 100 and 101 (2D line / 2D line that crosses an obstacle)
ga.lines.filter(kcu__in=[100, 101])

Functionalities

Models

The contents of the gridadmin file are accessed through a number of threedigrid Models (not to be confused with “3Di model”):

Breaches
CrossSections
Grid
Levees
Lines
Nodes

Breaches

Breaches are 1D-2D flowlines that were schematised using a Potential breach feature. They are Lines with a KCU value (line type) of 55.

Breaches have the following attributes:

Variable Name	Description
code	Code as set in the schematisation
content_pk	ID of the source record in the schematisation
coordinates	Coordinates of the start and end nodes
display_name	Display name as defined in the schematisation
kcu	Line type
levbr	Breach width
levl	Exchange level
levmat	Levee material
line_geometries	Geometry of the breach line (start node to end node)
seq_ids	Deprecated

CrossSections

CrossSections describe all 1D cross-sections used in the 3Di model.

CrossSections have the following attributes:

Variable Name	Description
code	Code as set in the schematisation
content_pk	ID of the source record in the schematisation
count	Number of items in the tables array for this CrossSection
offset	Index of the first item of the tables array where the data for this CrossSection is located
shape	Shape
tables	Array of all values for all Tabulated cross-sections
width_1d	Width of cross-section (for circle and rectangle)

Grid

property Grid.n2dtot

property Grid.dx: Return size of the grid cell for each refinement level, in meters.

property Grid.transform

Return the transformation that maps pixel_coords to coordinates.

The six returned values (a, b, c, d, e, f) define the (affine) transform between coordinates (x, y) and pixel indices (i, j) as follows:

>>> x = a * i + b * j + c
>>> y = d * i + e * j + f

Note that for a 3Di grid, the vertical pixel size is positive, while for most raster files this is negative. This means that you should flip the vertical axis of the raster when using the pixel coordinates.

Grid has the following attributes.

Variable Name	Description
ip	Deprecated
jp	Deprecated
nodk	Refinement level, 1 being the smallest cell
nodm	Horizontal index of the cell within its refinement level
nodn	Vertical index of the cell within its refinement level

Levees

property Levees.geoms

Levees.load_geoms(): load levee geometries originating from model DB

Levees have the following attributes:

Variable Name	Description
coords	Geometry of the levee
crest_level	Crest level
max_breach_depth	Max breach depth

Lines

property Lines.channels

property Lines.culverts

property Lines.orifices

property Lines.pipes

property Lines.weirs

property Lines.line_nodes

Lines.cross_pix_coords_transformed(geo_transform)

Get pix_coords transformed by geo_transform (=ga.grid.transform)

>>> x = a * i + b * j + c
>>> y = d * i + e * j + f

The Lines class is parent to a number of child classes:

Channels
Culverts
Orifices
Pipes
Weirs

Lines and its child classes have the following attributes:

Variable name	Description
content_pk	ID of the source feature in the schematisation
content_type	Source table in the schematisation
cross_pix_coords	Location (index) of the lower left and upper right of the pixels at the cross-section in DEM (1-based)
cross_weight	Relative distance between cross1 and cross2 (counting from cross1)
cross1	ID of CrossSection 1. See also Lines.cross_weight
cross2	ID of CrossSection 2. See also Lines.cross_weight
discharge_coefficient_negative	Positive discharge coefficient
discharge_coefficient_positive	Negative discharge coefficient
dpumax	Exchange level as used by the computational core
ds1d	Geometrical length of the line (used to calculate gradient)
ds1d_half	Distance from start of the line to the velocity point (relevant for embedded flowlines only)
flod	Obstacle height at cross-section (2D).
flou	Obstacle height at cross-section (2D).
invert_level_end_point	Invert level at the end of the line
invert_level_start_point	Invert level at the start of the line
kcu	See Line types
lik	Refinement level, 1 being the smallest cell. For internal use only.
line	IDs of start and end nodes
line_coords	Coordinates of the start and end nodes
line_geometries	(Relevant part of the) geometry of this element as set in the schematisation.
sewerage	Is this part of a sewer system?
sewerage_type	Sewerage type
zoom_category	Zoom category

Line types

The KCU value defines the line type. To describe these values to a string representation you can use the KCUDescriptor.

class threedigrid.admin.utils.KCUDescriptor(*arg, **kw)

A dictionary-like object that provides human readable descriptions for threedicore kcu codes:

'1d embedded line',
'1d isolated line',
'1d connected line',
'1d long-crested structure',
'1d short-crested structure',
'1d double connected line',
'1d2d single connected line with storage',
'1d2d single connected line without storage',
'1d2d double connected line with storage',
'1d2d double connected line without storage',
'1d2d connected line possible breach',
'1d2d connected line active breach',
'1d2d groundwater link',
'1d2d groundwater link # diff to 57? ',
'2d line',
'2d obstacle (levee) line',
'2d vertical link',
-150: '2d groundwater link',
'2d boundary',
'2d boundary',
'2d boundary',
'2d boundary',
'2d groundwater boundary',
'2d groundwater boundary',
'2d groundwater boundary',
'2d groundwater boundary',

get(item): Return the value for key if key is in the dictionary, else default.

keys(): Return keys

values() → an object providing a view on D's values

Channels

Channels have the following attributes, additional to the ones inherited from Lines:

Variable name	Description
calculation_type	Calculation type
code	Code as set in the schematisation
connection_node_end_pk	Connection node end ID
connection_node_start_pk	Connection node start ID
discharge_coefficient	Discharge coefficient
dist_calc_points	Calculation point distance

Culverts

Culverts have the following attributes, additional to the ones inherited from Lines:

Variable Name	Description
calculation_type	Calculation type
code	Code as set in the schematisation
connection_node_end_pk	Connection node end ID
connection_node_start_pk	Connection node start ID
cross_section_height	Cross-section height
cross_section_shape	Cross-section shape
cross_section_width	Cross-section width
display_name	Display name as defined in the schematisation
dist_calc_points	Calculation point distance
friction_type	Friction type
friction_value	Friction value

Orifices

Orifices have the following attributes, additional to the ones inherited from Lines:

Variable Name	Description
connection_node_end_pk	Connection node end ID
connection_node_start_pk	Connection node start ID
crest_level	Crest level
crest_type	Crest type
display_name	Display name as defined in the schematisation
friction_type	Friction type
friction_value	Friction value
sewerage	Is this orifice part of the sewer system?

Pipes

Pipes have the following attributes, additional to the ones inherited from Lines:

Variable Name	Description
calculation_type	Calculation type
connection_node_end_pk	Connection node end ID
connection_node_start_pk	Connection node start ID
cross_section_height	Cross-section height
cross_section_shape	Cross-section shape
cross_section_width	Cross-section width
discharge_coefficient	Discharge coefficient
display_name	Display name as defined in the schematisation
friction_type	Friction type
friction_value	Friction value
material	Pipe material
sewerage_type	Sewerage type

Weirs

property Weirs.line_coord_angles

Weirs have the following attributes, additional to the ones inherited from Lines:

Variable Name	Description
code	Code as set in the schematisation
connection_node_end_pk	Connection node end ID
connection_node_start_pk	Connection node start ID
crest_level	Crest level
crest_type	Crest type
cross_section_height	Cross-section height
cross_section_shape	Cross-section shape
cross_section_width	Cross-section width
display_name	Display name as defined in the schematisation
friction_type	Friction type
friction_value	Friction value
sewerage	Is this weir part of a sewer system?

Nodes

property Nodes.added_calculationnodes

property Nodes.locations_2d

property Nodes.connectionnodes

property Nodes.manholes

The Nodes class is parent to a number of child classes:

AddedCalculationNodes
Cells
ConnectionNodes
Manholes

Note

The Nodes child class EmbeddedNodes is intended for internal use only.

Nodes have the following attributes:

Variable Name	Description
calculation_type	Calculation type
cell_coords	Cell coordinates
content_pk	Connection node ID
coordinates	Node coordinates
dimp	Impervious surface level (interflow)
dmax	Bottom level. May differ from Manhole.bottom_level e.g. if all pipes connected to this node have a higher invert level. For 2D: elevation of lowest pixel in the cell.
drain_level	Drain level as defined in the schematisation. May be different from the actual exchange level (see Lines.dpumax). Only relevant if models is purely 1D. In all other cases, use Lines.dpumax).
initial_waterlevel	Initial water level as defined in the schematisation.
is_manhole	Is this node a manhole
node_type	Node type
seq_id	Deprecated
storage_area	Storage area as defined in the schematisation. May be different from the actual/total storage area (see Nodes.sumax)
sumax	Maximum surface area (wet surface area when entire cell/node is wet)
zoom_category	Zoom category

AddedCalculationNodes

AddedCalculationNodes are 1D nodes that are created in between connection nodes if the schematisation object (e.g. Channel) is longer than the calculation point distance.

They have the same attributes as Nodes.

Cells

Cells are 2D nodes.

property Cells.bounds

Returns:: coordinates of the cell bounds (counter clockwise): minx, miny, maxx, miny, maxx, maxy, minx, maxy

Cells.get_id_from_xy(x, y, xy_epsg_code=None, subset_name=None)

Parameters:

x – the x coordinate in xy_epsg_code
y – the y coordinate in xy_epsg_code
subset_name – filter on a subset of cells

Returns:

numpy array with cell id’s for x, y

Cells.get_ids_from_pix_bbox(bbox, subset_name='2D_OPEN_WATER')

Parameters:

x – the x coordinate in xy_epsg_code
y – the y coordinate in xy_epsg_code
subset_name – filter on a subset of cells

Returns:

numpy array with cell id’s for x, y

Cells.get_nodgrid(pix_bbox, subset_name='2D_OPEN_WATER')

Cells.get_extent_pixels()

Determine the extent of the cells (in pixels)

The returned bounding box is left-inclusive; cells cover the the half-open intervals [xmin, xmax) and [ymin, ymax).

Returns:: tuple of xmin, ymin, xmax, ymax or None

Cells.iter_by_tile(width, height)

Iterate over groups of cells given a tile shape (in pixels).

The tiles are always aligned to pixel (0, 0) so that a single grid cell never overlaps with multiple tiles. For the the same reason, the tile size should be an integer multiple of the maximum cell size.

Parameters:

width – the width of the tile in pixels
height – the height of the tile in pixels

Yield:

(xmin, ymin, xmax, ymax), cells

Cells have the following attributes, additional to the ones inherited from Nodes:

Variable Name	Description
has_dem_averaged	Has DEM averaging been used in this cell?
pixel_coords	Location (index) of the lower left corner and upper right in pixels from DEM origin (1-based)
pixel_width	Pixel size
z_coordinate	Elevation of lowest pixel in the cell. Equal to Node.dmax

ConnectionNodes

ConnectionNodes have the same attributes as Nodes. They are Nodes at locations where a Connection node is present in the schematisation (as opposed to 2D nodes or nodes that are added e.g. along a channel with a smaller calculation point distance than length.

Manholes

Manholes have the following attributes, additional to the ones inherited from Nodes:

Variable Name	Description
bottom_level	Bottom level as defined in the schematisation. For the bottom level used in the calculation, see Nodes.dmax
display_name	Display name as defined in the schematisation
manhole_indicator	Manhole indicator as defined in the schematisation
shape	Manhole shape as defined in the schematisation
surface_level	Surface level as defined in the schematisation
width	Manhole width as defined in the schematisation

Pumps

Pumps have the following attributes:

Variable Name	Description
bottom_level	Bottom level of the start node
capacity	Pump capacity
content_pk	ID of the source record in the schematisation
coordinates	Coordinates is the centroid of node_coordinates if both are set, else the one that is set.
display_name	Display name as defined in the schematisation
lower_stop_level	Pump lower stop level
node_coordinates	`[[node1_x], [node1_y], [node2_x], [node2_y]]` `-9999` if nodeX_id is -9999
node1_id	Start node id
node2_id	End node id
start_level	Pump start level
type	Pump type
zoom_category	Zoom category