Add iterator interface to VideoReader objects (#261)

* Add iterator interface to VideoReader objects

I have added an iterator interface to the `VideoReader` type, making collecting
all frames of a video as simple as `f = openvideo(fname); imgs = collect(f)`.
The iterator returns a new array for each frame, as I think mutating the same
array on subsequent calls to `iterate` would be surprising and lead to strange
behavior when calling functions such as `collect`. Note that the VideoReader
iterator is mutable, like Channel or Stateful iterators in Julia, and will
resume iteration where it was last stopped, instead of at the beginning. I have
added some text in the documentation explaining this behavior, and also added
some tests.

* Do not collect all frames into memory to test iterator interface

Instead of collecting all frames into memory with `collect` to test the
`VideoReader` interface, I am instead testing the iterator interface with a
simple for loop. This should reduce the memory requirement for CI, and avoid
memory-related test errors on low memory CI VMs.

* Simplify test of mutability of `VideoReader` iterator

Instead of looping over the iterator to test that there are zero elements
remaining, it is simpler to just see if `iterate` returns `nothing`.

* Test that iterator interface for `VideoReader` does not mutate frames

I have added a test to verify that frames returned by the `VideoReader`
iterator interface have distinct storage.

docs/src/reading.md

@@ -9,10 +9,12 @@ video frames from a supported video file (or from a camera device, shown later).
 ```julia
 using VideoIO
 
-#io = VideoIO.open(video_file)
+# Construct a AVInput object to access the video and audio streams in a video container
+# io = VideoIO.open(video_file)
 io = VideoIO.testvideo("annie_oakley") # for testing purposes
 
-f = VideoIO.openvideo(io)
+# Access the video stream in an AVInput, and return a VideoReader object:
+f = VideoIO.openvideo(io) # you can also use a file name, instead of a AVInput
 
 img = read(f)
 
@@ -23,6 +25,37 @@ end
 close(f)
 ```
 
+Alternatively, you can open the video stream in a file directly with
+`VideoIO.openvideo(filename)`, without making an intermediate `AVInput`
+object, if you only need the video.
+
+VideoIO also provides an iterator interface for [`VideoReader`](@ref), which
+behaves like other mutable iterators in Julia (e.g. Channels). If iteration is
+stopped early, for example with a `break` statement, then it can be resumed in
+the same spot by iterating on the same `VideoReader` object. Consequently, if
+you have already iterated over all the frames of a `VideoReader` object, then it
+will be empty for further iteration unless its position in the video is changed
+with `seek`.
+
+```julia
+using VideoIO
+
+
+io = VideoIO.testvideo("annie_oakley")
+f = VideoIO.openvideo(io)
+
+for img in f
+    # Do something with img
+end
+
+# You can also use collect(f) to get all of the frames
+
+# Further iteration will show that f is now empty!
+
+close(f)
+```
+
+
 Seeking through the video can be achieved via `seek(f, seconds::Float64)` and `seekstart(f)` to return to the start.
 ```@docs
 VideoIO.seek

src/VideoIO.jl

@@ -6,6 +6,8 @@ using ImageCore: permuteddimsview, channelview, rawview #0.723065 seconds
 using ColorTypes: RGB, Gray, N0f8, YCbCr                #0.529263 seconds
 using ImageTransformations: restrict                    #3.156594 seconds!!
 
+import Base: iterate, IteratorSize, IteratorEltype
+
 include("init.jl")
 include("util.jl")
 include(joinpath(av_load_path, "AVUtil", "src", "AVUtil.jl"))

src/avio.jl

@@ -93,6 +93,15 @@ end
 
 show(io::IO, vr::VideoReader) = print(io, "VideoReader(...)")
 
+function iterate(r::VideoReader, state = 0)
+    eof(r) && return
+    return read(r), state + 1
+end
+
+IteratorSize(::Type{<:VideoReader}) = Base.SizeUnknown()
+
+IteratorEltype(::Type{<:VideoReader}) = Base.EltypeUnknown()
+
 # Pump input for data
 function pump(c::AVInput)
     pFormatContext = c.apFormatContext[1]

test/avio.jl

@@ -128,7 +128,7 @@ end
             first_frame = load(first_frame_file)
 
             filename = joinpath(videodir, name)
-            v = VideoIO.openvideo(open(filename))
+            v = VideoIO.openvideo(VideoIO.open(filename))
 
             if size(first_frame, 1) > v.height
                 first_frame = first_frame[1+size(first_frame,1)-v.height:end,:]
@@ -147,13 +147,40 @@ end
             while !eof(v)
                 read!(v, img)
             end
+
+            # Iterator interface
+            VT = typeof(v)
+            @test Base.IteratorSize(VT) === Base.SizeUnknown()
+            @test Base.IteratorEltype(VT) === Base.EltypeUnknown()
+
+            VideoIO.seekstart(v)
+            i = 0
+            local first_frame
+            local last_frame
+            for frame in v
+                i += 1
+                if i == 1
+                    first_frame = frame
+                end
+                last_frame = frame
+            end
+            @test i == VideoIO.TestVideos.videofiles[name].numframes
+            # test that the frames returned by the iterator have distinct storage
+            if i > 1
+                @test first_frame !== last_frame
+            end
+
+            ## Test that iterator is mutable, and continues where iteration last
+            ## stopped.
+            @test iterate(v) === nothing
         end
     end
 
     VideoIO.testvideo("ladybird") # coverage testing
     @test_throws ErrorException VideoIO.testvideo("rickroll")
     @test_throws ErrorException VideoIO.testvideo("")
 end
+
 @testset "Reading video metadata" begin
     @testset "Reading Storage Aspect Ratio: SAR" begin
         # currently, the SAR of all the test videos is 1, we should get another video with a valid SAR that is not equal to 1