video699.interface

This module defines interfaces, and abstract base classes.

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in the docstrings of this module and modules importing this module are to be interpreted as described in RFC2119.

Module Contents

video699.interface.SCREENABC_CONFIGURATION
video699.interface.SCREENABC_LRU_CACHE_MAXSIZE
video699.interface.IMAGEABC_CONFIGURATION
video699.interface.IMAGEABC_LRU_CACHE_MAXSIZE
class video699.interface.EventABC

Bases: abc.ABC

An abstract event detected in a video.

write_xml(self, xf)

Writes an XML fragment that represents the event to an XML file.

Parameters:xf (lxml.etree.xmlfile) – An XML file.
__repr__(self)
class video699.interface.EventDetectorABC

Bases: abc.ABC, collections.abc.Iterable

An abstract detector of events in a video.

Notes

It MAY be possible to repeatedly iterate over all events detected in a video.

video

VideoABC – The video in which the events are detected.

video
write_xml(self, xf)

Writes an XML document that represents all detected event to an XML file.

Notes

After the first invocation of write_xml, it MAY be possible to call write_xml again and to iterate over all detected events in the video.

Parameters:xf (lxml.etree.xmlfile) – An XML file.
__iter__(self)

Produces an iterator of all events detected in a video.

Notes

After the first iteration, it MAY be possible to call write_xml and to iterate over all detected events in the video again.

Returns:frames – An iterable of events.
Return type:iterator of EventABC
__repr__(self)
class video699.interface.VideoABC

Bases: abc.ABC, collections.abc.Iterable

An abstract video.

Notes

It MAY be possible to repeatedly iterate over all video frames. A video MAY produce non-consecutive frames, i.e. frames with non-consecutive but increasing frame numbers. This MUST be understood as an indication that no important events took place between the two frames.

fps

scalar – The framerate of the video in frames per second.

width

int – The width of the video.

height

int – The height of the video.

datetime

aware datetime – The date, and time at which the video was captured.

uri

string – An IRI, as defined in RFC3987, that uniquely indentifies the video over the entire lifetime of a program.

fps
width
height
datetime
uri
__iter__(self)

Produces an iterator of video frames.

Returns:frames – An iterable of the frames of the video.
Return type:iterator of FrameABC
__repr__(self)
class video699.interface.ImageABC

Bases: abc.ABC

An abstract image represented by an OpenCV CV_8UC3 RGBA matrix.

image

array_like – The image data as an OpenCV CV_8UC3 RGBA matrix, where the alpha channel (A) denotes the weight of a pixel. Fully transparent pixels, i.e. pixels with zero alpha, SHOULD be completely disregarded in subsequent computation.

image
render(self, width=None, height=None)

Renders the image at the specified dimensions.

Parameters:
  • width (int or None, optional) – The width of the image data. When unspecified or None, the implementation MUST pick a width at its own discretion.
  • height (int or None, optional) – The height of the image data. When unspecified or None, the implementation MUST pick a height at its own discretion.
Returns:

image – The image data of the page as an OpenCV CV_8UC3 RGBA matrix, where the alpha channel (A) denotes the weight of a pixel. Fully transparent pixels, i.e. pixels with zero alpha, SHOULD be completely disregarded in subsequent computation. Any margins added to the image data, e.g. by keeping the aspect ratio of the image, MUST be fully transparent.
Return type:

array_like
Raises:

ValueError – When either the width or the height is zero.
class video699.interface.FrameABC

Bases: video699.interface.ImageABC

An abstract frame of a video.

video

VideoABC – The video containing the frame.

number

int – The frame number, i.e. the position of the frame in the video. Frame indexing is one-based, i.e. the first frame has number 1.

image

array_like – The image data of the frame as an OpenCV CV_8UC3 RGBA matrix, where the alpha channel (A) denotes the weight of a pixel. Fully transparent pixels, i.e. pixels with zero alpha, SHOULD be completely disregarded in subsequent computation.

width

int – The width of the image data.

height

int – The height of the image data.

duration

timedelta – The elapsed time since the beginning of the video.

datetime

aware datetime – The date, and time at which the frame was captured.

video
number
width
height
duration
datetime
__hash__(self)
__eq__(self, other)
__lt__(self, other)
__repr__(self)
class video699.interface.ConvexQuadrangleABC

Bases: abc.ABC

A convex quadrangle specifying a map between video frame and projection screen coordinates.

top_left

(scalar, scalar) – The top left corner of the quadrangle in a video frame coordinate system.

top_left_bound

(scalar, scalar) – The top left corner of the minimal bounding box that bounds the quadrangle in a video frame coordinate system.

top_right

(scalar, scalar) – The top right corner of the quadrangle in a video frame coordinate system.

