Capturing Frames
****************

``EasyVision.vision`` submodule conttains various capturing adapters.

Frame structure
===============

Each capturing adapter captures an image from some external source and returns a Frame object.
Frame consists of a ``timestamp``, frame ``index``, ``images`` - collection of Image objects and a ``processing_mask``.
Frame is implemented as namedtuple object with several additional helper methods. Please refer to ``EasyVision.vision`` submodule documentation for more details.

Frame supports ``fromdict``, ``todict`` methods as well as ``tobytes``, ``frombytes`` and ``tobuffer``, ``frombuffer`` which are used for multiprocessing and PyroServer.


Image structure
===============

An Image consists of ``source``, ``image``, ``mask``, ``original``, ``features`` and ``feature_type`` fields and is implemented as namedtuple object.

    ``source`` is a reference to the capture/processor object, that generated this image.

    ``image`` is usually a numpy array containing the actual captured image.

    ``mask`` is a generated or captured mask, that should be applied to the image before e.g. feature extraction.

    ``original`` is an original image. Usually this one is not being used, so it is ``None``.

    ``features`` and ``feature_type`` is generated by ``FeatureExtraction``/``BlobExtraction`` processing object.


Image supports ``fromdict``, ``todict`` methods as well as ``tobytes``, ``frombytes`` and ``tobuffer``, ``frombuffer`` which are used for multiprocessing and PyroServer.


Capturing from a list of images
===============================

It is useful to be able to process a list of images in offline processing scenarious. That is possible with ``ImagesReader`` class:

.. code-block:: python

    images = [...]
    with ImagesReader(images) as vision:
        for frame in vision:
            # do something with the frame

It is also possible to provide a list of masks:

.. code-block:: python

    images = [...]
    masks = [...]
    with ImagesReader(images, mask_paths=masks) as vision:
        for frame in vision:
            # do something with the frame


Capturing from video file or camera
===================================

Alternatively one can read frames from a video file like so:

.. code-block:: python

    with VideoCapture('path/to/video/file.mp4') as vision:
        for frame in vision:
            # do something with the frame

Or perform online capturing from e.g. a webcam:

.. code-block:: python

    with VideoCapture(0) as vision:
        for frame in vision:
            # do something with the frame


Capturing from capturing server
===============================

For some really computationally heavy processing it is useful to split the processing stack into several parts, that run on separate machines.
For that purpose there is a Pyro4 ``Server`` and ``PyroCapture``. The capturing protocol is already familiar:

.. code-block:: python

    with PyroCapture('RemoteProcessingStack') as vision:
        for frame in vision:
            # do something with the frame

However in order to use PyroCapture class, a Pyro4 NameServer should already be running and RemoteProcessingStack should be registered.
You can start Pyro4 Name Server like this::

    # pyro4-ns

Then you should start EasyVision server on the remote machine like this::

    # python -m EasyVision.bin.server RemoteProcessingStack remote_processing_stack.json

For more information on how to configure Pyro4 you can refer to Pyro4 documentation.
The format of ``remote_processing_stack.json`` file is described on ``ProcessorStackBuilder`` documentation page.

Writing your own adaptors
=========================

Just subclass from ``EasyVision.vision.base.VisionBase`` and implement all abstract methods.