Home > chronux > fly_track > videoIO > videoIO_2006a > @videoReader > videoReader.m

videoReader

PURPOSE ^

videoReader class constructor

SYNOPSIS ^

function vr = videoReader(url, varargin)

DESCRIPTION ^

 videoReader class constructor
   Creates a object that reads video streams.  We use a plugin 
   architecture in the backend to do the actual reading.  For example, 
   on Windows, DirectShow will typically be used and on Linux, the 
   ffmpeg library is often used.

   vr = videoReader(url)
     Opens the given video file for reading using the default plugin.
     On Windows, 'DirectShow' is used by default and on Linux,
     'ffmpegPopen2' is used by default.  For most plugins, the url will 
     really be a filename.

   vr = videoReader(url, ..., 'plugin',pluginName, ...)
   vr = videoReader(url,pluginName, ...)
     Opens the file using the manually specified plugin implementation.  
     Available plugins include:

     'DirectShow': preferred method on Windows
       - Only available on Windows
       - See INSTALL.dshow.txt for installation instructions
       - Can load virtually any video file that can be played in
         Microsoft's Windows Media Player.  Note that the correct codec
         must be installed to read a file.  For example, to read 
         tests/numbers.3ivx.avi, the user must have installed an MPEG4
         codec such as 3ivx (www.3ivx.com), DivX (www.divx.com), or XviD 
         (www.xvid.org).
       - The URL parameter should be a filename.
         - As a convenience, all forward slashes ('/') are automatically  
           converted to backslashes ('\')

     'ffmpegPopen2': safe method on Linux
       - Only supported on GNU/Linux (might work on BSD systems too like Mac 
         OS X, but this is untested)
       - See INSTALL.ffmpeg.txt for installation instructions
       - Creates a separate server process to communicate with the
         ffmpeg libraries.  
         - Works when the system's version of GCC is very different from
           the one that MathWorks used to compile Matlab.
         - Isolates ffmpeg errors so they typically cannot crash
           Matlab.  
         - May allow for more flexible distribution terms for your code 
           when it uses videoIO (ffmpeg may be compiled with either 
           the LGPL or GPL license).

     'ffmpegDirect': low-overhead method on Linux
       - same as ffmpegPopen2, but the ffmpeg libraries are loaded
         directly by the MEX file.
         - May not work if MathWorks' and your version of GCC are
           incompatible. 
         - Slightly faster than ffmpegPopen2 since there is no
           interprocess communication overhead.

   vr = videoReader(url, ..., param,arg,...)
     Allows the user to pass extra configuration arguments to plugin.
     Currently no plugin arguments are supported right now.  In the 
     future, we may allow the user to do things like have DirectShow
     automatically convert to grayscale, or give options to trade off 
     speed with seeking precision.
 
 Once you have created a videoReader object, you must next call NEXT,
 SEEK, or STEP at least once so that it will read some frame from disk.  
 *After* calling one of these methods, you may call GETFRAME as many 
 times as you would like and it will decode and return the current frame 
 (without advancing to a different frame).  GETINFO may be called at any 
 time (even before NEXT, SEEK, or STEP).  It returns basic information 
 about the video stream.  Once you are done using the videoReader, make 
 sure you call CLOSE so that any system resources allocated by the plugin 
 may be released.  Here's a simple example of how you might use
 videoReader: 

   % take us to the videoReader directory since we know there's a video
   % file there.  
   chdir(fileparts(which('videoReaderWrapper.cpp')));

   % Construct a videoReader object
   vr = videoReader('tests/numbers.uncompressed.avi');

   % Do some processing on the video and display the results
   avgIntensity = [];
   i = 1;
   figure;
   while (next(vr))
     img = getframe(vr);  
     avgIntensity(i) = mean(img(:));
     subplot(121); imshow(img);        title('current frame');
     subplot(122); plot(avgIntensity); title('avg. intensity vs. frame');
     drawnow;      pause(0.1);         i = i+1;
   end
   vr = close(vr);

 SEE ALSO:
   buildVideoMex
   videoReader/close
   videoReader/getframe
   videoReader/getinfo
   videoReader/getnext
   videoReader/next
   videoReader/seek
   videoReader/step
   videoWriter

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: This function is called by:

SUBFUNCTIONS ^

SOURCE CODE ^

0001 function vr = videoReader(url, varargin)
0002 % videoReader class constructor
0003 %   Creates a object that reads video streams.  We use a plugin
0004 %   architecture in the backend to do the actual reading.  For example,
0005 %   on Windows, DirectShow will typically be used and on Linux, the
0006 %   ffmpeg library is often used.
0007 %
0008 %   vr = videoReader(url)
0009 %     Opens the given video file for reading using the default plugin.
0010 %     On Windows, 'DirectShow' is used by default and on Linux,
0011 %     'ffmpegPopen2' is used by default.  For most plugins, the url will
0012 %     really be a filename.
0013 %
0014 %   vr = videoReader(url, ..., 'plugin',pluginName, ...)
0015 %   vr = videoReader(url,pluginName, ...)
0016 %     Opens the file using the manually specified plugin implementation.
0017 %     Available plugins include:
0018 %
0019 %     'DirectShow': preferred method on Windows
0020 %       - Only available on Windows
0021 %       - See INSTALL.dshow.txt for installation instructions
0022 %       - Can load virtually any video file that can be played in
0023 %         Microsoft's Windows Media Player.  Note that the correct codec
0024 %         must be installed to read a file.  For example, to read
0025 %         tests/numbers.3ivx.avi, the user must have installed an MPEG4
0026 %         codec such as 3ivx (www.3ivx.com), DivX (www.divx.com), or XviD
0027 %         (www.xvid.org).
0028 %       - The URL parameter should be a filename.
0029 %         - As a convenience, all forward slashes ('/') are automatically
0030 %           converted to backslashes ('\')
0031 %
0032 %     'ffmpegPopen2': safe method on Linux
0033 %       - Only supported on GNU/Linux (might work on BSD systems too like Mac
0034 %         OS X, but this is untested)
0035 %       - See INSTALL.ffmpeg.txt for installation instructions
0036 %       - Creates a separate server process to communicate with the
0037 %         ffmpeg libraries.
0038 %         - Works when the system's version of GCC is very different from
0039 %           the one that MathWorks used to compile Matlab.
0040 %         - Isolates ffmpeg errors so they typically cannot crash
0041 %           Matlab.
0042 %         - May allow for more flexible distribution terms for your code
0043 %           when it uses videoIO (ffmpeg may be compiled with either
0044 %           the LGPL or GPL license).
0045 %
0046 %     'ffmpegDirect': low-overhead method on Linux
0047 %       - same as ffmpegPopen2, but the ffmpeg libraries are loaded
0048 %         directly by the MEX file.
0049 %         - May not work if MathWorks' and your version of GCC are
0050 %           incompatible.
0051 %         - Slightly faster than ffmpegPopen2 since there is no
0052 %           interprocess communication overhead.
0053 %
0054 %   vr = videoReader(url, ..., param,arg,...)
0055 %     Allows the user to pass extra configuration arguments to plugin.
0056 %     Currently no plugin arguments are supported right now.  In the
0057 %     future, we may allow the user to do things like have DirectShow
0058 %     automatically convert to grayscale, or give options to trade off
0059 %     speed with seeking precision.
0060 %
0061 % Once you have created a videoReader object, you must next call NEXT,
0062 % SEEK, or STEP at least once so that it will read some frame from disk.
0063 % *After* calling one of these methods, you may call GETFRAME as many
0064 % times as you would like and it will decode and return the current frame
0065 % (without advancing to a different frame).  GETINFO may be called at any
0066 % time (even before NEXT, SEEK, or STEP).  It returns basic information
0067 % about the video stream.  Once you are done using the videoReader, make
0068 % sure you call CLOSE so that any system resources allocated by the plugin
0069 % may be released.  Here's a simple example of how you might use
0070 % videoReader:
0071 %
0072 %   % take us to the videoReader directory since we know there's a video
0073 %   % file there.
0074 %   chdir(fileparts(which('videoReaderWrapper.cpp')));
0075 %
0076 %   % Construct a videoReader object
0077 %   vr = videoReader('tests/numbers.uncompressed.avi');
0078 %
0079 %   % Do some processing on the video and display the results
0080 %   avgIntensity = [];
0081 %   i = 1;
0082 %   figure;
0083 %   while (next(vr))
0084 %     img = getframe(vr);
0085 %     avgIntensity(i) = mean(img(:));
0086 %     subplot(121); imshow(img);        title('current frame');
0087 %     subplot(122); plot(avgIntensity); title('avg. intensity vs. frame');
0088 %     drawnow;      pause(0.1);         i = i+1;
0089 %   end
0090 %   vr = close(vr);
0091 %
0092 % SEE ALSO:
0093 %   buildVideoMex
0094 %   videoReader/close
0095 %   videoReader/getframe
0096 %   videoReader/getinfo
0097 %   videoReader/getnext
0098 %   videoReader/next
0099 %   videoReader/seek
0100 %   videoReader/step
0101 %   videoWriter
0102 %
0103 %Copyright (c) 2006 Gerald Dalley
0104 %See "MIT.txt" in the installation directory for licensing details (especially
0105 %when using this library on GNU/Linux).
0106 
0107 if (mod(length(varargin),2) == 0)
0108   plugin     = defaultVideoIOPlugin;
0109   pluginArgs = varargin;
0110 else
0111   plugin     = varargin{1};
0112   pluginArgs = {varargin{2:end}};
0113 end
0114 [plugin,pluginArgs] = parsePlugin(plugin, pluginArgs);
0115 
0116 vr = struct('plugin',mexName(plugin), 'handle',int32(-1));
0117 vr = class(vr, 'videoReader');
0118 [pathstr, name, ext, versn] = fileparts(url);
0119 strArgs = cell(size(pluginArgs));
0120 for i=1:numel(pluginArgs), strArgs{i} = num2str(pluginArgs{i}); end
0121 vr.handle = feval(vr.plugin, 'open', vr.handle, ...
0122   fullfile(pathstr,[name ext versn]), strArgs{:});
0123 
0124 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0125 function n = mexName(plugin)
0126 n = ['videoReader_' plugin];
0127 
0128 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0129 function [plugin,pluginArgs] = parsePlugin(plugin, pluginArgs)
0130 if (length(pluginArgs) > 0)
0131   [pluginSpecified,idx] = ismember('plugin', {pluginArgs{1:2:end}});
0132   if pluginSpecified
0133     plugin = pluginArgs{idx*2};
0134     pluginArgs = { pluginArgs{1:idx*2-2}, pluginArgs{idx*2+1:end} };
0135   end
0136 end

Generated on Fri 28-Sep-2012 12:34:30 by m2html © 2005