VidSync News

Estimating water velocity from tracers measured in VidSync

Jason Neuswanger Thursday March 17, 2016

VidSync is often used in rivers to study the behavior of fish from a stationary camera position, and it can be useful to characterize the water velocity in the region being observed — to measure which way is downstream, how fast it's flowing, or even characterize the velocity in specific locations within the region. One way to do this with VidSync is to measure the motion of small, neutrally buoyant tracers, such as natural debris particles. On the Drift Model Project, we've found that well-soaked Israeli cous cous thrown into the river several meters upstream produces a good number of highly visible, biodegradeable tracers. 

But how many of these tracers do we need to accurately characterize the velocity at a site? Using data from the above project in which we digitized trajectories of 100 particles in each of three sites on three different rivers, I ran some randomization tests to see how many tracers we needed to approximate the "true" velocity, which was assumed to be the mean velocity of all 100 tracers.  Of course, there is no single true velocity: the current at each site really does vary constantly, both over time and at different locations within the observation region. But it is nevertheless useful to figure out how many tracers are required to get an estimate that characterizes the habitat fairly well. This characterization includes both the magnitude (current speed) and direction of the mean velocity vector.

The randomization tests involved drawing a number of tracer vectors from the full set of 100 vectors with replacement, averaging them, and comparing them to the overall average of  the original 100. The results below show the "error" (absolute difference between the randomized measurement and the "real" 100-tracer measurement) in both current speed (left column) and angle (right column) for random samples ranging from 5 to 100 tracers at three sites in different streams. The black line is the mean error and 95 % confidence band is shaded in gray.

VelocitySampleSize MeanVelocityEstimates  For this study we decided to go with 40 tracers per site, which can be digitized pretty quickly and are adequate to stabilize our estimates at values very close to the larger-sample average of 100 tracers.

Quick update to 1.63

Jason Neuswanger Saturday March 12, 2016

In the few days after making 1.60 public, I made some improvements that were worth putting out as a new version quickly. Here's what's new in 1.63:

  • I improved the distortion correction algorithm substantially by (1) adding four more high-order radial and one higher-order tangential term term to the underlying model, which especially helps with extremely wide fisheye lenses but slightly improves accuracy across the board, and (2) improved the cost function and numerical minimization algorithm that find the distortion parameters. The previous distortion correction was already pretty good, so there's no rush to redo previous analyses, but there should be some slight improvements to accuracy, especially in highly distorted footage.
  • Added diagnostics for the distortion model, and a page on this wiki describing the model and the meaning of the diagnostics, which are visible just below the distortion model parameters in the VidSync interface.
  • Added the ability to select whether to see all distortion lines on the screen (while on the distortion tab) or just the ones on the current timecode. This makes it manageable to gather plumblines from multiple different frames in the same video and maximize input to the distortion model. This is rarely if ever necessary, but it's good to have the option.
  • Added an automatic calculation of "distance to the nearest camera" for all 3-D points, which shows up in the points list on the measurement tab as well as in the spreadsheet and XML data exports.
  • Added buttons to reset just the front face or back face of the calibration frame, not just both at once. This makes it possible to correct user mistakes during calibration (such as accidentally clicking on a bunch of the wrong points) by redoing the face that was messed up, without having to redo both of them.
  • Added a "tally" button to the measurement interface that pops up a running list of the number of events for each type under a given object (for example showing the number of length measurements and foraging maneuvers for a particular fish, etc). 
  • Fixed a bug in the distortion correction display that was causing the final, straightened lines to always appear perfectly straight. Previously, it was actually just showing a straight line between the endpoints of each corrected plumbline. Now it shows both the actual corrected plumbline and a striaght line between the endpoints as a reference to indicate how much distortion remains. 
  • Updated the entire project to use the same permissive, open-source license (the MIT license) instead of a hodgepodge of outdated default copyright notices.


Updated to version 1.60

Jason Neuswanger Wednesday March 9, 2016

Version 1.60 of VidSync is now available. It fixes several minor glitches that came up in the last 1-2 versions of OS X. The new version 1.60 works well in El Capitan.

Several new features and minor bug fixes have been added since 1.55:

  • Added "instant replay" buttons to the advanced playback controls. The one for the standard playback rate goes backward 2 seconds, plays forward 2 second, and stops. You can customize the behavior for both advanced playback rate controls. These are great for re-watching animal behaviors you want to see a few times over to properly interpret.
  • All the different "play" buttons for various rates now work like "pause" buttons while the video is playing, so you can click once to start, again to stop. They don't all change to show the pause icon while playing (that would be visually annoying), but they work that way.
  • Added the ability to automatically show speeds on connecting lines, in addition to distances. These speeds are also included in spreadsheet copy/paste exports.
  • Added a "Current observer" box on the Project tab. The observer is then recorded along with all measurements and annotations, which makes it possible to figure out of two people working on the same analysis might be interpreting things differently.
  • Added the ability to mute sound on each video individually and have this setting remembered for each project individually.
  • Added 27 new measurement overlay icons for event types, based on FontAwesome.
  • Added help buttons in several parts of the program that link directly to the relevant pages in this online user guide.
  • Added a button to sort the events list on the measurement tab chronologically based on the timecode of their earliest point.
  • The "Direct OpenCV output window" option from the automatic plumbline detection interface has been replaced by something better. Now, the detected chessboard corners all show up as yellow dots on the main video windows during this stage instead.
  • In configuring event types, you can now use length label multipliers < 1. For example, if your calibration units are in millimeters, you can use a multiplier of 0.1 to display measured lengths on the screen in centimeters.
  • Reorganized and enhanced the XML output. This includes adding project notes and all Annotations to the XML files. Instead of the object and videoclip elements being nested inside an "objects" element, the top-level element is now "project" (with some attributes including project description and name), under which are "objects" (containing only objects and their children, such as events) and "videoClips" (containing only videoClips and their children, such as annotations or calibration information). This means the XML files now contain pretty much any information from a VidSync file that you could possibly want to access. However, if you wrote code previously to import VidSync's XML output into R or some other environment, you might (depending on your specific code) have to make some small, easy modifications for compatibility with the new and improved exports.
  • Fixed a bug that sometimes caused new portraits to overwrite old ones.
  • Fixed a bug that showed back face world residuals being way higher than they actually were.
  • Fixed many other minor glitches.


Minor update with Version 1.55

Jason Neuswanger Monday March 2, 2015

A new version of VidSync (1.55) is available with several minor bug fixes and user interface inhancements. The main changes since 1.5 include:

  • Added shortcut keys for regular advanced playback rates 1 and 2 (described in the tooltips for their buttons).
  • Fixed some bugs that prevented effective use of VidSync for 2-D calibrations (for people not trying to take 3-D measurements but wanting to record observations in terms of a 2-D grid).
  • Added the ability for annotations to include a running timer from the point the annotation was started (useful for having a "Begin analysis" annotation at a certain point in your video and being able to see how much time has elapsed since that point).
  • Made speed improvements so that files containing thousands of measurements should have playback just as responsive as files containing a few measurements.
  • Adjusted the color of the synced playback scrubber to show up well in Yosemite, since Apple inverted the colors of their sliders in the upgrade from Mavericks.