mmif-python 1.0.14__tar.gz → 1.0.16__tar.gz

mmif_python-1.0.16/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.1
+Name: mmif-python
+Version: 1.0.16
+Summary: Python implementation of MultiMedia Interchange Format specification. (https://mmif.clams.ai)
+Home-page: https://mmif.clams.ai
+Author: Brandeis Lab for Linguistics and Computation
+Author-email: admin@clams.ai
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers 
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: deepdiff>5
+Requires-Dist: jsonschema
+Provides-Extra: seq
+Requires-Dist: numpy; extra == "seq"
+Provides-Extra: cv
+Requires-Dist: pillow; extra == "cv"
+Requires-Dist: opencv-python; extra == "cv"
+Requires-Dist: ffmpeg-python; extra == "cv"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-pep8; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytype; extra == "dev"
+
+## MultiMedia Interchange Format
+[MMIF](https://mmif.clams.ai) is a JSON(-LD)-based data format designed for transferring annotation data between computational analysis applications in [CLAMS project](https://clams.ai). 
+
+
+## mmif-python
+`mmif-python` is a Python implementation of the MMIF data format. 
+`mmif-python` provides various helper classes and functions to handle MMIF JSON in Python, 
+including ; 
+
+1. de-/serialization of MMIF internal data structures to/from JSON
+2. validation of MMIF JSON
+3. handling of CLAMS vocabulary types
+4. navigation of MMIF object via various "search" methods (e.g. `mmif.get_all_views_contain(vocab_type))`)
+
+## For more ...
+* [Version history and patch notes](https://github.com/clamsproject/mmif-python/blob/main/CHANGELOG.md)
+* [MMIF Python API documentation](https://clamsproject.github.io/mmif-python)
+* [MMIF JSON specification and schema](https://clamsproject.github.io/mmif)

mmif_python-1.0.16/VERSION

@@ -0,0 +1 @@
+1.0.16

{mmif-python-1.0.14 → mmif_python-1.0.16}/mmif/serialize/mmif.py

@@ -10,7 +10,7 @@ import math
 import warnings
 from collections import defaultdict
 from datetime import datetime
-from typing import List, Union, Optional, Dict, cast
+from typing import List, Union, Optional, Dict, cast, Iterator, Tuple
 
 import jsonschema.validators
 
@@ -24,6 +24,104 @@ from .view import View
 __all__ = ['Mmif']
 
 
+class MmifMetadata(MmifObject):
+    """
+    Basic MmifObject class to contain the top-level metadata of a MMIF file.
+
+    :param metadata_obj: the JSON data
+    """
+
+    def __init__(self, metadata_obj: Optional[Union[bytes, str, dict]] = None) -> None:
+        # TODO (krim @ 10/7/20): there could be a better name and a better way to give a value to this
+        self.mmif: str = f"http://mmif.clams.ai/{mmif.__specver__}"
+        self._required_attributes = ["mmif"]
+        super().__init__(metadata_obj)
+
+
+class DocumentsList(DataList[Document]):
+    """
+    DocumentsList object that implements :class:`mmif.serialize.model.DataList`
+    for :class:`mmif.serialize.document.Document`.
+    """
+    _items: Dict[str, Document]
+
+    def _deserialize(self, input_list: list) -> None:  # pytype: disable=signature-mismatch
+        """
+        Extends base ``_deserialize`` method to initialize ``items`` as a dict from
+        document IDs to :class:`mmif.serialize.document.Document` objects.
+
+        :param input_list: the JSON data that defines the list of documents
+        :return: None
+        """
+        self._items = {item['properties']['id']: Document(item) for item in input_list}
+
+    def append(self, value: Document, overwrite=False) -> None:
+        """
+        Appends a document to the list.
+
+        Fails if there is already a document with the same ID
+        in the list, unless ``overwrite`` is set to True.
+
+        :param value: the :class:`mmif.serialize.document.Document`
+                      object to add
+        :param overwrite: if set to True, will overwrite an
+                          existing document with the same ID
+        :raises KeyError: if ``overwrite`` is set to False and
+                          a document with the same ID exists
+                          in the list
+        :return: None
+        """
+        super()._append_with_key(value.id, value, overwrite)
+
+
+class ViewsList(DataList[View]):
+    """
+    ViewsList object that implements :class:`mmif.serialize.model.DataList`
+    for :class:`mmif.serialize.view.View`.
+    """
+    _items: Dict[str, View]
+
+    def __init__(self, mmif_obj: Optional[Union[bytes, str, list]] = None):
+        super().__init__(mmif_obj)
+
+    def _deserialize(self, input_list: list) -> None:  # pytype: disable=signature-mismatch
+        """
+        Extends base ``_deserialize`` method to initialize ``items`` as a dict from
+        view IDs to :class:`mmif.serialize.view.View` objects.
+
+        :param input_list: the JSON data that defines the list of views
+        :return: None
+        """
+        if input_list:
+            self._items = {item['id']: View(item) for item in input_list}
+
+    def append(self, value: View, overwrite=False) -> None:
+        """
+        Appends a view to the list.
+
+        Fails if there is already a view with the same ID
+        in the list, unless ``overwrite`` is set to True.
+
+        :param value: the :class:`mmif.serialize.view.View`
+                      object to add
+        :param overwrite: if set to True, will overwrite an
+                          existing view with the same ID
+        :raises KeyError: if ``overwrite`` is set to False and
+                          a view with the same ID exists
+                          in the list
+        :return: None
+        """
+        super()._append_with_key(value.id, value, overwrite)
+
+    def get_last(self) -> Optional[View]:
+        """
+        Returns the last view appended to the list.
+        """
+        for view in reversed(self._items.values()):
+            if 'error' not in view.metadata and 'warning' not in view.metadata:
+                return view
+
+
 class Mmif(MmifObject):
     """
     MmifObject that represents a full MMIF file.
@@ -511,7 +609,74 @@ class Mmif(MmifObject):
                 if at_types in view.metadata.contains:
                     return view
         return None
-    
+
+    def _is_in_time_between(self, start: Union[int, float], end: Union[int, float], annotation: Annotation) -> bool:
+        s, e = self.get_start(annotation), self.get_end(annotation)
+        return (s < start < e) or (s > start and e < end) or (s < end < e)
+
+    def _handle_time_unit(self, input_unit: str, ann_unit: str,
+                          start: int, end: int) -> Tuple[Union[int, float, str], Union[int, float, str]]:
+        from mmif.utils.timeunit_helper import convert
+        start = convert(start, input_unit, ann_unit, 1)
+        end = convert(end, input_unit, ann_unit, 1)
+        return start, end
+
+    def get_annotations_between_time(self, start: int, end: int, time_unit: str = "milliseconds") -> Iterator[Annotation]:
+        """
+        Version: 1.0
+        Returns all 'Token' annotations aligned with 'TimeFrame' annotations sorted by start time within start and end time
+        Note: this function only works for mmif object obtained from Whisper-wrapper
+
+        :param start: the start time
+        :param end: the end time
+        :param time_unit: the time unit, either string "milliseconds" or "seconds", defaults to "milliseconds"
+        :return: a generator of 'Token' annotations
+        """
+        assert start <= end, "Start time must be less than end time"
+        assert start >= 0, "Start time must be greater than or equal to zero"
+        assert end >= 0, "End time must be greater than or equal to zero"
+        # 0. Initialize container and helper method
+        valid_tf_anns = []
+        tf_to_anns = defaultdict(list)
+
+        # 1. find all views that contain the type of TF
+        views = self.get_all_views_contain([AnnotationTypes.TimeFrame, AnnotationTypes.Alignment])
+
+        # 2. For each view, extract annotations that satisfy conditions that are TF/TP and fall into time interval
+        for view in views:
+            # Make sure time unit stay at the same level
+            start_time, end_time = self._handle_time_unit(time_unit, view.metadata.contains.get(AnnotationTypes.TimeFrame)["timeUnit"],
+                                                          start, end)
+            tf_anns = view.get_annotations(at_type=AnnotationTypes.TimeFrame)
+            al_anns = view.get_annotations(at_type=AnnotationTypes.Alignment)
+
+            # Select 'TimeFrame' annotations within given time interval
+            for tf in tf_anns:
+                if self._is_in_time_between(start_time, end_time, tf):
+                    valid_tf_anns.append(tf)
+
+            # Map 'TimeFrame' annotation to its aligned annotation
+            for align in al_anns:
+                source_id, target_id = align.get_property('source'), align.get_property('target')
+                to_long_id = lambda x: x if self.id_delimiter in x else f'{view.id}{self.id_delimiter}{x}'
+                try:
+                    source, target = view.get_annotation_by_id(source_id), view.get_annotation_by_id(target_id)
+                    if source in valid_tf_anns:
+                        tf_to_anns[to_long_id(source_id)].append(target)
+                    elif target in valid_tf_anns:
+                        tf_to_anns[to_long_id(target_id)].append(source)
+                except KeyError:
+                    pass
+
+        # 3. For those extracted 'TimeFrame' annotations, sort them by their start time
+        sort_tf_anns = sorted(valid_tf_anns, key=lambda x: self.get_start(x))
+
+        # 4. Yield all annotations aligned with sorted 'TimeFrame' annotations
+        for tf_ann in sort_tf_anns:
+            anns = tf_to_anns[tf_ann.long_id]
+            for ann in anns:
+                yield ann
+
     def _get_linear_anchor_point(self, ann: Annotation, targets_sorted=False, start: bool = True) -> Union[int, float]:
         # TODO (krim @ 2/5/24): Update the return type once timeunits are unified to `ms` as integers (https://github.com/clamsproject/mmif/issues/192)
         """
@@ -560,131 +725,41 @@ class Mmif(MmifObject):
         """
         return self._get_linear_anchor_point(annotation, start=False)
 
-    # pytype: disable=bad-return-type
-    def __getitem__(self, item: str) -> Union[Document, View, Annotation]:
+    def __getitem__(self, item: str) \
+            -> Union[Document, View, Annotation, MmifMetadata, DocumentsList, ViewsList]:
         """
-        getitem implementation for Mmif. When nothing is found, this will raise an error
-        rather than returning a None (although pytype doesn't think so...)
+        getitem implementation for Mmif. This will try to find any object, given an identifier or an immediate 
+        attribute name. When nothing is found, this will raise an error rather than returning a None 
 
         :raises KeyError: if the item is not found or if the search results are ambiguous
-        :param item: the search string, a document ID, a view ID, or a view-scoped annotation ID
+        :param item: an attribute name or an object identifier (a document ID, a view ID, or an annotation ID). When 
+                     annotation ID is given as a "short" ID (without view ID prefix), the method will try to find a 
+                     match from the first view, and return immediately if found.
         :return: the object searched for
+        :raise KeyError: if the item is not found or multiple objects are found with the same ID
         """
         if item in self._named_attributes():
             return self.__dict__[item]
         split_attempt = item.split(self.id_delimiter)
 
-        document_result = self.documents.get(split_attempt[0])
-        view_result = self.views.get(split_attempt[0])
+        found = []
 
         if len(split_attempt) == 1:
-            anno_result = None
-        elif view_result:
-            anno_result = view_result[split_attempt[1]]
+            found.append(self.documents.get(split_attempt[0]))
+            found.append(self.views.get(split_attempt[0]))
+            for view in self.views:
+                found.append(view.annotations.get(split_attempt[0]))
+        elif len(split_attempt) == 2:
+            v = self.get_view_by_id(split_attempt[0])
+            if v is not None:
+                found.append(v.annotations.get(split_attempt[1]))
         else:
             raise KeyError("Tried to subscript into a view that doesn't exist")
+        found = [x for x in found if x is not None]
 
-        if view_result and document_result:
+        if len(found) > 1:
             raise KeyError("Ambiguous ID search result")
-        if not (view_result or document_result):
+        elif len(found) == 0:
             raise KeyError("ID not found: %s" % item)
-        return anno_result or view_result or document_result
-    # pytype: enable=bad-return-type
-
-
-class MmifMetadata(MmifObject):
-    """
-    Basic MmifObject class to contain the top-level metadata of a MMIF file.
-
-    :param metadata_obj: the JSON data
-    """
-
-    def __init__(self, metadata_obj: Optional[Union[bytes, str, dict]] = None) -> None:
-        # TODO (krim @ 10/7/20): there could be a better name and a better way to give a value to this
-        self.mmif: str = f"http://mmif.clams.ai/{mmif.__specver__}"
-        self._required_attributes = ["mmif"]
-        super().__init__(metadata_obj)
-
-
-class DocumentsList(DataList[Document]):
-    """
-    DocumentsList object that implements :class:`mmif.serialize.model.DataList`
-    for :class:`mmif.serialize.document.Document`.
-    """
-    _items: Dict[str, Document]
-
-    def _deserialize(self, input_list: list) -> None:  # pytype: disable=signature-mismatch
-        """
-        Extends base ``_deserialize`` method to initialize ``items`` as a dict from
-        document IDs to :class:`mmif.serialize.document.Document` objects.
-
-        :param input_list: the JSON data that defines the list of documents
-        :return: None
-        """
-        self._items = {item['properties']['id']: Document(item) for item in input_list}
-
-    def append(self, value: Document, overwrite=False) -> None:
-        """
-        Appends a document to the list.
-
-        Fails if there is already a document with the same ID
-        in the list, unless ``overwrite`` is set to True.
-
-        :param value: the :class:`mmif.serialize.document.Document`
-                      object to add
-        :param overwrite: if set to True, will overwrite an
-                          existing document with the same ID
-        :raises KeyError: if ``overwrite`` is set to False and
-                          a document with the same ID exists
-                          in the list
-        :return: None
-        """
-        super()._append_with_key(value.id, value, overwrite)
-
-
-class ViewsList(DataList[View]):
-    """
-    ViewsList object that implements :class:`mmif.serialize.model.DataList`
-    for :class:`mmif.serialize.view.View`.
-    """
-    _items: Dict[str, View]
-    
-    def __init__(self, mmif_obj: Optional[Union[bytes, str, list]] = None):
-        super().__init__(mmif_obj)
-
-    def _deserialize(self, input_list: list) -> None:  # pytype: disable=signature-mismatch
-        """
-        Extends base ``_deserialize`` method to initialize ``items`` as a dict from
-        view IDs to :class:`mmif.serialize.view.View` objects.
-
-        :param input_list: the JSON data that defines the list of views
-        :return: None
-        """
-        if input_list:
-            self._items = {item['id']: View(item) for item in input_list}
-
-    def append(self, value: View, overwrite=False) -> None:
-        """
-        Appends a view to the list.
-
-        Fails if there is already a view with the same ID
-        in the list, unless ``overwrite`` is set to True.
-
-        :param value: the :class:`mmif.serialize.view.View`
-                      object to add
-        :param overwrite: if set to True, will overwrite an
-                          existing view with the same ID
-        :raises KeyError: if ``overwrite`` is set to False and
-                          a view with the same ID exists
-                          in the list
-        :return: None
-        """
-        super()._append_with_key(value.id, value, overwrite)
-
-    def get_last(self) -> Optional[View]:
-        """
-        Returns the last view appended to the list.
-        """
-        for view in reversed(self._items.values()):
-            if 'error' not in view.metadata and 'warning' not in view.metadata:
-                return view
+        else:
+            return found[-1]

mmif_python-1.0.16/mmif/utils/text_document_helper.py

@@ -0,0 +1,12 @@
+import mmif
+from mmif import Annotation
+
+
+def slice_text(mmif_obj, start: int, end: int, unit: str = "milliseconds") -> str:
+    token_type = "http://vocab.lappsgrid.org/Token"
+    anns_found = mmif_obj.get_annotations_between_time(start, end, unit)
+    tokens_sliced = []
+    for ann in anns_found:
+        if ann.is_type(token_type):
+            tokens_sliced.append(ann.get_property('word'))
+    return ' '.join(tokens_sliced)

{mmif-python-1.0.14 → mmif_python-1.0.16}/mmif/utils/video_document_helper.py

@@ -6,7 +6,7 @@ import math
 import mmif
 from mmif import Annotation, Document, Mmif
 from mmif.utils.timeunit_helper import convert
-from mmif.vocabulary import DocumentTypes
+from mmif.vocabulary import DocumentTypes, AnnotationTypes
 
 for cv_dep in ('cv2', 'ffmpeg', 'PIL'):
     try:
@@ -83,14 +83,16 @@ def extract_frames_as_images(video_document: Document, framenums: List[int], as_
     frames = []
     video = capture(video_document)
     cur_f = 0
+    tot_fcount = video_document.get_property(FRAMECOUNT_DOCPROP_KEY)
     while True:
-        if not framenums or cur_f > video_document.get_property(FRAMECOUNT_DOCPROP_KEY):
+        if not framenums or cur_f > tot_fcount:
             break
         ret, frame = video.read()
         if cur_f == framenums[0]:
             if not ret:
                 sec = convert(cur_f, 'f', 's', video_document.get_property(FPS_DOCPROP_KEY))
                 warnings.warn(f'Frame #{cur_f} ({sec}s) could not be read from the video {video_document.id}.')
+                cur_f += 1
                 continue
             frames.append(Image.fromarray(frame[:, :, ::-1]) if as_PIL else frame)
             framenums.pop(0)
@@ -125,6 +127,42 @@ def extract_mid_frame(mmif: Mmif, time_frame: Annotation, as_PIL: bool = False):
     return extract_frames_as_images(vd, [get_mid_framenum(mmif, time_frame)], as_PIL=as_PIL)[0]
 
 
+def get_representative_framenum(mmif: Mmif, time_frame: Annotation):
+    """
+    Calculates the representative frame number from an annotation.
+
+    :param mmif: :py:class:`~mmif.serialize.mmif.Mmif` instance
+    :param time_frame: :py:class:`~mmif.serialize.annotation.Annotation` instance that holds a time interval annotation containing a `representatives` property (``"@type": ".../TimeFrame/..."``)
+    :return: representative frame number as an integer
+    """
+    if 'representatives' not in time_frame.properties:
+        raise ValueError(f'The time frame {time_frame.id} does not have a representative.')
+    timeunit = time_frame.get_property('timeUnit')
+    video_document = mmif[time_frame.get_property('document')]
+    fps = get_framerate(video_document)
+    representatives = time_frame.get_property('representatives')
+    top_representative_id = representatives[0]
+    try:
+        representative_timepoint_anno = mmif[time_frame._parent_view_id+time_frame.id_delimiter+top_representative_id]
+    except KeyError:
+        raise ValueError(f'Representative timepoint {top_representative_id} not found in any view.')
+    return convert(representative_timepoint_anno.get_property('timePoint'), timeunit, 'frame', fps)
+
+
+def extract_representative_frame(mmif: Mmif, time_frame: Annotation, as_PIL: bool = False):
+    """
+    Extracts the representative frame of an annotation as a numpy ndarray or PIL Image.
+
+    :param mmif: :py:class:`~mmif.serialize.mmif.Mmif` instance
+    :param time_frame: :py:class:`~mmif.serialize.annotation.Annotation` instance that holds a time interval annotation (``"@type": ".../TimeFrame/..."``)
+    :param as_PIL: return :py:class:`~PIL.Image.Image` instead of :py:class:`~numpy.ndarray`
+    :return: frame as a :py:class:`numpy.ndarray` or :py:class:`PIL.Image.Image`
+    """
+    video_document = mmif[time_frame.get_property('document')]
+    rep_frame_num = get_representative_framenum(mmif, time_frame)
+    return extract_frames_as_images(video_document, [rep_frame_num], as_PIL=as_PIL)[0]
+
+
 def sample_frames(start_frame: int, end_frame: int, sample_rate: float = 1) -> List[int]:
     """
     Helper function to sample frames from a time interval.

mmif_python-1.0.16/mmif/ver/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "1.0.16"
+__specver__ = "1.0.4"

mmif_python-1.0.16/mmif_python.egg-info/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.1
+Name: mmif-python
+Version: 1.0.16
+Summary: Python implementation of MultiMedia Interchange Format specification. (https://mmif.clams.ai)
+Home-page: https://mmif.clams.ai
+Author: Brandeis Lab for Linguistics and Computation
+Author-email: admin@clams.ai
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers 
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: deepdiff>5
+Requires-Dist: jsonschema
+Provides-Extra: seq
+Requires-Dist: numpy; extra == "seq"
+Provides-Extra: cv
+Requires-Dist: pillow; extra == "cv"
+Requires-Dist: opencv-python; extra == "cv"
+Requires-Dist: ffmpeg-python; extra == "cv"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-pep8; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytype; extra == "dev"
+
+## MultiMedia Interchange Format
+[MMIF](https://mmif.clams.ai) is a JSON(-LD)-based data format designed for transferring annotation data between computational analysis applications in [CLAMS project](https://clams.ai). 
+
+
+## mmif-python
+`mmif-python` is a Python implementation of the MMIF data format. 
+`mmif-python` provides various helper classes and functions to handle MMIF JSON in Python, 
+including ; 
+
+1. de-/serialization of MMIF internal data structures to/from JSON
+2. validation of MMIF JSON
+3. handling of CLAMS vocabulary types
+4. navigation of MMIF object via various "search" methods (e.g. `mmif.get_all_views_contain(vocab_type))`)
+
+## For more ...
+* [Version history and patch notes](https://github.com/clamsproject/mmif-python/blob/main/CHANGELOG.md)
+* [MMIF Python API documentation](https://clamsproject.github.io/mmif-python)
+* [MMIF JSON specification and schema](https://clamsproject.github.io/mmif)

{mmif-python-1.0.14 → mmif_python-1.0.16}/mmif_python.egg-info/SOURCES.txt

@@ -18,6 +18,7 @@ mmif/serialize/model.py
 mmif/serialize/view.py
 mmif/utils/__init__.py
 mmif/utils/sequence_helper.py
+mmif/utils/text_document_helper.py
 mmif/utils/timeunit_helper.py
 mmif/utils/video_document_helper.py
 mmif/ver/__init__.py
@@ -32,4 +33,8 @@ mmif_python.egg-info/PKG-INFO
 mmif_python.egg-info/SOURCES.txt
 mmif_python.egg-info/dependency_links.txt
 mmif_python.egg-info/requires.txt
-mmif_python.egg-info/top_level.txt
+mmif_python.egg-info/top_level.txt
+tests/test_serialize.py
+tests/test_utils.py
+tests/test_versioncompat.py
+tests/test_vocab.py