mmif-python 1.0.2__tar.gz → 1.0.7__tar.gz

{mmif-python-1.0.2 → mmif-python-1.0.7}/MANIFEST.in

@@ -1,4 +1,5 @@
 # only copied in sdist and be used when building
 include ./VERSION
 include ./requirements.txt
+include ./requirements.cv
 

{mmif-python-1.0.2/mmif_python.egg-info → mmif-python-1.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mmif-python
-Version: 1.0.2
+Version: 1.0.7
 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
@@ -17,4 +17,5 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
+Provides-Extra: cv
 Provides-Extra: dev

mmif-python-1.0.7/VERSION

@@ -0,0 +1 @@
+1.0.7

mmif-python-1.0.7/mmif/__init__.py

@@ -0,0 +1,17 @@
+import importlib.resources
+
+# DO NOT CHANGE THIS ORDER, important to prevent circular imports
+from mmif.ver import __version__
+from mmif.ver import __specver__
+from mmif.vocabulary import *
+from mmif.serialize import *
+
+_res_pkg = 'res'
+_ver_pkg = 'ver'
+_vocabulary_pkg = 'vocabulary'
+_schema_res_name = 'mmif.json'
+
+
+def get_mmif_json_schema():
+    # TODO (krim @ 7/14/23): use `as_file` after dropping support for Python 3.8
+    return importlib.resources.read_text(f'{__package__}.{_res_pkg}', _schema_res_name)

{mmif-python-1.0.2 → mmif-python-1.0.7}/mmif/serialize/annotation.py

@@ -8,6 +8,7 @@ of a view. For documentation on how views are represented, see
 """
 import importlib
 import itertools
+import os
 import pathlib
 import pkgutil
 import re
@@ -135,6 +136,13 @@ class Annotation(MmifObject):
     def __getitem__(self, prop_name: str):
         return self.get(prop_name)
     
+    def __contains__(self, item):
+        try:
+            self.get(item)
+            return True
+        except KeyError:
+            return False
+    
     def is_document(self):
         return isinstance(self.at_type, DocumentTypesBase)
 
@@ -219,7 +227,15 @@ class Document(Annotation):
         the three properties in a specific order so that the latest value is 
         returned, in case there are multiple values for the same key.
         """
-        if prop_name in self._props_temporary:
+        if prop_name == 'id':
+            # because all three dicts have `id` key as required field, we need
+            # this special case to return the correct value from the correct dict
+            return self.id
+        elif prop_name == 'location':
+            # because location is internally stored in self.location_,
+            # it doesn't work with regular __getitem__ method
+            return self.location
+        elif prop_name in self._props_temporary:
             return self._props_temporary[prop_name]
         elif prop_name in self._props_existing:
             return self._props_existing[prop_name]
@@ -378,7 +394,7 @@ class DocumentProperties(AnnotationProperties):
         if "location_" in serialized:
             serialized["location"] = serialized.pop("location_")
         return serialized
-
+    
     @property
     def text_language(self) -> str:
         return self.text.lang
@@ -438,7 +454,7 @@ class DocumentProperties(AnnotationProperties):
         warnings.warn('location_path() is deprecated. Use location_path_resolved() instead.', DeprecationWarning)
         return self.location_path_resolved()
     
-    def location_path_resolved(self) -> Optional[str]:
+    def location_path_resolved(self, nonexist_ok=True) -> Optional[str]:
         """
         Retrieves only path name of the document location (hostname is ignored), 
         and then try to resolve the path name in the local file system.
@@ -452,11 +468,15 @@ class DocumentProperties(AnnotationProperties):
             return None
         scheme = self.location_scheme()
         if scheme in ('', 'file'):
-            return urlparse(self.location).path
+            p = urlparse(self.location).path
         elif scheme in discovered_docloc_plugins:
-            return discovered_docloc_plugins[scheme].resolve(self.location)
+            p = discovered_docloc_plugins[scheme].resolve(self.location)
         else:
             raise ValueError(f'Cannot resolve location of scheme "{scheme}". Interested in developing mmif-locdoc-{scheme} plugin? See https://clams.ai/mmif-python/plugins')
+        if not nonexist_ok and not os.path.exists(p):
+            raise FileNotFoundError(f'Cannot find file "{p}"')
+        else:
+            return p
 
     def location_path_literal(self) -> Optional[str]:
         """

{mmif-python-1.0.2 → mmif-python-1.0.7}/mmif/serialize/model.py

@@ -11,15 +11,13 @@ core functionality for deserializing MMIF JSON data into live objects
 and serializing live objects into MMIF JSON data. Specialized behavior
 for the different components of MMIF is added in the subclasses.
 """
+
 import json
 from datetime import datetime
-from types import MethodType
 from typing import Union, Any, Dict, Optional, TypeVar, Generic, Generator, Iterator, Type, Set
 
 from deepdiff import DeepDiff
 
-import mmif
-
 T = TypeVar('T')
 S = TypeVar('S')
 JSON_PRMTV_TYPES: Type = Union[str, int, float, bool, None]
@@ -105,8 +103,6 @@ class MmifObject(object):
             self._unnamed_attributes = {}
         if mmif_obj is not None:
             self.deserialize(mmif_obj)
-        for method in mmif.patches[self.__class__]:
-            setattr(self, method.__name__, MethodType(method, self))
 
     def disallow_additional_properties(self) -> None:
         """

mmif-python-1.0.7/mmif/utils/__init__.py

@@ -0,0 +1 @@
+from mmif.utils import video_document_helper

mmif-python-1.0.7/mmif/utils/video_document_helper.py

@@ -0,0 +1,208 @@
+import importlib
+import warnings
+from typing import List, Union, Tuple
+
+import mmif
+from mmif import Annotation, Document, Mmif
+from mmif.vocabulary import DocumentTypes
+
+for cv_dep in ('cv2', 'ffmpeg', 'PIL'):
+    try:
+        importlib.__import__(cv_dep)
+    except ImportError as e:
+        warnings.warn(f"Optional package \"{e.name}\" is not found. "
+                      f"You might want to install Computer-Vision dependencies "
+                      f"by running `pip install mmif-python[cv]=={mmif.__version__}`")
+
+
+FPS_DOCPROP_KEY = 'fps'
+DURATION_DOCPROP_KEY = 'duration'
+DURATIONUNIT_DOCPROP_KEY = 'durationTimeUnit'
+                           
+UNIT_NORMALIZATION = {
+    'm': 'millisecond',
+    'ms': 'millisecond',
+    'msec': 'millisecond',
+    'millisecond': 'millisecond',
+    'milliseconds': 'millisecond',
+    's': 'second',
+    'se': 'second',
+    'sec': 'second',
+    'second': 'second',
+    'seconds': 'second',
+    'f': 'frame',
+    'fr': 'frame',
+    'frame': 'frame',
+    'frames': 'frame',
+}
+
+
+def capture(vd: Document):
+    import cv2  # pytype: disable=import-error
+    if vd is None or vd.at_type != DocumentTypes.VideoDocument:
+        raise ValueError(f'The document does not exist.')
+
+    v = cv2.VideoCapture(vd.location_path())
+    vd.add_property(FPS_DOCPROP_KEY, v.get(cv2.CAP_PROP_FPS))
+    vd.add_property(DURATION_DOCPROP_KEY, v.get(cv2.CAP_PROP_FRAME_COUNT))
+    vd.add_property(DURATIONUNIT_DOCPROP_KEY, 'frames')
+    return v
+
+
+def get_framerate(vd: Document) -> float:
+    if vd is None or vd.at_type != DocumentTypes.VideoDocument:
+        raise ValueError(f'The document does not exist.')
+
+    framerate_keys = (FPS_DOCPROP_KEY, 'framerate')
+    for k in framerate_keys:
+        if k in vd:
+            fps = vd.get_property(k)
+            return fps
+    capture(vd)
+    return vd.get_property(FPS_DOCPROP_KEY)
+
+
+def extract_frames_as_images(vd: Document, framenums: List[int], as_PIL: bool = False):
+    """
+    Extracts frames from a video document as a list of numpy arrays.
+    Use `sample_frames` function in this module to get the list of frame numbers first. 
+    
+    :param vd: VideoDocument object that holds the video file location
+    :param framenums: integers representing the frame numbers to extract
+    :param as_PIL: use PIL.Image instead of numpy.ndarray
+    :return: frames as a list of numpy arrays or PIL.Image objects
+    """
+    import cv2  # pytype: disable=import-error
+    if as_PIL:
+        from PIL import Image
+    frames = []
+    video = capture(vd)
+    for framenum in framenums:
+        video.set(cv2.CAP_PROP_POS_FRAMES, framenum)
+        ret, frame = video.read()
+        if ret:
+            frames.append(Image.fromarray(frame[:, :, ::-1]) if as_PIL else frame)
+        else:
+            break
+    return frames
+
+
+def get_mid_framenum(mmif: Mmif, tf: Annotation):
+    """
+    Extracts the middle frame from a video document
+    """
+    timeunit = get_annotation_property(mmif, tf, 'timeUnit')
+    vd = mmif[get_annotation_property(mmif, tf, 'document')]
+    fps = get_framerate(vd)
+    return sum(convert(float(tf.get_property(timepoint_propkey)), timeunit, 'frame', fps) for timepoint_propkey in ('start', 'end')) // 2
+
+
+def extract_mid_frame(mmif: Mmif, tf: Annotation, as_PIL: bool = False):
+    vd = mmif[get_annotation_property(mmif, tf, 'document')]
+    return extract_frames_as_images(vd, [get_mid_framenum(mmif, tf)], as_PIL=as_PIL)[0]
+
+
+def sample_frames(start_frame: int, end_frame: int, sample_ratio: int = 1) -> List[int]:
+    """
+    Helper function to sample frames from a time interval.
+    When start_frame is 0 and end_frame is X, this function basically works as "cutoff". 
+    
+    :param start_frame: start frame of the interval
+    :param end_frame: end frame of the interval
+    :param sample_ratio: sample ratio or sample step, default is 1, meaning all consecutive frames are sampled
+    """
+    sample_ratio = int(sample_ratio)
+    if sample_ratio < 1:
+        raise ValueError(f"Sample ratio must be greater than 1, but got {sample_ratio}")
+    frame_nums: List[int] = []
+    for i in range(start_frame, end_frame, sample_ratio):
+        frame_nums.append(i)
+    return frame_nums
+
+
+def convert(time: Union[int, float], in_unit: str, out_unit: str, fps: float) -> Union[int, float]:
+    try:
+        in_unit = UNIT_NORMALIZATION[in_unit]
+    except KeyError:
+        raise ValueError(f"Not supported time unit: {in_unit}")
+    try:
+        out_unit = UNIT_NORMALIZATION[out_unit]
+    except KeyError:
+        raise ValueError(f"Not supported time unit: {out_unit}")
+    # s>s, ms>ms, f>f
+    if in_unit == out_unit:
+        return time
+    elif out_unit == 'frame':
+        # ms>f
+        if 'millisecond' == in_unit:
+            return int(time / 1000 * fps)
+        # s>f
+        elif 'second' == in_unit:
+            return int(time * fps)
+    # s>ms
+    elif in_unit == 'second':
+        return time * 1000
+    # ms>s
+    elif in_unit == 'millisecond':
+        return time // 1000
+    # f>ms, f>s
+    else:
+        return (time / fps) if out_unit == 'second' else (time / fps * 1000)  # pytype: disable=bad-return-type
+
+def get_annotation_property(mmif, annotation, prop_name):
+    # TODO (krim @ 7/18/23): this probably should be merged to the main mmif.serialize packge
+    if prop_name in annotation:
+        return annotation.get_property(prop_name)
+    try:
+        return mmif[annotation.parent].metadata.contains[annotation.at_type][prop_name]
+    except KeyError:
+        raise KeyError(f"Annotation {annotation.id} does not have {prop_name} property.")
+
+def convert_timepoint(mmif: Mmif, timepoint: Annotation, out_unit: str) -> Union[int, float]:
+    """
+    Converts a time point included in an annotation to a different time unit.
+    The input annotation must have ``timePoint`` property. 
+
+    :param mmif: input MMIF to obtain fps and input timeunit
+    :param timepoint: annotation with ``timePoint`` property
+    :param out_unit: time unit to which the point is converted
+    :return: frame number (integer) or second/millisecond (float) of input timepoint
+    """
+    in_unit = get_annotation_property(mmif, timepoint, 'timeUnit')
+    vd = mmif[get_annotation_property(mmif, timepoint, 'document')]
+    return convert(timepoint.get_property('timePoint'), in_unit, out_unit, get_framerate(vd))
+
+def convert_timeframe(mmif: Mmif, timeframe: Annotation, out_unit: str) -> Union[Tuple[int, int], Tuple[float, float]]:
+    """
+    Converts start and end points in a TimeFrame annotation a different time unit.
+
+    :param mmif: input MMIF to obtain fps and input timeunit
+    :param timeframe: ``TimeFrame` type annotation
+    :param out_unit: time unit to which the point is converted
+    :return: tuple of frame numbers (integer) or seconds/milliseconds (float) of input start and end
+    """
+    in_unit = get_annotation_property(mmif, timeframe, 'timeUnit')
+    vd = mmif[get_annotation_property(mmif, timeframe, 'document')]
+    return convert(timeframe.get_property('start'), in_unit, out_unit, get_framerate(vd)), \
+        convert(timeframe.get_property('end'), in_unit, out_unit, get_framerate(vd))
+
+
+
+def framenum_to_second(video_doc: Document, frame: int):
+    fps = get_framerate(video_doc)
+    return convert(frame, 'f', 's', fps)
+
+
+def framenum_to_millisecond(video_doc: Document, frame: int):
+    fps = get_framerate(video_doc)
+    return convert(frame, 'f', 'ms', fps)
+
+
+def second_to_framenum(video_doc: Document, second) -> int:
+    fps = get_framerate(video_doc)
+    return int(convert(second, 's', 'f', fps))
+
+
+def millisecond_to_framenum(video_doc: Document, millisecond: float) -> int:
+    fps = get_framerate(video_doc)
+    return int(convert(millisecond, 'ms', 'f', fps))

mmif-python-1.0.7/mmif/ver/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "1.0.7"
+__specver__ = "1.0.0"

{mmif-python-1.0.2 → mmif-python-1.0.7/mmif_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mmif-python
-Version: 1.0.2
+Version: 1.0.7
 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
@@ -17,4 +17,5 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
+Provides-Extra: cv
 Provides-Extra: dev

{mmif-python-1.0.2 → mmif-python-1.0.7}/mmif_python.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ MANIFEST.in
 README.md
 setup.py
 ./VERSION
+./requirements.cv
 ./requirements.txt
 mmif/__init__.py
 mmif/res/__init__.py
@@ -14,6 +15,8 @@ mmif/serialize/annotation.py
 mmif/serialize/mmif.py
 mmif/serialize/model.py
 mmif/serialize/view.py
+mmif/utils/__init__.py
+mmif/utils/video_document_helper.py
 mmif/ver/__init__.py
 mmif/ver/do-not-edit.txt
 mmif/vocabulary/__init__.py

{mmif-python-1.0.2 → mmif-python-1.0.7}/mmif_python.egg-info/requires.txt

@@ -1,6 +1,11 @@
 deepdiff>5
 jsonschema
 
+[cv]
+pillow
+opencv-python
+ffmpeg-python
+
 [dev]
 pytest
 pytest-pep8

mmif-python-1.0.7/requirements.cv

@@ -0,0 +1,3 @@
+pillow
+opencv-python
+ffmpeg-python

{mmif-python-1.0.2 → mmif-python-1.0.7}/setup.py

@@ -269,6 +269,9 @@ with open('README.md') as readme:
 with open('requirements.txt') as requirements:
     requires = requirements.readlines()
 
+with open('requirements.cv') as requirements:
+    cv_requires = requirements.readlines()
+
 setuptools.setup(
     name=name,
     version=version,
@@ -287,6 +290,7 @@ setuptools.setup(
     },
     install_requires=requires,
     extras_require={
+        'cv': cv_requires,
         'dev': [
             'pytest',
             'pytest-pep8',

mmif-python-1.0.2/VERSION

@@ -1 +0,0 @@
-1.0.2

mmif-python-1.0.2/mmif/__init__.py

@@ -1,36 +0,0 @@
-import importlib
-import pkgutil
-import re
-from collections import defaultdict
-from typing import Dict, Type, Callable, Set
-
-import pkg_resources
-
-# DO NOT CHANGE THIS ORDER, important to prevent circular imports
-from mmif.ver import __version__
-from mmif.ver import __specver__
-from mmif.vocabulary import *
-from mmif.serialize import *
-
-_res_pkg = 'res'
-_ver_pkg = 'ver'
-_vocabulary_pkg = 'vocabulary'
-_schema_res_name = 'mmif.json'
-
-
-def get_mmif_json_schema():
-    res = pkg_resources.resource_stream(f'{__name__}.{_res_pkg}', _schema_res_name)
-    res_str = res.read().decode('utf-8')
-    res.close()
-    return res_str
-
-
-patches: Dict[Type, Set[Callable]] = defaultdict(set)
-for _, name, ispkg in pkgutil.iter_modules():
-    if ispkg and re.match(r'mmif[-_]utils[-_]', name):
-        mod = importlib.import_module(name)
-        for c, ms in mod.patches.items():
-            for m in ms:
-                if m in patches[c]:
-                    raise ValueError(f'Patch for {c}::{m.__name__} already exists.')
-                patches[c].add(m)

mmif-python-1.0.2/mmif/ver/__init__.py

@@ -1,2 +0,0 @@
-__version__ = "1.0.2"
-__specver__ = "1.0.0"