Video Annotation and Reference System (VARS) version 8.x

http://vars.sourceforge.net
https://github.com/hohonuuli/vars

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~  What is VARS?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The Video Annotation and Reference System (VARS) is a software interface and 
database system that provides tools for describing, cataloging, retrieving, and 
viewing the visual, descriptive, and quantitative data associated with video 
archives. 

VARS is a suite of applications that communicate with a relational database 
mangement system. VARS comes with a database system (Apache Derby) that is 
suitable for testing, development, and small deployment applications. For 
production systems, it is recommended that you set up a database server. VARS 
has been tested on Apache Derby, MySQL, PostgreSQL, Oracle, MS SQL Server 2000 
and MS SQL Server 2008 but should also run on most relational databases.

Developed and Maintained by the Monterey Bay Aquarium research institute 
(MBARI), VARS is aimed at the oceanographic community. However, it can be used 
for other fields and we welcome suggestions or code contributions that would 
help expand the VARS community.


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~  About this release?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
VARS 8.x is backwards compatibly with previous VARS databases (i.e. 6.0 or
later). If you have significant data from a pre-6.0 VARS installation, it is
possbible to migrate the older database to work with VARS 8.x. Contact 
http://groups.google.com/group/mbari-vars for assistance.

This release includes support for the Sharktopoda video player on Mac OS X.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~  Installing VARS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For installation instructions refer to the INSTALL.macosx and INSTALL.windows 
files. You will need to follow these instructions before you can run VARS.

VARS has a built in video player that works with h264/mp4 files. If you are 
using macOS, it is recommended you also download the Sharktopoda video player
from https://github.com/underwatervideo/Sharktopoda


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~  Running VARS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To quickly get started on windows, refer to QUICKSTART.windows. Mac users should
refer to QUICKSTART.macosx


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~ Deploying VARS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Fresh out of the box, VARS is configured as a demostration application. If you
intend to use VARS on a single machine only, this setup will work fine.

Here are a few configuration tips to help set VARS up for your use.
 
I. Customizing the Camera-platforms

   A camera-platform is the name of whatever it is you have your camera 
   mounted on. At MBARI, we use 2 ROVs, Ventana and Tiburon. But the camera-
   platform can be anything that you want to use to uniquely identify the 
   source of the video. Configuring VARS to recognize your camera-platform is 
   simple; just follow these steps:
   
    A) Open conf/annotation.properties.
    B) At the bottom of the file is several lines starting with ship and 
       cameraplatform. You can delete all of these, then add a line like:
       
        cameraplatform.0=MyCameraPlatform
        
       You can add as many camera-platforms as you like; subsequent ones would 
       be identified as cameraplatform.1, cameraplatform.2, etc.
       
II. Capturing images

    When VARS is used to capture images from video, it initially stores them
    in a directory that you specify. When a session is closed, VARS can be 
    configured to change the reference of these images to a web accessable URLs.
    In order to do this you will need to do the following:
    
    A) You will need to setup a web server. (The details of which are WAY
       beyond the scope of this document). 
    B) When setting up the web server you will need to have a directory that
       can be both accessed from the annotation workstation and served 
       through the web server. This directory should have write permissions
       for the user accounts that will be running the Annotation 
       applications. In addition, the directory will need to be mounted (for 
       Mac OS X) or accessed by UNC paths (on Windows) so that VARS can move
       images to them. 
    C) In the VARS annotation application, open the preferences (it's a button on 
       the toolbar.
    D) In the preference window you will need to specify
       1) The directory that you wish to write the images too. Ideally, this
          directory will be on a shared drive that is mounted on a web server.
          For Example, this might be \\SomeSharedDrive\framegrabs. Mac\Linux
          users may have to mount the shared directory before annotation 
       2) The URL that points to the above directory on the web server. For example
          http://mywebsite.edu/video/framegrabs.

          
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~  Running VARS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The scripts for running VARS are located in the bin directory (e.g. VARS\bin)

!!! IMPORTANT !!!
VARS requires a networked database server in order to function. This download
includes one, but you must start it before running VARS. To start the database 
server use: derbystart (Mac\Linux) or derbystart.bat (Windows)
!!!!!!!!!!!!!!!!!

There are 3 applications in VARS. You can start them by running the appropriate
launcher script. The applications and corresponding scripts are:

Application        Windows             Mac OS X \ Linux
~~~~~~~~~~~        ~~~~~~~~~~~         ~~~~~~~~~~~~~~~~
Annotation         annotation.bat      annotation
Knowledgebase      knowledgebase.bat   knowledgebase
Query              query.bat           query

NOTE: The Annotation application may take a long time to start. This is 
normal because it must load all the information from the knowledgebase database
when starting.


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~  Integrating other data with VARS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

VARS was designed to integrate other data such as position (latitude, longitude,
depth) and physical parameters (salinity, temperature, etc.). This information 
is stored in a table named PhysicalData in the database. There is a script included 
in the bin directory named 'merge_csv'. If you run merge_cvs from the command line
it will display help. If you need further help or suggestions on how to import 
your physical data into VARS you can post your question at 
https://github.com/hohonuuli/vars/issues. Also, if you would like to 
integrate other information thats not available in the default tables, send an 
email. It's very easy to modify VARS to store additional information.


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~ Using your own database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

VARS comes with Apache Derby as a database server. Derby is very useful for 
small deployments or for testing VARS. However, it is likely that if you are
seriously considering running VARS, you will want to use your own database 
server. Contact http://groups.google.com/group/mbari-vars for instructions for 
setting VARS up other databases.


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~  Feedback
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
VARS is an open source project. We welcome contributions and suggestions. 
Contributions can come in many different forms such as documentation, code 
contributions, web site improvements etc. More information can be found 
https://github.com/hohonuuli/vars. The VARS mailing list can be found at 
http://groups.google.com/group/mbari-vars.
