Measuring "Objects" and "Events" in VidSync

VidSync organizes measurements into a customizable, reusable hierarchy consisting of:

1. Objects, such as fish. Objects typically have many Events.

2. Events, such as prey capture maneuvers. An Event may consist of many Points. (It can also, sometimes, involve multiple Objects.)

3. Points, which contain your actual measurements. Every Point belongs to exactly one Event.

Defining object and event types

Much of the flexibility of VidSync comes from the way you define Object and Event types. In a typical study of fish feeding behavior, there might be a "fish" Object Type and Event Types for prey capture attempts, length measurements, and aggressive conflicts. Any given Object of type "fish" might then be associated with several individual Events of each of those types. This is the most intuitive way to use the hierarchy, but it is not the most convenient in all cases.

It is also frequently useful for objects to encapsulate a collection of real-world objects, each of which is represented by a separate event. For example, I've measured hundreds tiny tracer particles drifting past the camera to digitize a 3-D velocity field throughout a stream fish's habitat. They were all contained within a single Object in VidSync of type "velocity tracer collection," and each actual tracer was represented by a separate Event of type "tracer drifted." This style of organization is useful whenever you need to make just a single measurement each on a large number of real-world objects. Another common application of this approach is when measuring the lengths of a large number of fish without any need to collect other types of measurements on each individual.

Each measured point is shown on the screen with a marker, the color of which depends on the specific Object being measured (e.g., different colors for different individual fish). The measurement’s Event Type determines the marker’s shape, size, duration of visibility, and whether or not lines are drawn and labeled to connect consecutive points for that event. Visually, the Object Type determines only the default color of new Objects.

You can view lengths and speeds instantly on-screen by enabling labeled "connecting lines" for a given Event Type. For this, you must change "Connecting line type" to "Dotted" or "Solid" instead of "None," then the "Label connecting lines" dropdown menu to add labels on either the master clip or both clips. Finally, check the boxes for labeling length or speed or both. The max # of points for these types must be at least 2, of course, so a line can be drawn between the points.

Creating and managing actual Objects and Events

After creating the Types of Objects and Events you'll measure, you still have to create the actual instances of those Objects and Events. Create Objects with the "Add" button above the Objects table. With an Object selected, you can create an Event with the "Add" button above the Events table. 

Event Types may also be defined with a maximum number of points, which allows fast, automatic creation of new Events. If the most recently measured Event in the table already has the maximum points for its Event Type, then your next point measurement will create a new Event of that type automatically. This is really useful when you're digitizing hundreds of one- or two-click events like prey capture attempts and don't want to have to click the "Add" button and select the event type from the dropdown menu every time.

VidSync allows you to associate multiple Objects with a single Event, i.e. it supports many-to-many relationships. These are useful, for example, when studying competing fish and wanting to associate a "conflict" Event with both of the individual fish Objects involved. To do this, select the Event of interest, hit the Event "Edit" button, select the additional participating Object from the "Other Objects in this Project" listing, and hit the "Add Selected to this Event" button.

You can also move an Event from one Object to another, in case you accidentally associated it with the wrong one. To do this, follow the instructions above for adding both Objects to the same Event, and then hit the "Remove Selected" button to remove the unwanted one.

Recording measurements

With an event selected, click on the position you with to measure on the video window, and a new point will be created. Watch the magnified preview window to see exactly where you're clicking. After the click, the new point will be selected (indicated by yellow crosshairs), and you can use the arrow keys to nudge it around in exactly the right position. (When you're trying to get very position just right, clicking fairly quickly and then nudging with the keys tends to be faster than fiddling with the mouse to get it into exactly the right spot.) Once you're satisfied with the position of that click, do the same thing in the other video(s), and 3-D coordinates (x, y, z) will appear next to the current point in the "Selected Event's Points" table.

At any time, you can select any measurement visible on the video screen by right-clicking near it (while on the Measurement tab). However, you can only nudge the point if the video is at the exact frame on which the point was created, so hit "Go To Point" if you want to select a point and move it around.

You can delete a selected point by pressing the delete key, but this will only delete the "screen point" — i.e, the information for that point in that video clip. The point will still exist and may contain information on other clips. To completely delete a point, use the "Delete" button above the points table. The lesser "screen point" deletion is frequently useful if you accidentally click too far away from the object you want to measure and want to just start over with that click rather than nudging it with the arrow key thirty times. These same selection and deletion mechanics also work for points you digitize in the calibration and distortion correction interfaces.

Hint lines are a very useful feature when recording points. If you're doing a calibrated 3-D analysis, clicking on one video to begin a point will automatically display a line in the other video(s) corresponding to the line-of-sight established by your first click. This makes it easy to find the same object in the other camera, an otherwise sometimes difficult task when dealing with dense schools of fish or clouds of velocity tracers. You should not use hint lines to tell you exactly where to click on the object; just use them to find the right object, then place your like normal click based on your view of it in the magnified preview.

At the top of the Measurement screen is a setting to turn hint lines off, view all hintlines for currently visible points (even if the point isn't missing any coordinates), or view only "Unpaired" hint lines, i.e. those for which a point has been created on one video but not yet clicked on the other(s). "Unpaired" is the default and most useful option.

VidSync contains efficient systems for selecting and precisely editing existing measurements. Any input can be selected through tables in the main document window at any time: just select the object and event of interest (and point, if not just any point will do) from the tables, and click "Go To Point" to jump the video to that measurement.

When a measurement’s marker is visible on the video overlay, you can also select it by right-clicking near the marker. Newly measured points are automatically selected. A selected point’s position can be “nudged,” by a configurable distance with sub-pixel precision (e.g., 0.2 pixel) by using the keyboard arrows. The exact position of the measurement on the video is reflected in a “magnified preview” box in the document window, which shows a marker in the exact position of the point against a magnified version of the local region of the video. The magnification of the preview is configurable, as are its brightness, contrast, sharpening, and the size and type of the point marker (a small dot or a concentric arc reticle). This system enables arbitrarily precise placement with no ambiguity about which exact point under the cursor is recorded when clicked.

Correcting mistaken identity: splitting and joining objects

When analyzing several similar-looking objects (such as juvenile salmon in a school) over a long period of time, it's easy to have cases of mistaken identity. A fish might wander off-screen, come back a couple minutes later, and be picked up and recorded as a different fish until you realize it was the same one as before. Likewise, the fish might come back on-screen and you think it's the same one, but realize later it was a different individual. VidSync has tools to correct both types of errors.

If you've mistakenly recorded two objects as one, and this mistake happened at a single point in time, you can use the "Split" button above the list of the object's events. The current object will then only be associated with events before the video's current timecode. All events at or beyond the current timecode will be placed under a new, otherwise identical object.

If you've mistakenly recorded one object as two, you can open up the first object's "Edit" panel, go to the "Synonymize" tab, select the second object from the list, and hit the "Synonymize" button. This will delete the second object and add all its events to the first object. Notes from the second object will be added to notes from the first object; everything else from the second object (e.g., name, color) is forgotten.