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 the --help option.

$ 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 camera-config and 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.

The 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.

The velocimetry command does all the processing of videos into all end products you may want. The inputs -V (videofile), -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 your video.

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.

With the -u or --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.

Note

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.

Note

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 the same.

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 .yml in Windows Explorer by right clicking on a .yml file 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 :, e.g. 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 video, frames, velocimetry, mask, transect and 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:

How to select start and end frame of the video to work with: Videos
Working with frames, preprocessing and reprojection: Frames
Estimate surface velocity and masking: Velocimetry
Extract velocities over transects: Transects
Plotting frames, velocities and transects: Plotting