API reference

pyorc’s API consists of several subclasses of the xarray.Dataset and xarray.DataArray data models. In a nutshell, xarray’s data models are meant to store and analyze scientific datasets with multiple dimensions. A xarray.DataArray contains one variable with possibly several dimensions and coordinates within those dimensions. A xarray.Dataset may contain multiple xarray.DataArray objects, with shared coordinates. In pyorc typically the coordinates are time for time epochs measured in seconds since the beginning of a video, x for horizontal grid spacing (in meters), y for vertical grid spacing (in meters). Operations you can apply on both data models are very comparable with operations you may already use in pandas, such as resampling, reindexing, aggregations, and so on.

Note

We highly recommend to use the excellent xarray manual side-by-side with pyorc to understand how to effectively work with the xarray ecosystem.

In the remaining sections, we describe the API classes, and the functions they are based on.

CameraConfig class

Class and properties

CameraConfig(height, width[, crs, ...])	Camera configuration containing information about the perspective of the camera.
CameraConfig.bbox	Give geographical bbox fitting around corners points of area of interest in camera perspective.
CameraConfig.shape	Return rows and columns in projected frames from Frames.project.
CameraConfig.transform	Returns Affine transform of projected frames from Frames.project.

Setting of properties and attributes

CameraConfig.set_bbox_from_corners(corners)	Establish bbox based on a set of camera perspective corner points.
CameraConfig.set_gcps(src, dst, z_0[, ...])	Set ground control points for the given CameraConfig.
CameraConfig.set_lens_pars([k1, c, focal_length])	Set the lens parameters of the given CameraConfig.
CameraConfig.set_intrinsic([camera_matrix, ...])	Set lens and distortion parameters.
CameraConfig.set_lens_calibration(fn[, ...])	Calibrate and set the properties camera_matrix and dist_coeffs using a video of a chessboard pattern.
CameraConfig.set_lens_position(x, y, z[, crs])	Set the geographical position of the lens of current CameraConfig.

Exporting

CameraConfig.to_dict()	Return the CameraConfig object as dictionary.
CameraConfig.to_dict_str()	Convert the current instance to a dictionary with all values converted to strings.
CameraConfig.to_file(fn)	Write the CameraConfig object to json structure.
CameraConfig.to_json()	Convert CameraConfig object to string.

Retrieve geometrical information

