View Javadoc
1   /*
2    * Licensed to The Apereo Foundation under one or more contributor license
3    * agreements. See the NOTICE file distributed with this work for additional
4    * information regarding copyright ownership.
5    *
6    *
7    * The Apereo Foundation licenses this file to you under the Educational
8    * Community License, Version 2.0 (the "License"); you may not use this file
9    * except in compliance with the License. You may obtain a copy of the License
10   * at:
11   *
12   *   http://opensource.org/licenses/ecl2.txt
13   *
14   * Unless required by applicable law or agreed to in writing, software
15   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
16   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
17   * License for the specific language governing permissions and limitations under
18   * the License.
19   *
20   */
21  
22  
23  package org.opencastproject.metadata.mpeg7;
24  
25  import org.opencastproject.mediapackage.XmlElement;
26  
27  import java.util.Iterator;
28  
29  /**
30   * Base interface for text annotations with relevance and confidence values.
31   *
32   * <pre>
33   * &lt;complexType name=&quot;TextAnnotationType&quot;&gt;
34   *   &lt;choice minOccurs=&quot;1&quot; maxOccurs=&quot;unbounded&quot;&gt;
35   *       &lt;element name=&quot;FreeTextAnnotation&quot; type=&quot;mpeg7:TextualType&quot;/&gt;
36   *       &lt;element name=&quot;StructuredAnnotation&quot; type=&quot;mpeg7:StructuredAnnotationType&quot;/&gt;
37   *       &lt;element name=&quot;DependencyStructure&quot; type=&quot;mpeg7:DependencyStructureType&quot;/&gt;
38   *       &lt;element name=&quot;KeywordAnnotation&quot; type=&quot;mpeg7:KeywordAnnotationType&quot;/&gt;
39   *   &lt;/choice&gt;
40   *   &lt;attribute name=&quot;relevance&quot; type=&quot;mpeg7:zeroToOneType&quot; use=&quot;optional&quot;/&gt;
41   *   &lt;attribute name=&quot;confidence&quot; type=&quot;mpeg7:zeroToOneType&quot; use=&quot;optional&quot;/&gt;
42   *   &lt;attribute ref=&quot;xml:lang&quot;/&gt;
43   * &lt;/complexType&gt;
44   * </pre>
45   *
46   * TODO: How to encode source and version? Maybe use MediaInformation in VideoSegment
47   */
48  public interface TextAnnotation extends XmlElement {
49  
50    /**
51     * Returns the relevance of this annotation.
52     *
53     * @return the relevance value
54     */
55    float getRelevance();
56  
57    /**
58     * Returns the confidence of the validity of this annotation. The value will be in the range of <code>0.0</code> and
59     * <code>1.0</code>.
60     *
61     * The confidence may vary with the technique that was used to create the annotation. For example, extracting a word
62     * using optical character recognition usually has a better confidence value than speech recognition.
63     *
64     * @return the confidence value
65     */
66    float getConfidence();
67  
68    /**
69     * Returns the language of this annotation in ISO represenatation, e. g. <code>en</code> for annotations in English.
70     *
71     * @return the language
72     */
73    String getLanguage();
74  
75    /**
76     * Adds a new keyword annotation.
77     *
78     * @param keywordAnnotation
79     *          the annotation
80     */
81    void addKeywordAnnotation(KeywordAnnotation keywordAnnotation);
82  
83    /**
84     * Adds a free text annotation.
85     *
86     * @param freeTextAnnotation
87     *          the annotation
88     */
89    void addFreeTextAnnotation(FreeTextAnnotation freeTextAnnotation);
90  
91    /**
92     * Returns an iteration of the keyword annotations.
93     *
94     * @return the keyword annotations
95     */
96    Iterator<KeywordAnnotation> keywordAnnotations();
97  
98    /**
99     * Returns an iteration of the free text annotations.
100    *
101    * @return the free text annotations
102    */
103   Iterator<FreeTextAnnotation> freeTextAnnotations();
104 
105 }