ViPER-GT Specification
What is ViPER-GT?
ViPER-GT is a system for editing and reviewing video metadata, with the main goal of editing 'ground truth' data. For information about the requirements for this system, see the ViPER-GT requirements document. For information from a user perspective, see the ground truth annotation manual. This document describes the design and implementation of the fourth major revision of the ViPER Ground Truth Authoring Tool. It is written to give insight as to how the system operates internally and how it can be extended, and may offer some insight as to why it was designed that way. This document is live, and will change as the requirements change and the implementation is developed.
Note that this only defines the core system, not the modules that attach to it and provide most of the user experience. For information about those, seek them out individually in the beans page.
System Overview
The system uses the Java programming language, and relies on the ViPER API and the Limn3. It uses the pure java JMPEG to decode mpeg-1 videos, which is used in the canvas and to populate the FILE Information descriptor, and will likely use the Chronicle widget to handle the timeline view. The current system uses the Swing toolkit. The system is a bunch of javabeans that are loaded by the application loader; this document will describe this process, and the core utlities and beans that are required for the application to load. Beans that provide the user interface, and others, are described in the beans page.
It should be noted that Limn3 comes with its own bean, the apploader:Core bean, that acts as the main container and holds the master menu. Most of these beans require this, if only to get at the Preference Manager.
The mediator bean provides access to the currently loaded ground truth file (that's right, the system design only supports one file at a time - I've gotta work on this. Note that there is nothing stopping multiple mediators from pointing the the same 'ViperData' instance, or from multiple mediators loaded at once, but the apploader doesn't have good support for this kind of functionality yet). The mediator provides access to the ViperData object and a variety of helper methods and models to maintain interface consistency. Most of the other beans should do their communication either by altering the user preference model that the application launcher keeps (like the way the most-recently-used list works) or by manipulating the mediator.
The Viper Data Mediator
The mediator is the main ViPER-GT bean, maintaining the shared application state. Any changes the user wishes to make in one view, if they are to be reflected in the other views, must pass through this bean, or one of its delegates. Its full java name is edu.umd.cfar.lamp.viper.gui.core.ViperViewMediator. Composed piecemeal from views in viper 3.6 and some other parts as needed, it is lacking in elegance. When a new feature was required, such as selection or hiding, it was simply added.
The main function of the mediator is to hold the ViperData object; the ViperData object is the root of the metadata, as described in the ViPER API documentation. Currently, the mediator only holds one root annotation; this can be retrieved with the getViperData method. Any changes a view wants to make to the data should go through the getViperData method's ViperData object. For more information about how the API works, read its documentation. If you want to respond to changes in the data, I would recommend listening on the mediator, not the ViperData object. ViperMediatorChangeEvent``s, described later, provide another layer of utility to the ``ViperDataChanged events of the API.
Another way to communicate between views, and across sessions, is to save data to the Limn3 preferences space, an RDF data store. This involves querying and updating the appropriate triple store, either the user store, for things that will be saved across sessions, or the temporary store, for stuff that won't be. This can be accessed with the getPrefs method. For more information about how to use the triplestore features, see the Limn3 documentation.
The mediator has a few other features that are more specific to the ViPER application, and arose to address specific user requirements. These include the selection model, the data player interface for accessing media data, the hiding interface, a unified event mechanism, and tools for handling propagation and interpolation.
Selection
Selection is handled in two othogonal ways. The selection of the annotation uses with the delegate selection object associated with the mediator. There is also a selection of the current frame, the currentFrame. In addition to the current frame, there may also be a marker model, something useful for the chronicle (it is basically a map of strings to frames).
The data selection model uses the ViperSelection interface, from the viper api's utility package. The current implemenation relies on the DefaultSingleViperSubTree model, which includes only the ability to select a single attribute, following a sourcefile - config - attrconfig - desc - attr chain.
To change the selected frame, alter the currentFrame property of the mediator. The current frame is the one displayed in the video frame view widget; the values at this frame are used in the spreadsheet view; the chronicle uses it as its main marker.
Changes to the frame selection are reflected in mediator change events, while changes to data selection are presented through the selection object itself.
Media Players
The DataPlayer classes provide an interface to get the frame images of a video. In a future revision, they should also provide access to audio tracks.
Hiding Values
Sometimes, it is useful to only display a subset of the data, to avoid clutter and to focus on a specific task. The list of hidden attributes acts similarly to the selection interface, but it has a different model.
Viper Mediator Events
In order to simplify development of views, the mediator combines several event types (UI changes, mediator notifications, and data changes) into one viper event object.
Propagation and Interpolation
Propagation, the act of altering certain selections of attributes so that they take the same value over a subset of frames, is handled by the propagation and interpolation delegate.
The Most Recently Used File Manager
The MRU list maintains a list of files the user has opened, and their associated last time of opening.
The Property Sheets
One of the features I tried to develop was a property sheet api.
The Action History (Undo/Redo)
The action history, present in the user interface as the undo history, presents a record of all currently applied changes since the last save.