CameraConfig.estimate_lens_position()	Estimate lens position from distortion and intrinsec/extrinsic matrix.
CameraConfig.get_M([h_a, to_bbox_grid, reverse])	Establish a transformation matrix for a certain actual water level h_a.
CameraConfig.get_bbox([camera, mode, h_a, ...])	Get bounding box.
CameraConfig.get_dist_shore(x, y, z[, h_a])	Retrieve depth for measured bathymetry points.
CameraConfig.get_dist_wall(x, y, z[, h_a])	Retrieve distance to wall for measured bathymetry points.
CameraConfig.get_depth(z[, h_a])	Retrieve depth for measured bathymetry points.
CameraConfig.get_z_a([h_a])	Get actual water level measured in global vertical datum (+z_0) from water level in local datum (+h_ref).
CameraConfig.project_grid(xs, ys, zs[, ...])	Project gridded coordinates to col, row coordinates on image.
CameraConfig.project_points(points[, ...])	Project real world x, y, z coordinates into col, row coordinates on image.
CameraConfig.unproject_points(points, zs)	Reverse projects points in [column, row] space to [x, y, z] real world.
CameraConfig.z_to_h(z)	Convert z coordinates of bathymetry to height coordinates in local reference (e.g.
CameraConfig.h_to_z(h_a)	Convert z coordinates of bathymetry to height coordinates in local reference (e.g.
CameraConfig.estimate_lens_position()	Estimate lens position from distortion and intrinsec/extrinsic matrix.

Plotting methods

CameraConfig.plot([figsize, ax, tiles, ...])	Plot geographical situation of the CameraConfig.
CameraConfig.plot_bbox([ax, camera, mode, ...])	Plot bounding box.

CrossSection class

The CrossSection class is made to facilitate geometrical operations with cross sections. It can be used to guide water line detection methods, estimate the water level and possibly other optical methods conceived by the user, that require understanding of the perspective, jointly with a measured cross section.

To facilitate geometric operations, most of the geometric properties are returned as shapely.geometry objects such as Point, LineString and Polygon.

This makes it easy to derive important flow properties such as wetted surface [m2] and wetted perimeter [m].

Class and properties

CrossSection(camera_config, cross_section)	Water Level functionality.
CrossSection.cs_points	Return cross-section as list of shapely.geometry.Point.
CrossSection.cs_points_sz	Return cross-section perpendicular to flow direction (SZ) as list of shapely.geometry.Point.
CrossSection.cs_linestring	Return cross-section as shapely.geometry.Linestring.
CrossSection.cs_linestring_sz	Return cross-section perpendicular to flow direction (SZ) as shapely.geometry.Linestring.
CrossSection.cs_angle	Average angle orientation that cross-section makes in geographical space.
CrossSection.idx_closest_point	Determine index of point in cross-section, closest to the camera.
CrossSection.idx_farthest_point	Determine index of point in cross-section, farthest from the camera.

Getting cross section geometries

CrossSection.get_cs_waterlevel(h[, sz])	Retrieve LineString of water surface at cross-section at a given water level.
CrossSection.get_csl_point([h, l, camera, ...])	Retrieve list of points, where cross-section (cs) touches the land (l).
CrossSection.get_csl_line([h, l, length, ...])	Retrieve waterlines over the cross-section, perpendicular to the orientation of the cross-section.
CrossSection.get_csl_pol([h, l, length, ...])	Get horizontal polygon from cross-section land-line towards water or towards land.
CrossSection.get_bottom_surface([length, ...])	Retrieve a bottom surface polygon for the entire cross section, expanded over a length.
CrossSection.get_planar_surface(h[, length, ...])	Retrieve a planar water surface for a given water level, as a geometry.Polygon.
CrossSection.get_wetted_surface(h[, camera, ...])	Retrieve a wetted surface for a given water level, as a geometry.Polygon.
CrossSection.get_wetted_surface_sz(h)	Retrieve a wetted surface perpendicular to flow direction (SZ) for a water level, as a geometry.Polygon.
CrossSection.get_line_of_interest([bank])	Retrieve the points of interest within the cross-section for water level detection.

Plotting methods

The plotting methods consist of a number of smaller methods, as well as one overarching CrossSection.plot method, that combines the smaller methods. The plotting functions are meant to provide the user insight in the situation on a site. All methods can be combined with the parallel plotting method for camera configurations CameraConfig.plot.

CrossSection.plot([h, length, offset, ...])	Plot the cross-section situation.
CrossSection.plot_cs([ax, camera, swap_y_coords])	Plot the cross section.
CrossSection.plot_planar_surface(h[, ...])	Plot the planar surface for a given water level.
CrossSection.plot_bottom_surface([length, ...])	Plot the bottom surface for a given water level.
CrossSection.plot_wetted_surface(h[, ...])	Plot the wetted surface for a given water level.

Water level detection

Combined with a preprocessed image from e.g. a video file, a water level can be detected.

CrossSection.detect_water_level(img[, bank, ...])

Detect water level optically from provided image.

Video class

Class and properties

Video(fn[, camera_config, h_a, start_frame, ...])	Video class for reading and extracting data from video files.
Video.camera_config	Get CameraConfig object attached to Video instance.
Video.end_frame	int, last frame considered in analysis
Video.fps	float, frames per second
Video.frames	Get frames of Video instance.
Video.freq	Get video sampling frequency.
Video.h_a	Actual water level [m] during video
Video.lazy	Get lazy flag.
Video.mask	Get region mask for stabilization.
Video.rotation	Get rotation code.
Video.stabilize	Get stabilization region coordinates.
Video.start_frame	int, first frame considered in analysis
Video.corners	list of 4 lists (int) with [column, row] locations of area of interest in video objective

Setting properties

Video.set_mask_from_exterior(exterior)

Prepare a mask grid with 255 outside of the stabilization polygon and 0 inside.

Getting frames from video objects

Video.get_frame(n[, method])	Retrieve one frame.
Video.get_frames([method])	Get a xr.DataArray, containing a dask array of frames, from start_frame until end_frame.
Video.get_frames_chunk(n_start, n_end[, method])	Retrieve a chunk of frames in one go.
Video.get_ms(cap[, split])	Get stabilization transforms for each frame based on analysis of stable points outside of water area.

Frames subclass

These methods can be called from an xarray.DataArray that is generated using pyorc.Video.get_frames.

Class and properties

Frames(xarray_obj)	Frames functionalities that can be applied on xr.DataArray.
Frames.camera_config	Camera configuration belonging to the processed video.
Frames.camera_shape	Shape of the original camera objective of the processed video (e.g.
Frames.h_a	Actual water level belonging to the processed video.

Enhancing frames

Frames.edge_detect([wdw_1, wdw_2])	Highlight edges of frame intensities, using a band convolution filter.
Frames.minmax([min, max])	Minimum / maximum intensity filter.
Frames.normalize([samples])	Remove the temporal mean of sampled frames.
Frames.reduce_rolling([samples])	Remove a rolling mean from the frames.
Frames.smooth([wdw])	Smooth each frame with a Gaussian kernel.
Frames.time_diff([thres, abs])	Apply a difference over time.

Projecting frames to planar views

Frames.project([method, resolution, reducer])

Project frames into a projected frames object, with information from the camera_config attr.

Retrieving surface velocities from frames

Frames.get_piv([window_size, overlap, engine])

Perform PIV computation on projected frames.

Visualizing frames

Frames.plot([ax, mode])	Create QuadMesh plot from a RGB or grayscale frame on a new or existing (if ax is not None) axes.
Frames.to_ani(fn[, figure_kwargs, ...])	Store an animation of the frames in the object.
Frames.to_video(fn[, video_format, fps, ...])	Write frames to a video file without any layout.

Velocimetry subclass

These methods can be called from an xarray.Dataset that is generated using pyorc.Frames.get_piv.

Class and properties

Velocimetry(xarray_obj)	Velocimetry functionalities that can be applied on xarray.Dataset.
Velocimetry.camera_config	Camera configuration belonging to the processed video.
Velocimetry.camera_shape	Shape of the original camera objective of the processed video (e.g.
Velocimetry.h_a	Actual water level belonging to the processed video.
Velocimetry.is_velocimetry	Check if the data contained in the object seems to be velocimetry data.

Temporal masking methods

The mask methods below either require or may have a dimension time in the data. Therefore they are most logically applied before doing any reducing over time.

Velocimetry.mask.minmax([s_min, s_max])	Masks values if the velocity scalar lies outside a user-defined valid range.
Velocimetry.mask.corr([tolerance])	Masks values with too low correlation
Velocimetry.mask.angle([angle_expected, ...])	filters on the expected angle.
Velocimetry.mask.rolling([wdw, tolerance])	Masks values if neighbours over a certain rolling length before and after, have a significantly higher velocity than value under consideration, measured by tolerance.
Velocimetry.mask.outliers([tolerance, mode])	Mask outliers measured by amount of standard deviations from the mean.
Velocimetry.mask.variance([tolerance, mode])	Masks locations if their variance (std/mean in time) is above a tolerance level for either or both x and y direction.
Velocimetry.mask.count([tolerance])	Masks locations with a too low amount of valid velocities in time, measured by fraction with tolerance.

Spatial masking methods

The spatial masking methods look at a time reduced representation of the grid results. The resulting mask can be applied on a full time series and will then mask out grid cells over its full time span if these do not pass the mask.

Velocimetry.mask.window_mean([tolerance, ...])	Masks values when their value deviates more than tolerance (measured as relative fraction) from the mean of its neighbours (inc.
Velocimetry.mask.window_nan([tolerance, wdw])	Masks values if their surrounding neighbours (inc.

Data infilling

Velocimetry.mask.window_replace([wdw, iter])

Replaces values in a certain window size with mean of their neighbours.

Getting data over transects

Velocimetry.get_transect(x, y[, z, s, crs, ...])	Interpolate all variables to supplied x and y coordinates of a cross-section.
Velocimetry.set_encoding([enc_pars])	Set encoding parameters for all typical variables in a velocimetry dataset.

Plotting methods

Velocimetry.plot	alias of _Velocimetry_PlotMethods
Velocimetry.plot.pcolormesh(x, y[, s, ax])	Create pcolormesh plot from velocimetry results on new or existing axes.
Velocimetry.plot.scatter(x, y[, c, ax])	Create scatter plot of velocimetry or transect results on new or existing axes.
Velocimetry.plot.streamplot(x, y, u, v[, s, ...])	Create streamplot of velocimetry results on new or existing axes.
Velocimetry.plot.quiver(x, y, u, v[, s, ax])	Create quiver plot from velocimetry results on new or existing axes.

Transect subclass

These methods can be called from an xarray.Dataset that is generated using pyorc.Velocimetry.get_transect.

Class and properties

Transect(xarray_obj)	Transect functionalities that can be applied on xarray.Dataset.
Transect.camera_config	Camera configuration belonging to the processed video.
Transect.camera_shape	Shape of the original camera objective of the processed video (e.g.
Transect.h_a	Actual water level belonging to the processed video.

Derivatives

Transect.vector_to_scalar([v_x, v_y])	Set "v_eff" and "v_dir" variables as effective velocities over cross-section, and its angle.
Transect.get_xyz_perspective([trans_mat, ...])	Get camera-perspective column, row coordinates from cross-section locations.
Transect.get_depth_perspective(h[, ...])	Get line (x, y) pairs that show the depth over several intervals in the wetted part of the cross section.
Transect.get_bottom_surface_z_perspective(h)	Return densified bottom and surface points, warped to image perspective.
Transect.get_transect_perspective([h, ...])	Get row, col locations of the transect coordinates.
Transect.get_wetted_perspective(h[, sample_size])	Get wetted polygon in camera perspective.

River flow methods

Transect.get_river_flow([q_name, discharge_name])	Integrate time series of depth averaged velocities [m2 s-1] into cross-section integrated flow [m3 s-1].
Transect.get_q([v_corr, fill_method])	Integrated velocity over depth for quantiles of time series.

Plotting methods

Transect.plot	alias of _Transect_PlotMethods
Transect.plot.quiver(x, y, u, v[, s, ax])	Create quiver plot from velocimetry results on new or existing axes.
Transect.plot.scatter(x, y[, c, ax])	Create scatter plot of velocimetry or transect results on new or existing axes.