1
1
% PsychVideoCapture -- Video capture support
3
% Psychtoolbox has built-in Screen-Subfunctions that allow you
4
% to control and use standard video capture equipment to capture
5
% live video from a camera or other supported video source in
6
% real-time with low latency.
8
% This is useful for studies on (manipulated) visual feedback,
9
% e.g., action-perception studies, as well as for future
10
% applications like vision based eye-trackers.
12
% The M-Files in this folder use the Screen - Low-level functions
13
% to provide more convenient high-level access to standard video
14
% capture tasks, e.g., setup of the camera or a video feedback
15
% loop with low and controlled latency.
17
% THIS IS EXPERIMENTAL CODE FOR NOW! It is well tested and known
18
% to work perfectly on Linux, but support on MacOS-X and Windows
19
% is not yet as feature rich, flexible and mature as on Linux.
20
% Especially, the OS-X and Windows versions are not as extensively
21
% tested. Some of the functions here are work in progress, useful,
24
% OS-X & Windows: We use the Sequence-Grabber API of Apples Quicktime
25
% for video capture on OS-X and Windows. On Windows, you'll need
26
% to install a Quicktime compatible video digitizer component, e.g.,
27
% WinVDIG, which can be freely downloaded from http://www.vdig.com/WinVDIG/
29
% On MacOS-X 10.4, video digitizers are already installed.
31
% Windows and MacOS-X support USB-Webcams, Firewire digital cameras
32
% conforming to the IIDC 1.0 machine vision camera specification,
33
% standard framegrabber cards and standard digital video cameras.
34
% -> Everything that is supported by the operating system.
36
% On Linux, currently only Firewire digital cameras are supported that
37
% conform to the IIDC 1.0 machine vision camera specification.
38
% Internally we use the excellent and free LibDC1394 library. See
39
% http://damien.douxchamps.net/ieee1394/libdc1394/index.php
40
% for information, forums and links to the IIDC-Spec.
42
% A list of supported cameras can be found here:
43
% http://damien.douxchamps.net/ieee1394/cameras/index.php
45
% The Linux version is the most mature and well-tested one. It allows
46
% very convenient and fine-grained control over many aspects and
47
% settings of the cameras, it reliably can drive multiple cameras
48
% in parallel (tested with two cameras) and it has excellent timing,
49
% very low capture latency and highly accurate built-in timestamping
50
% code. The reported timestamps are accurate to a few dozen microseconds.
52
% You will need Linux kernel 2.4.21 or later or Linux 2.6.16
53
% or later for best performance, but these are part of any recent
56
% Supported Cameras on Linux:
3
% Psychtoolbox has built-in Screen-Subfunctions that allow you to control
4
% and use standard and professional video capture equipment to capture live
5
% video from a camera or other supported video source in real-time with low
8
% This is useful for studies on (manipulated) visual feedback, e.g.,
9
% action-perception studies, as well as for future applications like vision
12
% The M-Files in this folder use the Screen - Low-level functions to
13
% provide more convenient high-level access to standard video capture
14
% tasks, e.g., setup of the camera or a video feedback loop with low and
17
% The functions are well tested and known to work perfectly on Linux.
18
% Support on MacOS-X and Windows is not always as feature rich, flexible
19
% and mature as on Linux. Especially, the OS-X and Windows versions are not
20
% as extensively tested. Some of the functions here are work in progress,
21
% useful, but not finished.
23
% Screen() supports three separate built-in videocapture engines for
26
% PROFESSIONAL CLASS ENGINE FOR DEMANDING APPLICATIONS:
28
% For demanding pro-applications that require precise low-level control
29
% over your camera's features and capture parameters, high capture
30
% framerates, image resolutions, color depths and processing efficiency,
31
% low-latency, high timing precision and high capture timestamp precision,
32
% Screen implements a firewire videocapture engine which is based on the
33
% free-software and open-source cross-platform library "libdc1394". This
34
% engine supports professional IEEE-1394 machine vision cameras conforming
35
% to the IIDC 1.0 machine vision camera specification. These can be
36
% connected via IEEE-1394 firewire bus, or for some special examplars also
37
% via high-performance USB bus via "Firewire-over-USB" protocol. This
38
% high-perf capture engine is selected by default via the following Screen
41
% Screen('Preference', 'DefaultVideocaptureEngine', 1);
43
% Alternatively you can select it on a case-by-case basis by passing the
44
% value 1 as optional 'engineID' parameter for the
45
% Screen('OpenVideocapture', ...); command.
47
% See <http://damien.douxchamps.net/ieee1394/libdc1394/>
48
% for information about the libdc1394 library, forums and links to the
51
% A list of supported firewire pro-cameras can be found here:
52
% <http://damien.douxchamps.net/ieee1394/cameras/>
54
% The firewire engine is currently supported on Linux, where it was
55
% originally developed, tested and used, and on MacOSX, where it received
56
% some testing and use. Therefore, the Linux version is the most mature and
57
% well-tested one. It allows very convenient and fine-grained control over
58
% many aspects and settings of the cameras, it reliably can drive multiple
59
% cameras in parallel (tested with two cameras) and it has excellent
60
% timing, very low capture latency and highly accurate built-in
61
% timestamping code. The reported timestamps are accurate to a few dozen
64
% You will need Linux kernel 2.4.21 or later or Linux 2.6.16 or later for
65
% best performance, but these are part of any recent distribution.
58
69
% All IIDC compliant cameras should work. For the Basler A602f greyscale
59
70
% high performance camera and the cheap and good Unibrain Fire-i camera,
60
% the PsychCamSettings - Tool provides especially convenient access to
61
% the camera settings.
63
% Supported cameras on OS-X/Windows:
65
% All cameras supported by the operating system are supported, but there
66
% is only very limited support for changing camera settings and accessing
67
% special features. Capture works reliably, but the capture latency is
68
% pretty much unknown and the timing mechanisms for retrieving capture
69
% timestamps are hidden in Apples Quicktime implementation and therefore
70
% their reliability and internal working is unknown.
74
% PsychCamSettings - Function for programmatically querying and setting
75
% camera parameters like exposure time, gain, brightness
76
% color saturation and such. Can also estimate the
77
% internal latency of the camera for known models,
78
% currently Basler A602f and Unibrain Fire.i
71
% the PsychCamSettings - Tool provides especially convenient access to the
74
% You can find additional setup instructions for the libdc1394 engine in
75
% 'help VideoCaptureDC1394'.
77
% CONSUMER LEVEL ENGINES FOR LESS STRINGENT REQUIREMENTS:
79
% These engines are targeted at standard consumer class video capture and
80
% video digitizer equipment, e.g., built-in cameras of Laptop computers,
81
% USB or Firewire connected "webcams", DV camcorders, standard video
82
% converters and receivers etc. Quality of feature control, efficiency,
83
% attainable framerates and resolutions, precision of timing or capture
84
% timestamps and other properties vary on a model-by-model,
85
% vendor-by-vendor, operating-system-by-operating-system basis. While some
86
% relatively cheap cameras work very well on some operating systems, e.g.,
87
% the "Sony PlayStation Eye" USB web-camera, no guarantess can be made
88
% about the performance or quality of any specific camera.
90
% Screen supports different engines on different operating systems for
91
% driving such consumer cameras.
93
% * Linux, Windows: We use GStreamer's built-in videocapture functionality
94
% by default (see "help GStreamer"). This is highly reliable and feature
95
% rich on Linux, somewhat less feature rich and reliable but still decent
96
% on Windows -- highly dependent on the version of Windows you are using.
97
% The engine should support most commercially available consumer level
98
% cameras for firewire, USB, PCI and other busses, basically any camera for
99
% which the operating system provides a device driver.
101
% This engine has id 3 and is selected by default on Linux and Windows.
103
% You can find additional setup instructions for GStreamer in
107
% * 32-Bit OS-X & 32-Bit Windows: We use the Sequence-Grabber API of Apples
108
% Quicktime-7 for video capture on 32-Bit OS-X and (optionally) on 32-Bit
109
% Windows. On MS-Windows, you'll need to install a Quicktime compatible
110
% video digitizer component, e.g., WinVDIG, which can be freely downloaded
111
% from http://www.vdig.com/WinVDIG/. However, use of this engine is only
112
% provided for backward compatibility and generally discouraged, as the
113
% default GStreamer engine is to our knowledge superior in any aspect.
115
% On MacOS-X 32-Bit, video digitizers are already installed.
117
% On 32-Bit OS/X this engine is the default, on Windows you could select it
120
% * 64-Bit OS/X: This is not yet supported. We use the GStreamer engine by
121
% default, just as on Linux and Windows. However, GStreamer doesn't yet
122
% support video capture on 64-Bit OS/X, at least as of May 2012.
126
% Contents of this folder:
128
% libdc1394.22.dylib - The runtime library for the libdc1394 firewire video
129
% capture engine for 64-Bit MacOS/X. For installation
130
% into the /usr/local/lib/ system folder of your
133
% PsychCamSettings - Function for programmatically querying and setting
134
% camera parameters like exposure time, gain, brightness
135
% color saturation and such. Can also estimate the
136
% internal latency of the camera for known models,
137
% currently Basler A602f and Unibrain Fire.i
79
139
% PsychGetCamIdForSpec - Return deviceIndex of a specified camera.
80
% PsychOpenEyes - Control interface for PTB's integrated vision based
81
% eyetracker, based on the OpenEyes toolkit.
83
% PsychSetupCamera - Interactive tool for setting up a camera and writing
84
% the final settings into a .mat file for later use
85
% by experiment scripts.
87
% PsychVideoDelayLoop - Full, feature rich implementation of a live
88
% video feedback loop with controllable latency.
89
% See its help for a list of features.
141
% PsychOpenEyes - Control interface for PTB's integrated vision based
142
% eyetracker, based on the OpenEyes toolkit.
144
% PsychSetupCamera - Interactive tool for setting up a camera and writing
145
% the final settings into a .mat file for later use
146
% by experiment scripts.
148
% PsychVideoDelayLoop - Full, feature rich implementation of a live
149
% video feedback loop with controllable latency.
150
% See its help for a list of features.
added
removed
Psychtoolbox/PsychVideoCapture/Contents.m
