net.sourceforge.nite.tools.videolabeler
Class Document

A document is a global singleton object. Before it is used it should be
created with
createInstance(). From then on the same document can be retrieved with
getInstance().

The document makes use of the NITE XML Toolkit. It is assumed that you
are familiar with the concepts of this toolkit. A document is created with
the path to a metadata file, the name of an observation and the name of an
annotator. The metadata and observation data for the specified annotator will
be read into this document object. The metadata can later be retrieved with
getMetaData() and the observation is retrieved with
getObservation().

There are three base methods to obtain the available agents, layers and
signals from the metadata. These methods are
getAgents(), getLayers() and
getSignals(). The document only returns layers for
which there is a layerinfo element in the configuration
file.

The only possible document changes are creating, adding and deleting
annotations. The respective methods are
createAnnotation(),
insertAnnotation
and
deleteAnnotation().
These methods ensure that the annotations do not overlap. If the GUI setting
makeContinuous is true, it is also ensured
that the annotations remain continuous, i.e. there are no gaps between
them.

The document is Observable. Observers (see
Observer can register themselves with the document
to be notified of any changes. When the document notifies an observer of a
change, it will pass an argument, which is a List
that consists of two Double objects. The first one
contains a start time, the second an end time. The document changed between
that start and end time.

The document is saved with save(). To check whether a
document has been saved and show a prompt if not, use
checkSave().

getCorpus

Returns the corpus. Normally the corpus should not be edited outside
this class. The methods createAnnotation, insertAnnotation and
deleteAnnotation ensure that annotations remain non-overlapping and
continuous, and that observers are notified.

getClock

getLayers

public java.util.List getLayers()

Returns a list with the available annotation layers. This method
iterates through the list of all time-aligned layers defined in the
metadata. For each layer it is checked whether there is a layerinfo
element in the configuration file (see
CSLConfig.getLayerInfo()).
If so, the AnnotationLayerFactory is used
to create an annotation layer (instance of
AnnotationLayer). This method returns a list of
those annotation layers. If an error occurs, a message is printed to
standard output.

searchAnnotations

Performs a search in the corpus. This method takes a query in the
NITE Query Language. It should specify only one variable for the search
results. This method returns a simple list of annotations (instances of
NOMElement) rather
than the more complex result of
Engine.search().
The annotations will be sorted on their start times.

Parameters:

query - a query in the NITE Query Language

Returns:

a sorted list of annotations

Throws:

java.lang.Throwable - if an error occurs while searching the corpus

notifyObservers

public void notifyObservers(double start,
double end)

Notifies all observers that the document has changed between the
specified start and end time.

createAnnotation

Creates a new annotation for the specified code name, start time and
agent. The annotation without an end time (end time is Double.NaN) is
added to the corpus. When the end time is set, call insertAnnotation. If
an error occurs, this method throws an exception and the document won't
be changed.

insertAnnotation

Inserts a new annotation into the corpus. The annotation must have
been created with
createAnnotation(). The annotation must have a valid start time and end
time! This method does not really add the annotation, as this was already
done in createAnnotation(). This method only enforces some
constraints as described below.

Because the annotations cannot overlap, it may be necessary to make
space for the new annotation by deleting (parts of) existing annotations
in the period between the specified start and end time. This method
ensures that annotations will not overlap.

If CSLConfig.makeContinuous() returns true, this method also ensures
that there are no gaps in the time line. This would happen if the start
time of the new annotation is greater than the end time of the previous
annotation, or if the end time of the new annotation is less than the
start time of the next annotation. In these cases, the start or end time
of the new annotation is changed so the annotation is connected to the
previous or next annotation.

As a result there may be two annotations with the same target next to
each other. In that case the annotations are merged. Note therefore that
the specified annotation may be edited or deleted altogether!

DR:05.17.2005 merging made dependent on gui config var 'merge'

If makeContinuous is false, this method will execute
one corpus search. If makeContinuous is true, it will
execute three corpus searches.

Parameters:

layer - the annotation layer

annotation - the annotation to be inserted

Throws:

java.lang.Throwable - if the annotation cannot be inserted

deleteAnnotation

If CSLConfig.makeContinuous()
returns true, this method tries to fill the resulting space in the time
line with the previous or next annotation. If there is a previous
annotation, its end time will be set to the end time of the deleted
annotation. If there is no previous annotation, but there is a next
annotation, its start time will be set to the start time of the deleted
annotation.

As a result there may be two annotations with the same target next to
each other. In that case the annotations are merged.

If makeContinuous is false and the deleted annotation
has a duration greater than zero, this method will perform no corpus
search. Otherwise it will perform two corpus searches.

save

checkSave

public boolean checkSave()

Checks whether the document has been saved. If yes, this method
returns true. If not, this method shows a dialogue window to ask the user
whether the document should be saved. If the user clicks "Yes", the
document will be saved and this method returns true. If the user clicks
"No", the document will not be saved, but this method still returns true.
If the user clicks "Cancel", the document will not be saved and this
method returns false.

This method should be called before the application is closed. If
this method returns true, the application can be closed.

Returns:

true if the application can be closed (the document was saved or
the user does not want to save it), false otherwise