For many use cases, a user may require to extract velocities over a certain transect. The most famous application for this is measuring river flow. pyorc is equipped with very smart approaches to extract a transect, interpolate missing values that may appear on the transect, and extracting cross-section cubic meter per second river flow estimates with confidence intervals based on temporal variations in velocities. It is highly recommended to consider applying masks on your results before extracting velocities and flow over transects.
Extracting a transect#
The starting point for a transect is always a velocimetry result, containing surface velocities, gridded in space and
time and a set of coordinates of a cross section, measured in the same coordinate reference system as the ground control
points and using also the same vertical datum as the measurement of the control video water level (
z_0 in the
Transects can be derived by supplying a
transect section in your recipe. Under this section, one or several
transects can be derived, by supplying the path to a shapefile or geojson file, that contains x, y, z Point
coordinates of the measured cross section as well as the coordinate reference system of the coordinates.
Any metadata or properties are not used. These files are typical outputs of GNSS equipment and can one on
one be passed onto pyorc unless you wish to remove some wrong points, or points that belong to another survey.
The approach is best explained with an example
transect section for one transect, with some comments
# we start our transect section
# extracted transects will be written to disk
# we have measured one cross section in the Ngwerere river in Lusaka - Zambia
# path to the shapefile or geojson, containing our points
# supply some extra arguments to get_transect (if not provided, defaults will be used)
# we do a rolling mean over time to smooth out small fps changes of the camera
# we sample velocity by averaging in a one-sided window size of 2 (5x5)
# let's derive depth integrated velocity also
# we fill missing with a log interpolation method
# assume depth averaged velocity is 0.85 * surface velocity
# integrate to m3/s river flow without additional arguments
get_transect is not supplied in the command-line recipe then default parameters will be used. When
write: True is provided, the resulting extracted velocities and flow will be written to a file in the
output folder. This file will have the following naming convention:
transect_<name>.nc. From the example
above the file would be called
You may load x, y, z points from a shapefile or csv file with
geopandas. Then these can be
supplied with a velocimetry result, using the
get_transect method. Below a full working example is given, based
on our Ngwerere example dataset.
cross_section = pd.read_csv("ngwerere/ngwerere_cross_section.csv")
# the points are assigned to numpy arrays, coordinates are in crs 32735
x = cross_section["x"]
y = cross_section["y"]
z = cross_section["z"]
# extract points, ensuring pyorc knows their projection is 32735.
ds_points = ds.velocimetry.get_transect(x, y, z, crs=32735, rolling=4)
# add depth averaged velocity, filling missings and assuming a average velocity / surface velocity of 0.85
ds_points_q = ds_points.transect.get_q(fill_method="log_interp", v_corr: 0.85)
# finally, obtain cross sectional river flow (added as variable ["river_flow"])
get_transect method derives the transect from our gridded velocimetry results. Many options
may be supplied to improve sampling. For instance, if flow has a highly predominant direction, then it makes
sense to increase sampling over a longer longitudinal window, and reduce sampling in perpendicular direction.
This can be controlled by arguments
There are also options to refine or coarsen the sampling interval over space (
distance) as well as an option to
discard values if not enough valid (i.e. non masked) values in the sampled neighbourhood are found (
For a full list of parameters, please investigate the API documentation.
get_river_flow are not
mandatory to use, but recommended if river flow is the required variable of interest. Since river flow requires
estimates of velocities without any gaps, fill methods are available that can be applied before the depth averaged
velocity is derived. The relevant API pages that describe the possible input arguments for both are described
here. Stored results in a NetCDF structure will contain the following variables:
v_eff_nofill: the effective velocities per point in the cross section [m/s]
get_qis supplied, this will contain velocities, with gaps filled with a selected filling method within the
v_dir: the direction of the velocity per point in the cross section determined as the perpendicular direction of the supplied cross section. Note that if the cross section is not entirely straight, this may vary from point to point.
q_nofill: depth integrated velocity [m2/s], using a correction factor supplied with
q: same as
v_effbut then for depth integrated velocity.
river_flow: available when both
get_river_floware applied. This variable contains the river flow in m3/s.
In the processing to transects, the
time dimension will be replaced by a
quantile dimension. By default 5
quantiles are derived (0.05, 0.25, 0.5, 0.75, and 0.95) for each point in the transect based on the time variability of
the extracted velocities. These quantiles allow you to estimate the variance of the velocities. A very high variance
may indicate more uncertainty. Note that this variance is also integrated into the
river_flow variable, assuming the
variability is entirely correlated in space. This is likely not to be true, especially if variances are caused by
remaining variability in the frames-per-second of the camera, hence the confidence intervals of the
variable should be interpreted as highly conservative.