mmif.utils module

mmif.utils.video_document_helper module

mmif.utils.video_document_helper.capture(video_document: Document)

Captures a video file using OpenCV and adds fps, frame count, and duration as properties to the document.

Parameters:

video_document – Document instance that holds a video document ("@type": ".../VideoDocument/...")

Returns:

OpenCV VideoCapture object

mmif.utils.video_document_helper.convert_timeframe(mmif: Mmif, time_frame: Annotation, out_unit: str) → Tuple[int | float | str, int | float | str]

Converts start and end points in a TimeFrame annotation a different time unit.

Parameters:

• mmif – Mmif instance

• time_frame – Annotation instance that holds a time interval annotation ("@type": ".../TimeFrame/...")

• out_unit – time unit to which the point is converted

Returns:

tuple of frame numbers (integer) or seconds/milliseconds (float) of input start and end

mmif.utils.video_document_helper.convert_timepoint(mmif: Mmif, timepoint: Annotation, out_unit: str) → int | float | str

Converts a time point included in an annotation to a different time unit. The input annotation must have timePoint property.

Parameters:

• mmif – input MMIF to obtain fps and input timeunit

• timepoint – Annotation instance with timePoint property

• out_unit – time unit to which the point is converted (frames, seconds, milliseconds)

Returns:

frame number (integer) or second/millisecond (float) of input timepoint

mmif.utils.video_document_helper.extract_frames_as_images(video_document: Document, framenums: List[int], as_PIL: bool = False)

Extracts frames from a video document as a list of numpy.ndarray. Use with sample_frames() function to get the list of frame numbers first.

Parameters:

• video_document – Document instance that holds a video document ("@type": ".../VideoDocument/...")

• framenums – integers representing the frame numbers to extract

• as_PIL – return PIL.Image.Image instead of ndarray

Returns:

frames as a list of ndarray or Image

mmif.utils.video_document_helper.extract_mid_frame(mmif: Mmif, time_frame: Annotation, as_PIL: bool = False)

Extracts the middle frame of a time interval annotation as a numpy ndarray.

Parameters:

• mmif – Mmif instance

• time_frame – Annotation instance that holds a time interval annotation ("@type": ".../TimeFrame/...")

• as_PIL – return Image instead of ndarray

Returns:

frame as a numpy.ndarray or PIL.Image.Image

mmif.utils.video_document_helper.framenum_to_millisecond(video_doc: Document, frame: int)

Converts a frame number to a millisecond value.

mmif.utils.video_document_helper.framenum_to_second(video_doc: Document, frame: int)

Converts a frame number to a second value.

mmif.utils.video_document_helper.get_annotation_property(mmif, annotation, prop_name)

Deprecated since version 1.0.8: Use mmif.serialize.annotation.Annotation.get_property() method instead.

Get a property value from an annotation. If the property is not found in the annotation, it will look up the metadata of the annotation’s parent view and return the value from there. xisting

mmif.utils.video_document_helper.get_framerate(video_document: Document) → float

Gets the frame rate of a video document. First by checking the fps property of the document, then by capturing the video.

Parameters:

video_document – Document instance that holds a video document ("@type": ".../VideoDocument/...")

Returns:

frames per second as a float, rounded to 2 decimal places

mmif.utils.video_document_helper.get_mid_framenum(mmif: Mmif, time_frame: Annotation)

Calculates the middle frame number of a time interval annotation.

Parameters:

• mmif – Mmif instance

• time_frame – Annotation instance that holds a time interval annotation ("@type": ".../TimeFrame/...")

Returns:

middle frame number as an integer

mmif.utils.video_document_helper.millisecond_to_framenum(video_doc: Document, millisecond: float) → int

Converts a millisecond value to a frame number.

mmif.utils.video_document_helper.sample_frames(start_frame: int, end_frame: int, sample_ratio: int = 1) → List[int]

Helper function to sample frames from a time interval. Can also be used as a “cutoff” function when used with start_frame==0 and sample_ratio==1.

Parameters:

• start_frame – start frame of the interval

• end_frame – end frame of the interval

• sample_ratio – sample ratio (or step) to configure how often to take a frame, default is 1, meaning all consecutive frames are sampled

mmif.utils.video_document_helper.second_to_framenum(video_doc: Document, second) → int

Converts a second value to a frame number.