Confluence Retirement

In an effort to consolidate USGS hosted Wikis, the myUSGS Confluence service is targeted for retirement on January 28, 2022. The official USGS Wiki and collaboration space is now SharePoint. Please migrate existing spaces and content to the SharePoint platform and remove it from Confluence at your earliest convenience. If you need any additional information or have any concerns about this change, please contact Thank you for your prompt attention to this matter.
Skip to end of metadata
Go to start of metadata

See also:


Since RIVeR is a compiled freeware made in the Matlab environment you should: 

  1. Download and install the Matlab Runtime version #R2015a (64-bit)
  2. Download the latest version of RIVeR

  3. RIVeR uses results from image velocimetry software like PIVlab and PTVlab. For this example, we will only use PIVLab. Both programs are open-source software available on the Matworks file exchange platform as source code. You must have a Matlab license in order to use them otherwise you can always contact me for a compiled version.
  • File location/structure: Because the software doesn't like long pathnames or spaces, I put my files on my C-drive as follows. Note the programs are in the upper level file with folders containing individual videos, reference point lengths, and cross-section information. Navigate to: C:\LSPIV (Location of files on L. Bohman Computer)

  • Decide on a 10-sec cut of a longer video (an entire video should be 30-60 seconds)
  • Open River 2.2 (RIVeR_GUI) (circled in yellow above). This may take a while….
  • FileExtract Images From File (note that filenames CANNOT have imbedded spaces)
  • Click on the target video file, then OPEN.
  • Decide on fps (want 15 -25 pixels displacement per pair of images)
    • Example: Let's say your video was taken at 30 frames per second and your images each have a resolution of 1920x1080 pixels and is about 4 inches tall on your computer screen. So you'll have 1080/4 = 270 pixels/in.
    • Want 15-25 pixels of movement between consecutive frames, approximately. So, assuming we want 25 pixels of movement, you'd want 25/270 = .09 in or about 0.1 inch of movement between sampling frames. You could even print a ruler on regular paper (which is pretty transparent when held on the screen) to be sure displacement is enough.
    • So watching seeded material or object on the surface in your video (frame by frame), if it moved 0.1 inch in over 10 frames, you'd want to use every 10th frame. Since the video was shot at 30 frames/sec, using every 10th frame would give you 30/10 = 3 frames per sec sampling interval (sampling interval would be 333 milliseconds). For this example, select "3" for fps (resample).
    • If the water was moving twice as fast and only took 5 frames to move 1/10th of an inch, you might decide on 30/5 = 6 frames per second (every 5th frame).
    • I was told this decision is probably not critical (if you have time…experiment). But, for the IP (Internet Protocol) cams, don't go higher than 10 fps…this works for like 99% of our cases.
  • Select which part of the video you want to use. If you had a 17-second video and wanted 10 seconds, you might select seconds 5 to 15. Make that selection.
  • Selecting either Grayscale or Color are equally okay but sometimes using grayscale helps with contrast. Using Grayscale purportedly increases processing times. Actually, PIVLab will convert to grayscale in the background even if you don't. I often process in color so I can see what I'm doing better.
  • Click on "Extract Frames" You'll note the directory with the video now has 32 still frames.
  • Open up the PIVlab software (circled in blue above). Leave RIVeR GUI open on your screen. Again, it may take a while to appear.
  • FileNew session
  • Load Images (button on upper right). Navigate to FOLDER where sampled images exist.

  • Click Add
  • Select the following sequencing style: 1-2,2-3,3-4. FYI, the other sequence style is used for "classical PIV" which traditionally had 2 cams that were time synced to take pics one after the other (because they couldn't go as fast with 1 cam). That's less important/irrelevant with one camera, and our applications.
  • Select Import. The image list on the panel on the right side displays the images that you selected. The letters 'A' & 'B' denote the first and the second image of one image pair (= one "frame"). In the lower right corner, you will find a slider to navigate through all frames, and a button (Toggle A/B) to toggle between the individual images within one frame.
  • Analysis settingsExclusions (ROI, Mask). You don't have to have an ROI or Masks, but it will dramatically speed up processing if you exclude "not water". Also, if you don't specify ROI/Mask, you can, and likely will get velocity vectors in regions where there is not water.
  • Select ROI (region of interest) and then draw a box that encompasses all your reference points (see blue-dash area below). Use "Clear ROI" if you make a mistake and want to re-draw.
  • Click on Draw Mask for current frame – each mask should follow the water-ground interface and should also extend outside the box drawn in the last step…see pink area of next photo. Double-clicking will close the loop. Repeat this step for the other bank (one mask for each bank).

  • Click on Apply Mask(s) to Frames (1;end)(you won't notice any action)
  • Analysis SettingsImage Pre-processing… Contrast-limited adaptive histogram equalization (CLAHE) is enabled by default. This filter locally enhances the contrast in the images. Highpass filtering is also commonly used. Play around with the settings to see how the filters affect the image. Your goal is to produce an image with as much contrast of the moving bits in each Frame as possible. For now, enable CLAHE (20 pix window) and highpass filtering (15 pix window).
  • Preview Current Frame (will get result as shown below):

  • Analysis SettingsPIV Settings -- to setup the cross-correlation for your image data. PIVlab features two different correlation algorithms, DCC (single pass direct cross correlation) and FFT window deformation (direct Fourier transform correlation with multiple passes and deforming windows).
  • Leave FFT window deformation in PIV algorithm box checked as is. Using this algorithm, your data will be analyzed in several passes: The first pass uses relatively large interrogation areas to calculate the displacement of your image data reliably. The larger the interrogation areas, the better the signal-to-noise ratio, and the more robust is the cross correlation. But large interrogation areas will only give a very low vector resolution ("vectors per frame"). That is why you should decrease the size of the interrogation windows in the following passes. The displacement information of the first pass is used to offset the interrogation areas in the second pass and so on. This procedure yields a high vector resolution, a high signal-to-noise ratio, and a high dynamic velocity range. Start with big interrogation areas (e.g. 128 pixels) and decrease gradually in the following passes (e.g. 64 pixels in pass 2).
  • Change Pass 1 from 64 128 and 32  64 so about 50%
    • Want displacement to be half the interrogation area (or less)
  • Pass Good. I have found that in most videos of rivers, I seem to get good results with 3 passes, 256, 128, 64
    I think this works because in most cases, the scale of rivers and height above them we take video is pretty similar. Not sure it's worth pointing out in your webex, since really it's anecdotal so far2 (divide first pass nos. by 2). The pictures below show the interrogation areas before (64:32) AND after (128:64).

In most videos of rivers, one can get good results with 3 passes, 256, 128, 64. I think this works because in most cases, the scale of rivers and height above them we take video is pretty similar.

  • Analysis►Analyze►click on Analyze Current Frame (wait…won't see filter anymore)

  • Plot►Modify Plot Appearance►change the vector scale first no. to 15 or 20 to see nos. (I used 10)

  • Analysis ► Analyze ► click on Analyze All Frames (this may take a while. If you have 3 fps and 10 seconds of video, that's 30 images to process….% done is provided)
  • Post Processing ► Vector Validation
  • Check the box that says Display All Frames in Scatterplot
  • Click on Select Velocity Limits
  • Draw box around the most dense part of the data-point cluster(left click – hold – release):

  • Click on Apply to All Frames button (wait, % done displayed)

  • PlotDerive Parameters/Modify Data then click on the Calculate Mean Vectors button.  In Calculate Means table, enter "1:end" in the field "Used frames to calculate mean" and click Calculate mean vectors button. Now, an additional frame will be automatically added to your session. All masks of the frames you used to calculate this average will be combined. Vectors will be orange in the average frame, if more than half of the original vectors at that spot were interpolated before.

  • FileSave ► PIVLAB session. It is recommended to save the session in the same folder as the images. The resulting calculations consist of matrices or vectors of displacement for each pair of analyzed images.
  • Go back to the RIVeR_GUI window by clicking at the top
  • WorkflowLoad PIV/PTV AnalysisLoad PIVLAB/PTVLAB Session
  • Browse to folder and select the appropriate PIVLAB session, select it, and click on "Open".
  • WorkflowLoad Background Image. RIVeR doesn't rectify the original images. It rectifies the results processed with PIVlab/PTVlab on the original images. However, in order to display the rectified results, a single image will be used as background. You can either pick one or make one automatically.
  • Click on the Automatic button (won't notice anything happen). This works by taking the average of the first 10 images in the folder where the session was saved. If there is moving things, like the water for our cases, that will appear "motion blurred", while the banks will stay approximately unchanged
  • WorkflowLoad CPS Image. In order to rectify the results, points with known coordinates in the real world need to be visible on the image. Those points are called Control Points (CPs), also known as Ground Reference Points. Thus, in order to rectify the results from the image processing, (at least) 4 four known CPs must be defined at the water surface plane. It should be noted that the CPs must not be co-aligned. In this example we will see how to use only 4 CPs that are in the same plane for results rectification.
  • pick/click on first image, Open (again, nothing will be apparent)
  • WorkflowDefine CPS in 2D planeDefine Distances If Only 4 CPs
  • You get to pick four (4) CPs on the image. It is preferred to select them counterclockwise beginning with the CP on the left upstream bank. CPs are selected with the right click where the CP intersects the water surface and you can zoom with left click (I've noted that zooming sometimes confuses the program so zoom only if necessary and mark the location in the un-zoomed photo). I always close the loop. Once you have the 4 points, you can press enter, which is what you are doing I think. That effectively closes the loop also (it absolutely does behind the scenes in the program).

  • Do you want to load lengths between CPs? ► answer Yes. It is possible to import the lengths from a excel file (see next bullet) or fill them manually in the window. Select "Ok" when all the lengths are entered.
  • Specify the Excel file or fill in the distances directly in the box and click OK.
    • To select an Excel file and click on OPEN. My simple Excel file (below) had 6 lengths (upstream left going counterclockwise: 1-2-3-4, 5=1-3 and 6=2-4)

  • Click OK button when complete.
  • WorkflowDefine Region of Interest. It is necessary to select a Region Of Interest (ROI) on the image (this ROI is definitely required). It is not the same region defined in PIVlab. It doesn't have to be a rectangular shape and it is preferable to choose a slightly larger ROI than the one chosen in PIVlab in order to have some areas without motion as ground reference. Using left-clicks and going counterclockwise, build a polygon around the region you want to rectify. Double-click inside the box (or press ENTER) when you are done to close the loop. The area outside the ROI will now be shaded (see below).

  • Workflow, Define Time Step.   The time between each image is defined by the frame rate in frames per second (fps) used during the Image Extraction. It must be in milliseconds [ms] and can be calculated [EF1] as time step = 1000/fps. (500 milliseconds for 2 frames/sec, 100 milliseconds for 10 fps, 33.33 milliseconds for 30 fps, and so forth)  So enter 333 in our case. Then select  à OK.  Note this fps value is also in the text file RIVeR creates when you first extract the images (look for a file called “Images_Extraction.txt”).   It will have some text like:

Filename: DSC_0138.MOV
Extracted from: 30 s to 32 s; Total: 2 s
Resolution: 1920:1080
@ 10 fps; time step: 100 ms
Grayscale: Yes
Lens Correction: No
  • Everything has now been prepared to rectify the results. Navigate to WorkflowRectify Results. Wait for it…this will take few seconds until the background image is rectified. The results of the first image pair are plotted on the right side of the GUI interface. Now it is possible to navigate through all the results with the slider available. The last results will be the averaged velocity field. If you computed it in the Image Processing section the results number will be highlighted in green. If you don't do the Derive Mean back in PIVLab, you won't see this result.

  • WorkflowDefine Y+ Direction (drag one end of the flow direction (blue line) as needed to align with general flow direction).

  • IMPORTANTAgain ensure that you've moved the panel slider in upper right to slide all the way to right. That "Panel" area should turn green (circled above). You need to use all the frames…not just the first one, which may have erroneous velocities.
  • Cross-section selection: Now that the results are rectified, make sure that the mean results are selected (highlighted in green).
  • Cross-sectionAdd NewOn Original Image (left). Note, that it is also possible to define the cross section on the rectified image (image on the right). To locate the cross section, first left-click (and continue holding down) on the left bank, and drag to right bank, double click to end.
  • Rename section CS_A (or whatever) ► OK

  • A new window will pop up similar to the following wherein the velocity profile of the selected cross-section is plotted. Only the streamwise component (perpendicular to the section) is used for the discharge computation.

  • Bathymetry: Areacomp2 is embedded in RIVeR 2.2 to facilitate the bathymetry definition of the Cross Section. AreaComp is usually used to analyze ADCP data and compute a relation between channel area and stage for an ADCP measurement. So…one can choose to import data from an ADCP measurement or you can use comma-separated value (CSV) data files. In this example, the bathymetry from an ADCP will be imported. In the new window click on the button "AreaComp2" and a third window will popup…
  • ADCP file input for this example:
    • Areacomp2 button ► in new window: FILEImport TRDI Classic ASCII File
    • Clear all data before loading YES
    • In new window, navigate to ADCP file (ADCP.Qm.xsection.txt) ► OPEN
    • You will see two parallel lines. Change the starting station to 0.7 in the box on the left. In the station and stage table, click on ADD and enter 0,0 for the first station and elevation. Click on ADD again and enter 6.7,0 for the ending x-section station.

  • If CSV file input….
    • Areacomp2 button ► FILEImport CSV File
    • Clear All DataSelect File With Data (i.e., quebrada_bath2) ► 1 header line1OKElevations, etc., etc.

  • Whether and ADCP file or a CSV file..once your done….
  • File ► Exit Back to RIVeR
  • Areacomp will close and the bathymetry will be imported directly to RIVeR. Check the box that says Extrapolate Velocity to Edges (located in the Edit Cross Sections window)

  • The discharge is computed using the mean-section method that consists in dividing the cross-section in N adjacent verticals at an equal distance. Additionally, a coefficient between the surface velocity and the mean velocity in the water column can be used. By default this coefficient is Vm/Vs=1 but should be customized for the site. A theorieticaltheoretical value of 0.85 is typical but can range from 0.6 to 1.02. Enter 0.85 for Vm/Vs. Note that, right now, if units are consistent (cross section in ft, lengths in ft, etc., then answer will be in cfs. Example is in m3/s).
  • You should now have the answer in the upper right of the RIVeR – Edit Cross Section(s) window

  • No labels