Command line interface#
The command line interface is meant to provide an easy, reproducible and streamlined approach to perform the two main tasks required for performing a surface velocity and discharge analysis being:
Camera configuration: establishing the relationship between the field of view of the camera and the real world coordinates and defining the bounding box of the area of interest within the field of view.
Velocity and discharge processing: using the camera configuration with one or several (of different moments in time) videos of the same field of view (e.g. taken at different times) to estimate surface velocity on the area of interest and river flow over bathymetric transects.
The two tasks are available as so-called “subcommands”. You can see the available subcommands by passing
$ pyorc --help
Usage: pyorc [OPTIONS] COMMAND [ARGS]... Command line interface for pyOpenRiverCam. Options: --version Show the version and exit. --info Print information and version of PyOpenRiverCam --license Print license information for PyOpenRiverCam --debug / --no-debug --help Show this message and exit. Commands: camera-config Prepare Camera Configuration file velocimetry Estimate velocimetry
The meaning and way to use of these subcommands are explained through the rest of this user guide. Currently the
available subcommands are
velocimetry for the two tasks mentioned.
To find out more about them, you can request specific help on them on the command-line as well.
$ pyorc camera-config --help
Usage: pyorc camera-config [OPTIONS] OUTPUT Options: -V, --videofile FILE video file with required objective and resolution and control points in view [required] --crs TEXT Coordinate reference system to be used for camera configuration -f, --frame-sample INTEGER Frame number to use for camera configuration background --src TEXT Source control points as list of [column, row] pairs. --dst TEXT Destination control points as list of 2 or 4 [x, y] pairs, or at least 6 [x, y, z]. If --crs_gcps is provided, --dst is assumed to be in this CRS." --z_0 FLOAT Water level [m] +CRS (e.g. geoid or ellipsoid of GPS) --h_ref FLOAT Water level [m] +local datum (e.g. staff or pressure gauge) --crs_gcps TEXT Coordinate reference system in which destination GCP points (--dst) are measured --resolution FLOAT Target resolution [m] for ortho-projection. --window_size INTEGER Target window size [px] for interrogation window for Particle Image Velocimetry --shapefile FILE Shapefile or other GDAL compatible vector file containing dst GCP points [x, y] or [x, y, z] in its geometry --lens_position TEXT Lens position as [x, y, z]. If --crs_gcps is provided, --lens_position is assumed to be in this CRS. --corners TEXT Video ojective corner points as list of 4 [column, row] points -s, --stabilize Stabilize the videos using this camera configuration (you can provide a stable area in an interactive view). -v, --verbose Increase verbosity. --help Show this message and exit.
camera-config command is meant to create a camera configuration, stored in a file. The camera
configuration details how the camera’s perspective relates to real-world coordinates and distances, which area
within the objective should be processed, what the characteristics of the used lens are. All details can be
found in the section Camera configurations.
$ pyorc velocimetry --help
Usage: pyorc velocimetry [OPTIONS] OUTPUT Options: -V, --videofile FILE video file with required objective and resolution and control points in view [required] -r, --recipe FILE Options file (*.yml) [required] -c, --cameraconfig FILE Camera config file (*.json) [required] -p, --prefix TEXT Prefix for produced output files -h, --h_a FLOAT Water level in local vertical datum (e.g. staff or pressure gauge) belonging to video. -u, --update Only update requested output files with changed inputs or if not present on file system --lowmem Reduce memory consumption. Computation will be slower -v, --verbose Increase verbosity. --help Show this message and exit.
velocimetry command does all the processing of videos into all end products you may want. The inputs
-c (camera configuration file) and
-r (recipe file) are all required and in turn contain a
video file compatible with the provided camera configuration, and a recipe-file containing the recipe for the
processing steps. These steps may differ from location to location, or dependent on what details you wish to capture in
The processing steps that this command goes through are:
Preprocessing frames to e.g. enhance or sharpen patterns on the water that may be traceable.
Reproject the frames to a coordinate system (i.e. as if you are looking at the stream from above with known distances between pixels).
estimate surface velocity between groups of pixels.
mask out spurious velocities (can also be left out, if tracers are very prominent).
extract velocities over one or more transects and estimate river flow (only if you are interested in this).
make plots of frames, velocities and transects in the camera perspective, geographical perspective or local projection.
--update flag, you can indicate that you only want to process those parts of your recipe that
you have modified. With this option pyorc will check if any of your inputs and outputs (including the recipe
components, the input files and output files) have changed or require reprocessing because they were (re)moved. If this
is not the case then that step will be skipped. This is ideal for instance in case you only changed a plot setup or
masking step. The velocimetry part (which is time consuming) will then be skipped entirely.
You can also supply an option
--lowmem which may be useful if you work with a low memory device or very large.
With this setting, only small portions of data are processed at the same time. This therefore increases processing time,
while decreasing (sometimes severely!) the amount memory required. If pyorc crashes then this is likely due
to low memory resources. Please then try this option
The recipe file provided with
-r is a so-called Yaml formatted file (extension .yml). This is a text file with
a specific format that defines exactly what steps are being performed, and how the steps are to be performed. For
instance, the preprocessing steps can be done with different techniques, and these can be combined in substeps.
The same is true for the masking step. Several masking strategies can be performed, and this can even be done in parallel
or in series, to improve the results. The Yaml file is referred to as the recipe in the remainder of the User Guide.
A recipe file seems a lot of work to write, however, as you get used to pyorc you will notice that for many
use cases, you can simply use exactly the same or almost the same recipe throughout. For instance, for a fixed
camera, one only needs to supply a new value for
h_a (water level during video) and keep all the rest exactly
To give a first sense of a recipe, an example recipe file (also used in our examples) is displayed below.
video: start_frame: 0 end_frame: 20 h_a: 0.0 frames: normalize: edge_detect: wdw_1: 1 wdw_2: 2 minmax: min: -5 max: 5 velocimetry: get_piv: window_size: 25 write: True mask: write: True mask_group1: corr: mask_group1_2: minmax: mask_group1_3: rolling: mask_group2: outliers: mask_group3: variance: mask_group_4: count: mask_group5: window_mean: wdw: 2 tolerance: 0.5 reduce_time: True transect: write: True transect_1: shapefile: ../examples/ngwerere/cross_section1.geojson get_transect: rolling: 4 wdw: 2 get_q: fill_method: log_interp v_corr: 0.85 get_river_flow: transect_2: shapefile: ../examples/ngwerere/cross_section2.geojson get_transect: rolling: 4 wdw: 2 get_q: fill_method: log_interp v_corr: 0.85 get_river_flow: plot: plot_quiver: frames: velocimetry: alpha: 0.4 cmap: rainbow scale: 400 width: 0.0015 vmax: 0.6 transect: transect_1: cmap: rainbow scale: 200 width: 0.003 vmin: 0 vmax: 0.6 transect_2: cmap: rainbow add_colorbar: True scale: 200 width: 0.003 vmin: 0 vmax: 0.6 mode: camera reducer: mean write_pars: dpi: 100 bbox_inches: tight
If you are not used to .yml files, this may seem a little bit abstract. A few rules and hints are explained below.
A Yaml file is a text file without any formatting. Hence you may not edit it in Word or other word processors. You need to use a raw text editor to modify these. A recommended text editor for windows is notepad++_ which you can freely download and install. Set it up as default editor for files with the extension
.ymlin Windows Explorer by right clicking on a
.ymlfile in Windows Explorer and
A .yaml file consists of sections. Each section can have one or multiple sub-sections. And below each subsection you may define another set of sub-sections below that. This is very similar to numbering of report or book chapters with headings and subheadings, like Chapter 1, section 1.1, subsection 1.1.1, 1.1.2, 1.1.3. A section that has subsections is defined with a name and double colon
video:`. Subsections are defined by providing indented text below the section. You can also end these with
:and then define subsections under that with a deeper indentation level.
For indentation, you can either use the <TAB> button on your keyboard, or for instance two spaces to indent. Both is ok, but ensure you are very consistent with the indentation level. For instance, first indenting with two spaces and then with a <TAB> will give an error.
Anywhere in the file, you can add comments, by typing
#. Any text right of the
#will be interpreted as a comment. This is very useful to annotate the files and explain choices made in the file, either for yourself for later reference, to distinguish different experiments or make a colleague aware of your choices and reasoning.
In pyorc each main section has a specific name that relates to a larger processing steps. The steps that you can go through are
plot. Any other sections you would provide would simply be skipped, so carefully check your spelling if anything seems to be not working.
The options you may provide under each section, are (of course) different per section.
The details on the different steps and what you may configure are described in all other chapters of this User Guide. For quick reference you can use the links below: