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.


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 with respect to real world coordinates


Returns geographical bbox fitting around corners points of area of interest in camera perspective


Returns rows and columns in projected frames from Frames.project


Returns Affine transform of projected frames from Frames.project

Setting of properties and attributes#


Establish bbox based on a set of camera perspective corner points Assign corner coordinates to camera configuration

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_lens_calibration(fn[, ...])

Calibrates and sets 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.



Return the CameraConfig object as dictionary


Write the CameraConfig object to json structure


Convert CameraConfig object to string

Retrieve geometrical information#

CameraConfig.get_M([h_a, to_bbox_grid, reverse])

Establish a transformation matrix for a certain actual water level h_a.

CameraConfig.get_depth(z[, h_a])

Retrieve depth for measured bathymetry points using the camera configuration and an actual water level, measured in local reference (e.g.


Convert z coordinates of bathymetry to height coordinates in local reference (e.g.

Plotting methods#

CameraConfig.plot([figsize, ax, tiles, ...])

Plot the geographical situation of the CameraConfig.

CameraConfig.plot_bbox([ax, camera, ...])

Plot bounding box for orthorectification in a geographical projection (camera=False) or the camera Field Of View (camera=True).

Video class#

Class and properties#

Video(fn[, camera_config, h_a, start_frame, ...])

Video class, inheriting parts from cv2.VideoCapture.


CameraConfig object


float, frames per second


int, last frame considered in analysis


int, first frame considered in analysis


list of 4 lists (int) with [column, row] locations of area of interest in video objective

Getting frames from video objects#

Video.get_frame(n[, method, lens_corr])

Retrieve one frame.


Get a xr.DataArray, containing a dask array of frames, from start_frame until end_frame, expected to be read lazily.

Frames subclass#

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

Class and properties#


Frames functionalities that can be applied on xr.DataArray


Camera configuration belonging to the processed video


Shape of the original camera objective of the processed video (e.g.


Actual water level belonging to the processed video

Enhancing frames#

Frames.edge_detect([wdw_1, wdw_2])

Convert frames in edges, using a band convolution filter.


Remove the mean of sampled frames.

Frames.time_diff([thres, abs])

Apply a difference over time (i.e.


Smooth each frame with a Gaussian kernel.

Projecting frames to planar views#


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

Retrieving surface velocities from frames#


Perform PIV computation on projected frames.

Visualizing frames#

Frames.plot([ax, mode])

Creates 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 functionalities that can be applied on xarray.Dataset


Camera configuration belonging to the processed video


Shape of the original camera objective of the processed video (e.g.


Actual water level belonging to the processed video

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.


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.


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.


Set encoding parameters for all typical variables in a velocimetry dataset.

Plotting methods#


alias of _Velocimetry_PlotMethods

Velocimetry.plot.pcolormesh(x, y[, s, ax])

Creates pcolormesh plot from velocimetry results on new or existing axes

Velocimetry.plot.scatter(x, y[, c, ax])

Creates scatter plot of velocimetry or transect results on new or existing axes

Velocimetry.plot.streamplot(x, y, u, v[, s, ...])

Creates streamplot of velocimetry results on new or existing axes

Velocimetry.plot.quiver(x, y, u, v[, s, ax])

Creates 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 functionalities that can be applied on xarray.Dataset


Camera configuration belonging to the processed video


Shape of the original camera objective of the processed video (e.g.


Actual water level belonging to the processed video


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([M, xs, ys, ...])

Get camera-perspective column, row coordinates from cross-section locations.

River flow methods#

Transect.get_river_flow([q_name, Q_name])

Integrate time series of depth averaged velocities [m2 s-1] into cross-section integrated flow [m3 s-1] estimating one or several quantiles over the time dimension.

Transect.get_q([v_corr, fill_method])

Depth integrated velocity for quantiles of time series using a correction v_corr between surface velocity and depth-average velocity.

Plotting methods#


alias of _Transect_PlotMethods

Transect.plot.quiver(x, y, u, v[, s, ax])

Creates quiver plot from velocimetry results on new or existing axes

Transect.plot.scatter(x, y[, c, ax])

Creates scatter plot of velocimetry or transect results on new or existing axes