Readers
=======

In PyCVF, readers are kind of iterators that are : 
1. *seekable* ,
2. *copyable* ,
3. Measurable,
4. provide a built-in call back mechanism to set up observers related to them,
5. may provide *metadata*

Readers are used for audio, video and other spectral unidimensional
data that may not fit into memory, they provide a way to get reasonable
chunk fo data through a lazy mechanism.

Reader provide different methd for accessing the data.

The first method consist on seek and let it play paragigm.

Classical, usage will be ::

  reader.seek_to(targetpos)
  reader.set_observer(xxx)
  reader.run()
  
The other strategy is a seek base method::

  for frameno in range(len(reader)):
    reader[frameno]


Temporality
...........

A reader for sound will return buffers . The granularity will thus be at
the buffer level. To access the sample level, other objects must  be
used.

A reader for video will return images.
User must be able to seek with frameno, or to seek by timecode.



Subsequence Reader 
..................
* Slicing / restricting time range

Mapped Reader
.............
* Modifying each span of data

Incremental Reduce Reader
.........................
* Modifying each span of data


Methods
.......

* copy()

* seek_to
* getitem

* set_observer
* run

* get_current_frame()
* get_next_frame()


Audio metadata 
..............
1. get_channels()
2. get_samplerate()
3. get_datatype()

Video metadata
..............
1. get_size()
2. get_orig_size()
3. get_aspect_ratio()


When copied, each reader conserve its own position,
The copied iterator does not heritate from the observer.



Audio data
==========

Audio data are provided as numpy array with 2 dimensions. 
* First dimension is the time axis.
* Second dimension are the channels.


Image data
==========

The data itself
...............

An image is assumed to be a numpy array with 2 or 3 three dimensions,
whose value are assumed to be in-between in-between 0 and 255, if is
represented by an integer/ and in-between 0 and 1 if it is represented
by floats.

It is the responsabilabity of each node to check the representation of
the data.

The metadata  that are meant to be set..



Video data
==========

* Are readers returning image

Optical flow data
=================