Overview
Vidana is a piece of software for quantifying percentage cover within quadrats from video footage or still digital images. Vidana has been designed make the processing of large amounts of data as quick and effortless as possible. The principle of operation is simple:
1. Video footage is frozen on a frame showing the quadrat of interest.
2. A ‘template’ is drawn over the image by covering each class of cover with a different colour. This can be done quite quickly by drawing around the perimeter of the materials and then flood-filling the centre.
3. The mouse is clicked on the four corners of the quadrat to define its location (the corners can easily be adjusted if they are not quite right).
4. Click on the CALC button and Vidana gives the exact percentage cover of the materials within the quadrat boundary.
5. The results can be appended to a text file as output if required.
Best of all Vidana is absolutely free! Further, Vidana is open-source so you are freely able to modify the software to suit your own project if the required functionality is not already built-in.
Note: Vidana is currently in beta-test, there will probably be bugs.
Requirements
Vidana requires DirectX 9.0 and currently has been tested on Windows 2000 and XP.
DirectX 9.0 is a free download from Microsoft.
License
Vidana was created in the context of preliminary work for the World Bank/GEF targeted Coral Reef Research Project. Vidana has now been made available as a free download from this site (see below) and is released under the terms of the GPL Version 2. The source code is freely available (below) and the program may be modified and redistributed under the terms of the GPL.
Warranty
Vidana is provided with no warranty whatsoever. Neither the software author(s), MSEL, The University of Exeter, nor any other individual or organisation will accept liability for any consequence of the use of this software. Use it at your own risk.
Download and Installation
Vidana is distributed as a single executable file approx 230k in size. The current version is 1.0.1 beta. Download: vidana.exe. Or, if you prefer a zipped version (approx. 60k): vidana.zip
The executable is run directly, there is no installation process required. However remember to install DirectX 9.0 (or later) first.
The source code distribution is available here: vidana-1.0.1beta-source.tar.gz. The code can be compliled using MS Visual C++ and also requires the DirectX 9.0 SDK (free download from Microsoft).
Previous versions of Vidana can be downloaded at the foot of this page.
Instructions
Overview of Operation:
Quick Instructions
1) Load a video clip or still image (File > Open). Supported file formats are dependent on DirectX, most common formats should work ok, in particular we generally use AVI format.
2) For video clips, use the video playback controls to find and freeze the frame of interest.
3) Using the template editing controls and the mouse, draw outlines in different colours around the patch types of interest within the quadrat. Flood fill the outlines by holding the spacebar and clicking with the mouse inside the outlined regions. Note that the opacity of the template over the background can be adjusted by using the slider control at the bottom right.
4) Switch to quadrat editing mode and click on the four corners of the quadrat in order (i.e. either clockwise or anti-clockwise). As each corner is added the quadrat edges are drawn, and on the final (fourth) click the perimeter of the quadrat is automatically closed.
5) If necessary, drag the corners of the quadrat to their exact positions.
6) Click on the CALC button, and the percentage cover of each template colour within the quadrat will be displayed.
7) Note that it is not necessary to do the above steps in the strict order suggested here. The quadrat and template can be edited even while the percentage cover values are displayed, and the results are updated automatically.
The various control buttons are described in more detail below. There are also many options that adjust the behaviour of Vidana which can be set via the menus or through the options dialogue box (Options > All Options…), also described below.
Video Playback Controls
The following keyboard shortcuts and modifiers also apply:
P – Plays and stops the video clip on alternate presses.
S – Stops the video clip.
Right Arrow – Moves the clip one frame forward.
Left Arrow – Moves the clip one frame backward.
SPACE – If the spacebar is also held down certain video controls (operated either by the icons or keyboard) have an increased effect:
1) Stepping Forward or Backward jumps five frames instead of one.
2) Fast Foward and Rewind operate twice as fast.
Template and Quadrat Editing Controls
There are two editing modes which govern what happens when the mouse is clicked on the image area. When the “quadrat editing mode” button is down, mouse clicks in the image area set and adjust the quadrat position. When any of the other buttons are down, mouse clicks will draw and fill the coloured template overlay on the image.
Template Editing Mode
In this mode clicking and dragging on the image area draws in the current template colour. The first four template colours can be selected from the icons as shown, but in fact ten template colours are available. These (and the first four) can be selected by pressing the keys 1, 2, 3 etc. through to 0 (colour 10). An outlined region on the template can be flood-filled by holding down SPACE and clicking in the middle of the region. The area is filled using the currently selected template colour. Note: if the outline is not competely closed the flood-fill will ‘leak’ out filling a large part of the image, however this is easily undone using the Undo feature (see below).
Quadrat Editing Mode
In this mode clicking on the image area defines the quadrat corners. When the quadrat is drawn on the screen, the quadrat corner positions can be adjusted by dragging with the mouse.
= Undo and Redo
Template editing supports Undo and Redo actions. These are activated via the menu entries Edit > Undo and Edit > Redo and also by the keys U and R. Vidana supports 10 levels of undo, so up to the last 10 drawing actions can be undone by repeatedly pressing the U key. Similarly “Redo” (R) will redo an operation that has just been “Undone”.
Cover Calculation
When a completely formed quadrat is on screen (i.e. with all four corners defined) clicking the CALC button displays a box showing the percentage cover of each template colour as it appears within the quadrat boundaries. By default the cover for the first four classes only is shown (corresponding to the colours which are selectable from the icons). If any further of the ten classes have been selected (i.e. by using the keys 5 through to 0) then the cover of all classes up to the last one used will be displayed.
The percentage cover calculation is carried out as follows: The template colour is sampled at 32 x 32 (1024) locations within the quadrat (these points can be seen as the grid of small marks which appears when CALC is clicked). The number of points counted in each class divided by 1024 gives the proportional cover for that class. From this the percentage cover (= proportional cover x 100) and area (= proportional cover x quadrat area) are calculated. The number of sample points used can be changed via the Options dialogue box (see below). Note that with the default of 1024 sample points the calculated percentage cover is reasonably accurate to one decimal place, but is of good accuracy to the nearest percentage unit. Varing the number of sample points affects the precision accuracy of the cover estimates.
If the quadrat is not square on the screen the sample points are distributed as if quadrat is in fact square but is presented in a perspective view. In this case the points are not distributed evenly across the screen area but, notionally, are distributed evenly across the the quadrat area on the sampled surface. However, as long as the quadrat appears approximately square on the sceeen the distinction is irrelevant.
The CALC button operates like a toggle, clicking it a second time removes the results box from the display.
Export to Text File
In order to output results to a text file the option “Output File” must first be set in the Options Dialogue Box and the file name supplied (see below). If this has been done at the bottom of the cover information box will be an icon marked “Save”. When clicked the current resuts are appended onto an output text file. When the current result has been saved the text of the icon changes to “Save (Done)” as a reminder. The “Save Done” status is cleared as soon as the template or quadrat are edited or cleared.
The format of the text file output is described below.
Options
The various options and settings supported by Vidana can be set through the Options menu or the dialogue box opened via Options > All Options…
Output File
Check the box marked Output File if you want to append each set of results onto a text output file. The output file must also be named in in the box marked Filename. Click on Browse to search for a file or location. If the named file already exists then the results will be appended onto the end of the file, otherwise the file is created. If Prompt For Notes is checked (bottom right) then for each set of results written to text file, you will be prompted to enter text notes which will appear in the results file. See below for a description of the format of the output text file.
Template Clearing
This only applies to video media. “Template Clearing” refers to what happens when a video is played or stepped from a paused state with some template drawing or quadrat corners on screen.
All – the template and quadrat corners are cleared when the video is played or stepped.
Classes – the template drawing is cleared but quadrat corners will remain (when the video is paused again).
None – neither the template drawing nor quadrats are cleared.
Adjusting this option may produce a more efficient work flow for certain tasks.
Default Edit Mode
Vidana can be made to switch to a specific edit mode whenever a video stream is paused. Again, this may promote a more efficient work pattern when analysing many quadrats.
Quadrat Corners – switch to quadrat editing mode when video is paused.
First Class – switch to template editing mode and select the first class colour (red).
None – the current editing mode is preserved.
Draw Pen Size
The diameter in pixels of the “pen” used to draw on the class colours on the template.
Quadrats
These settings enable more than one quadrat to be placed on the screen at once.
One Only – the default setting where only one quadrat is allowed.
One or Four – under this setting one quadrat can be defined (by placing four corners), then an additional corner can be placed inside the quadrat to create a 2 x 2 matrix of four abutting quadrats.
Auto Split 2 x2 – under this option a single quadrat is automatically split into four sub-quadrats. Unlike the previous option there is no control over the position of the sub-quadrats, they are fixed as being delimited by the edge midpoints of the main quadrat. This option was added to Vidana as a specialist function for our own research into optimal sampling scales.
Sample Points
This sets the number of sample points used within the quadrat to calculate the percentage (or area) cover. As explained above, the default value of 1024 means that a grid of 32 x 32 points is overlayed on the quadrat area and the area cover is assessed by counting the number of those points that lies in each cover category. Increasing the number of sample points therefore improves the precision (i.e. accuracy) of the area cover calculation. However, note that the maximum achievable precision on the cover estimate is limited by the pixel resolution of the image. Increasing the number of sample points will also cause a performance decrease in editing functions if the calculation box is left visible while editing (i.e. editing might be a bit slow).
Only square values are permissable as the number of sample points. Vidana will round up the value you supply to the nearest square value. E.g. if you enter ’2000′ this will be rounded up to a grid size of 46 x 46 = 2116 sample points. A message window will notify you of this.
Calculate Options
These settings govern what is displayed when the CALC button is pressed.
Percentage Cover – display percentage cover.
Actual Area – display actual area covered (based on the quadrat size, see below).
Both – display both percentage cover and actual area.
Quadrat Size: – enter here how long a quadrat size is (note: quadrats are assumed to square).
Units: – enter here the units in which the quadrat size is expressed.
Output
Check “Prompt For Notes” to add notes to text file output (see above).
Text File Output Format
The outputted text file consists of a fixed number of tab delimited fields as detailed below. The first line of the file is a header which names each of columns then each following line corresponds to a single set of results from a quadrat or sub-quadrat. The results appear in the text file in the order they were saved. Note also, that the output text file is not “locked” while Vidana is running, so it is possible to open the file and edit it (to remove an erroneous entry for example) whilst using Vidana.
This example file contains only three entries, and was created using percentage cover calculation only.
Vidana 1.0beta output:
file mins secs centisecs scene quad sub units samples pct1 pct2 pct3 pct4 pct5 pct6 pct7 pct8 pct9 pct0 area1 area2 area3 area4 area5 area6 area7 area8 area9 area0 notes
C:clip.avi 0 0 97 1 1 0 m 1024 33.8 10.1 0.0 14.6 0.0 0.0 0.0 0.0 0.0 0.0 – - – - – - – - – - note1 note2
C:clip.avi 0 5 53 1 1 0 m 1024 16.2 22.9 0.0 9.8 0.0 0.0 0.0 0.0 0.0 0.0 – - – - – - – - – - note3
C:clip.avi 0 12 06 1 1 0 m 1024 29.1 0.0 20.1 0.0 0.0 0.0 0.0 0.0 0.0 0.0 – - – - – - – - – - note4
The column values for each entry can be interpreted as follows:
file – the video or image file being viewed.
mins, secs and centisecs – identifies the position of the frame in a video file.
scene – this increments every time results are saved and a video is subsequently played.
quad and sub – for multiple quadrat setups or when using “Autosplit 2 x 2″ these numbers identify the quadrat or sub quadrats.
units – the units symbol(s) a specified for actual area calculation in the Options dialogue.
samples – the number od sample points used within the quadrat, as set in the Options dialogue.
pct1 – pct0 – the percentage cover for each class.
area1 – area0 – the absolute area cover for each class.
notes – any notes that were entered when the “Prompt for Notes” option is set in the Options dialogue.
It is possible to enter multiple notes over several columns for a single entry by putting each note on a separate line (when entering notes press CTRL+RETURN to move down to the next line). For example, the two note entries in the first line of the above example file were entered like this:
Although the “scene”, “quad” and “sub” fields may be used to uniquely identify a set of results they may not do so in a consistent way. Using manually entered notes may be less ambiguous.
Known Issues and Workarounds
These are reported bugs which exist in the current version of Vidana.
1) Changing the Zoom level to anything other than 100% with some video media freezes program, possibly with an error message starting “FAILED(hr=…)”. This only happens with some video files, on others the zoom can be freely changed without problems. The cause is currently unknown.
Incomplete Versions
Here are two executables for newer versions of Vidana that never really got finished, or combined together. They do work ok, any problems are likely to be cosmetic or to do with non-obvious operation.
Vidana 1.1
This version has the ability to save and load template image files. Zipped Executable: vidana-1.1.zip
Vidana 1.2.1
This version can do a perimeter calculation, but bizarrely not the template image save. Even though the option appears in the menu it is disabled. Also note that the perimeter calculation only works in ruler mode – not quadrats. Zipped Executable: vidana-1.2.1.zip
Previously Released Versions
Vidana 1.0beta
Zipped Executable: vidana-1.0beta.zip Source: vidana-1.0beta-src.tar.gz
Authorship, Contributions, Bug Reports
Vidana was originally authored by J Hedley (jdhedleyexeter.ac.uk). Please submit bug reports which are not already listed above to this address. Modifications to the source code, new features and bug fixes are welcomed. They will be merged into the source available here if appropriate. Again, please get in touch via the above address.