bottom_left

(scalar, scalar) – The bottom left corner of the quadrangle in a video frame coordinate system.

bottom_right

(scalar, scalar) – The bottom right corner of the quadrangle in a video frame coordinate system.

bottom_right_bound

(scalar, scalar) – The bottom right corner of the minimal bounding box that bounds the quadrangle in a video frame coordinate system.

width

int – The width of the quadrangle in the screen coordinate space.

height

int – The height of the quadrangle in the screen coordinate space.

area

scalar – The area of the screen in the video frame coordinate system.

top_left
top_left_bound
top_right
bottom_left
bottom_right
bottom_right_bound
width
height
area
intersection_area(self, other)

The area of the intersection of two convex quadrangles.

Parameters:other (ConvexQuadrangleABC) – The other convex quadrangle.
Returns:intersection_area – The area of the intersection with the other convex quadrangle.
Return type:scalar
union_area(self, other)

The area of the union of two convex quadrangles.

Parameters:other (ConvexQuadrangleABC) – The other convex quadrangle.
Returns:union_area – The area of the union with the other convex quadrangle.
Return type:scalar
transform(self, frame_image)

Transforms image data in the frame coordinate system to the screen coordinate system.

Parameters:frame_image (array_like) – Image data in the video frame coordinate system as an OpenCV CV_8UC3 RGBA matrix, where the alpha channel (A) denotes the weight of a pixel. Fully transparent pixels, i.e. pixels with zero alpha, SHOULD be completely disregarded in subsequent computation.
Returns:screen_image – Image data in the projection screen coordinate system as an OpenCV CV_8UC3 RGBA matrix, where the alpha channel (A) denotes the weight of a pixel. Fully transparent pixels, i.e. pixels with zero alpha, SHOULD be completely disregarded in subsequent computation. Pixels that originate from beyond the boundaries of the frame coordinate system MUST be fully transparent.
Return type:array_like
__hash__(self)
__eq__(self, other)
__lt__(self, other)
__repr__(self)
class video699.interface.ConvexQuadrangleIndexABC

Bases: collections.abc.MutableSet

An abstract index for the retrieval of convex quadrangles.

Notes

All requirements for subclassing collections.abc.MutableSet (such as the requirement for a special constructor signature) apply. Mixin methods of MutableSet (such as __ior__, and __iand__) that are not overriden here MAY be efficiently implemented by subclasses.

quadrangles

read-only set-like object of ConvexQuadrangleABC – The convex quadrangles in the index.

quadrangles
add(self, quadrangle)
discard(self, quadrangle)
clear(self)
jaccard_indexes(self, input_quadrangle)

Retrieves quadrangles intersecting an input quadrangle, computes Jaccard indexes.

Parameters:quadrangle (ConvexQuadrangleABC) – An input convex quadrangle.
Returns:jaccard_indexes – A map between convex quadrangles in the index that intersect the input convex quadrangle, and the Jaccard indexes between the input convex quadrangle and the convex quadrangles in the index. All Jaccard indexes MUST be greater than zero.
Return type:dict of (ConvexQuadrangleABC, scalar)
__contains__(self, quadrangle)
__iter__(self)
__len__(self)
class video699.interface.MovingConvexQuadrangleABC

Bases: abc.ABC, collections.abc.Iterable

An abstract convex quadrangle that moves in time.

Notes

It MUST be possible to repeatedly iterate over all tracked convex quadrangles. MovingConvexQuadrangleABC objects corresponding to a single conceptual moving quadrangle MUST compare equal.

current_quadrangle

ConvexQuadrangleABC – The latest coordinates of the moving convex quadrangle.

current_quadrangle
add(self, quadrangle)

Adds the movement of the convex quadrangle at the following time frame.

Parameters:quadrangle (ConvexQuadrangleABC) – The coordinates of the moving convex quadrangle at the following time frame.
__iter__(self)

Produces an iterator of the convex quadrangle movements from the past to the present.

Returns:quadrangles – The coordinates of the moving convex quadrangle from the earliest time frame to the current time frame.
Return type:iterator of ConvexQuadrangleABC
__reversed__(self)

Produces an iterator of the convex quadrangle movements from the present to the past.

Returns:quadrangles – The coordinates of the moving convex quadrangle from the current time frame to the earliest time frame.
Return type:iterator of ConvexQuadrangleABC
__repr__(self)
class video699.interface.ConvexQuadrangleTrackerABC

Bases: abc.ABC, collections.abc.Iterable, collections.abc.Sized

An abstract tracker of the movement of convex quadrangles over time.

Notes

It MUST be possible to repeatedly iterate over all tracked convex quadrangles.

clear(self)

Removes all tracked convex quadrangles.

update(self, quadrangles)

