# videoread

## PURPOSE

VIDEOREAD Read an video file in a mannter compatible with Matlab's

## SYNOPSIS

function mov=videoread(fname,varargin)

## DESCRIPTION

    VIDEOREAD Read an video file in a mannter compatible with Matlab's
              built-in AVIREAD function, but using a videoReader object to do
              the work instead.

       MOV=VIDEOREAD(FNAME)
         Read the video file FNAME into the Matlab movie structure MOV.  MOV
         has two fields, "cdata" and "colormap".  Since all videoReader
         plugins currently output 24-bit images in all cases, colormap will
         always be blank.

       MOV=VIDEOREAD(FNAME,VRARGS)
         The same as MOV=VIDEOREAD(FNAME), but VRARGS are passed to the
         videoReader constructor.  VRARGS should be a cell array of arguments.
         E.g.
             mov = videoread('tests/numbers.wmv3.avi', {'DirectShow'});

       MOV=VIDEOREAD(FNAME,INDEX)
         Reads only the frame(s) specified by INDEX.  INDEX can be a single
         index or an array of indices into the video stream, where the first
         frame is  number one.  IMPORTANT NOTES: If you use videoReader
         directly, it assumes  frames start at 0, not 1.  We use 1-indexing
         here in VIDEOREAD to maximize  compatibility with MathWork's AVIREAD.
         Also, if you find yourself making several calls to VIDEOREAD to
         extract different portions of the file and/or if the number of
         frames is large, consider using videoReader directly instead of this
         wrapper function.

       MOV=VIDEOREAD(FNAME,VRARGS,INDEX)
         The same as MOV=VIDEOREAD(FNAME,INDEX), but VRARGS are passed to the
         videoReader constructor.  VRARGS should be a cell array of arguments.

    Copyright (c) 2006 Gerald Dalley
    See "MIT.txt" in the installation directory for licensing details (especially
    when using this library on GNU/Linux).

## CROSS-REFERENCE INFORMATION

This function calls:

- close VR=CLOSE(VR)
- getframe FRAME=GETFRAME(VR)
- getinfo INFO=GETINFO(VR)
- next WORKED=NEXT(VR)
- seek WORKED=SEEK(VR,FNUM)
- videoReader videoReader class constructor
- close VW=CLOSE(VW)
- getinfo INFO=GETINFO(VW)
- close VR=CLOSE(VR)
- getframe FRAME=GETFRAME(VR)
- getinfo INFO=GETINFO(VR)
- next WORKED=NEXT(VR)
- seek WORKED=SEEK(VR,FNUM)
- videoReader videoReader class constructor
- close VW=CLOSE(VW)
- getinfo INFO=GETINFO(VW)
- close VR=CLOSE(VR)
- getframe FRAME=GETFRAME(VR)
- getinfo INFO=GETINFO(VR)
- next WORKED=NEXT(VR)
- seek WORKED=SEEK(VR,FNUM)
- videoReader videoReader class constructor
- close VW=CLOSE(VW)
- getinfo INFO=GETINFO(VW)

This function is called by:

## SOURCE CODE

    0001 function mov=videoread(fname,varargin)
    0002 %VIDEOREAD Read an video file in a mannter compatible with Matlab's
    0003 %          built-in AVIREAD function, but using a videoReader object to do
    0004 %          the work instead.
    0005 %
    0006 %   MOV=VIDEOREAD(FNAME)
    0007 %     Read the video file FNAME into the Matlab movie structure MOV.  MOV
    0008 %     has two fields, "cdata" and "colormap".  Since all videoReader
    0009 %     plugins currently output 24-bit images in all cases, colormap will
    0010 %     always be blank.
    0011 %
    0012 %   MOV=VIDEOREAD(FNAME,VRARGS)
    0013 %     The same as MOV=VIDEOREAD(FNAME), but VRARGS are passed to the
    0014 %     videoReader constructor.  VRARGS should be a cell array of arguments.
    0015 %     E.g.
    0016 %         mov = videoread('tests/numbers.wmv3.avi', {'DirectShow'});
    0017 %
    0018 %   MOV=VIDEOREAD(FNAME,INDEX)
    0019 %     Reads only the frame(s) specified by INDEX.  INDEX can be a single
    0020 %     index or an array of indices into the video stream, where the first
    0021 %     frame is  number one.  IMPORTANT NOTES: If you use videoReader
    0022 %     directly, it assumes  frames start at 0, not 1.  We use 1-indexing
    0023 %     here in VIDEOREAD to maximize  compatibility with MathWork's AVIREAD.
    0024 %     Also, if you find yourself making several calls to VIDEOREAD to
    0025 %     extract different portions of the file and/or if the number of
    0026 %     frames is large, consider using videoReader directly instead of this
    0027 %     wrapper function.
    0028 %
    0029 %   MOV=VIDEOREAD(FNAME,VRARGS,INDEX)
    0030 %     The same as MOV=VIDEOREAD(FNAME,INDEX), but VRARGS are passed to the
    0031 %     videoReader constructor.  VRARGS should be a cell array of arguments.
    0032 %
    0033 %Copyright (c) 2006 Gerald Dalley
    0034 %See "MIT.txt" in the installation directory for licensing details (especially
    0035 %when using this library on GNU/Linux).
    0036
    0037 if nargin==1,
    0038   vrargs = {};
    0039 elseif nargin==2,
    0040   if (iscell(varargin{1})),
    0041     vrargs = varargin{1};
    0042   else
    0043     vrargs = {};
    0044     index  = varargin{1};
    0045   end
    0046 elseif nargin==3,
    0047   vrargs = varargin{1};
    0048   index  = varargin{2};
    0049 end
    0050
    0051 vr = videoReader(fname, vrargs{:});
    0052 if ~(exist('index','var')),
    0053   info = getinfo(vr);
    0054   index = (0:info.numFrames-1); % 0-indexed
    0055 else
    0056   index = index - 1; % 0-indexed
    0057 end
    0058
    0059 mov = struct;
    0060 currFrame = -1;
    0061 if (size(index)>0)
    0062   % index supplied or deduced from file
    0063   for i=1:length(index)
    0064     f = index(i);
    0065     if (f == currFrame+1)
    0066       if ~next(vr), error('Could not advance to frame %d\n', f+1); end
    0067     else
    0068       if ~seek(vr, f), error('Could not seek to frame %d\n', f+1); end
    0069     end
    0070     currFrame = f;
    0071     mov(i).cdata = getframe(vr);
    0072     mov(i).colormap = [];
    0073   end
    0074 else
    0075   % no index was supplied and we could not deduce the number of frames
    0076   % in the video.
    0077   i=1;
    0078   while next(vr)
    0079     mov(i).cdata = getframe(vr);
    0080     mov(i).colormap = [];
    0081     i = i+1;
    0082   end
    0083 end
    0084
    0085 vr = close(vr);
    0086