Records convex quadrangles that exist in the current time frame.

Notes

The moving convex quadrangles that existed in the previous time frame MUST record the coordinates of the moving convex quadrangle at the previous time frame.

Parameters:current_quadrangles (iterable of ConvexQuadrangleABC) – The convex quadrangles in the current time frame.
Returns:
  • appeared_quadrangles (set of MovingConvexQuadrangleABC) – The moving convex quadrangles that did not exist in the previous time frame and exist in the current time frame.
  • existing_quadrangles (set of MovingConvexQuadrangleABC) – The moving convex quadrangles that existed in the previous time frame and exist in the current time frame.
  • disappeared_quadrangles (set of MovingConvexQuadrangleABC) – The moving convex quadrangles that existed in the previous time frame and do not exist in the current time frame.
__iter__(self)

Produces an iterator of the tracked convex quadrangles.

Returns:tracked_quadrangles – An iterable of the tracked convex quadrangles.
Return type:iterator of TrackedConvexQuadrangleABC
__len__(self)

Produces the number of the tracked convex quadrangles.

Returns:length – The number of the tracked convex quadrangles.
Return type:int
__repr__(self)
class video699.interface.ScreenABC

Bases: video699.interface.ImageABC

An abstract projection screen shown in a video frame.

frame

FrameABC – A video frame containing the projection screen.

coordinates

ConvexQuadrangleABC – A map between frame and screen coordinates.

image

array_like – The image data of the projection screen as an OpenCV CV_8UC3 RGBA matrix, where the alpha channel (A) denotes the weight of a pixel. Fully transparent pixels, i.e. pixels with zero alpha, SHOULD be completely disregarded in subsequent computation.

width

int – The width of the image data.

height

int – The height of the image data.

is_beyond_bounds

bool – Whether the projection screen extends beyond the bounds of the video frame.

frame
coordinates
image
width
height
is_beyond_bounds
__hash__(self)
__eq__(self, other)
__repr__(self)
class video699.interface.ScreenDetectorABC

Bases: abc.ABC

An abstract screen detector that maps video frames to lists of screens.

detect(self, frame)

Converts a frame to an iterable of detected lit projection screens.

Parameters:frame (FrameABC) – A frame of a video.
Returns:screens – An iterable of detected lit projection screens.
Return type:iterable of ScreenABC
__repr__(self)
class video699.interface.DocumentABC

Bases: abc.ABC, collections.abc.Iterable

An abstract text document.

Notes

It MUST be possible to repeatedly iterate over all document pages. A document MUST contain a page.

title

str or None – The title of a document.

author

str or None – The author of a document.

uri

string – An IRI, as defined in RFC3987, that uniquely indentifies the document over the entire lifetime of a program.

title
author
uri
__iter__(self)

Produces an iterator of document pages.

Returns:pages – An iterable of the pages of the document.
Return type:iterator of PageABC
__hash__(self)
__eq__(self, other)
__lt__(self, other)
__repr__(self)
class video699.interface.PageABC

Bases: video699.interface.ImageABC

An abstract page of a document.

document

DocumentABC – The document containing the page.

image

array_like – The image data of the page as an OpenCV CV_8UC3 RGBA matrix, where the alpha channel (A) denotes the weight of a pixel. Fully transparent pixels, i.e. pixels with zero alpha, SHOULD be completely disregarded in subsequent computation. Any margins added to the image data, e.g. by keeping the aspect ratio of the page, MUST be fully transparent.

number

int – The page number, i.e. the position of the page in the document. Page indexing is one-based, i.e. the first page has number 1.

document
number
__hash__(self)
__eq__(self, other)
__lt__(self, other)
__repr__(self)
class video699.interface.PageDetectorABC

Bases: abc.ABC

An abstract detector of document pages in projection screens.

detect(self, frame, appeared_screens, existing_screens, disappeared_screens)

Detects document pages in projection screens from a current video frame.

Parameters:
  • frame (FrameABC) – A current video frame.
  • appeared_screens (iterator of (ScreenABC, MovingConvexQuadrangleABC)) – Projection screens that did not exist in the previous video frame and exist in the current video frame, and their movements.
  • existing_screens (iterator of (ScreenABC, MovingConvexQuadrangleABC)) – Projection screens that existed in the previous video frame and exist in the current video frame, and their movements.
  • disappeared_screens (iterator of (ScreenABC, MovingConvexQuadrangleABC)) – Projection screens that existed in the previous video frame and do not exist in the current video frame, and their movements.
Returns:

detected_pages – A map between projections screens that exist in the current video frame and the document page detected in a projection screen. If no page was detected in a screen, then the screen maps to None.
Return type:

dict of (ScreenABC, PageABC or None)
__repr__(self)