org.openimaj.video.capture

Class VideoCapture

java.lang.Object

org.openimaj.video.Video<MBFImage>

org.openimaj.video.capture.VideoCapture

All Implemented Interfaces:

Closeable, AutoCloseable, Iterable<MBFImage>

public class VideoCapture
extends Video<MBFImage>

VideoCapture is a type of Video that can capture live video streams from a webcam or other video device. On OSX and Windows, this is completely dependency-free and no extra software needs to be installed. On linux you need to have video4linux installed.

Environment variables

• The environment variable OPENIMAJ_GRABBER_VERBOSE can be set (to any non-zero length value) on windows to make the native library print lots of debugging information
• The environment variable OPENIMAJ_GRABBER_READ can be set on linux to force the native library use v4l in read-mode rather than through memory mapping the device. This can be useful if you have lots of cameras attached as it reduces the bandwidth required.

System properties

• The system property with the name given by DEFAULT_DEVICE_NUMBER_PROPERTY can be used to set the default capture device and can either be a device number, or device identifer string. See VideoCapture(int, int) for more details.

Author:

Jonathon Hare (jsh2@ecs.soton.ac.uk)

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_DEVICE_NUMBER_PROPERTY The property key for overriding the default device number.

Fields inherited from class org.openimaj.video.Video

currentFrame

Constructor Summary

Constructors

Constructor and Description
VideoCapture(int width, int height) Construct a VideoCapture instance with the requested width and height.
VideoCapture(int width, int height, Device device) Construct a VideoCapture instance with the requested width and height using the specified video device.
VideoCapture(int width, int height, double fps, Device device) Construct a VideoCapture instance with the requested width and height using the specified video device.

Method Summary

Modifier and Type	Method and Description
void	close() Close the video object
long	countFrames() Return the number of frames in the whole video.
protected void	finalize()
MBFImage	getCurrentFrame() Get the current frame
double	getFPS() Get the frame rate
int	getHeight() Get the height of the video frame.
MBFImage	getNextFrame() Get the next frame.
long	getTimeStamp() Get the timestamp of the current frame in milliseconds
static List<Device>	getVideoDevices() Get a list of all compatible video devices attached to the machine.
int	getWidth() Get the width of the video frame
boolean	hasNextFrame() Returns whether this video has another frame to provide.
static void	main(String[] args) Test main method.
void	reset() Reset the video - putting the frame counter back to the start.
void	setCurrentFrameIndex(long newFrame) Set the current frame index (i.e.
void	setFPS(double fps) Set the number of frames per second.
protected boolean	startSession(int requestedWidth, int requestedHeight, double requestedFPS)
protected boolean	startSession(int requestedWidth, int requestedHeight, double requestedFPS, Device device)
void	stopCapture() Stop the video capture system.

Methods inherited from class org.openimaj.video.Video

getCurrentFrameIndex, iterator, seek

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

DEFAULT_DEVICE_NUMBER_PROPERTY

public static final String DEFAULT_DEVICE_NUMBER_PROPERTY

The property key for overriding the default device number.

See Also:

Constant Field Values

Constructor Detail

VideoCapture

public VideoCapture(int width,
                    int height)
             throws VideoCaptureException

Construct a VideoCapture instance with the requested width and height. The default video device will be used. The actual height and width of the captured frames may not equal the requested size if the underlying platform-specific grabber is not able to honor the request. The actual size can be inspected through the getWidth() and getHeight() methods.

The default device is usually the first device listed by getVideoDevices(), however this is down to the underlying native libraries and operating system. The DEFAULT_DEVICE_NUMBER_PROPERTY system property allows the selection of the default device to be overridden. The property value can be an integer representing the index of the default device in the list produced by DEFAULT_DEVICE_NUMBER_PROPERTY or a String that includes part of the device identifier. In the case of a String value, the device with the identifier that first contains the value is selected.

Parameters:

width - the requested video width

height - the requested video height

Throws:

VideoCaptureException - if no webcam is found, or there is a problem opening it

VideoCapture

public VideoCapture(int width,
                    int height,
                    Device device)
             throws VideoCaptureException

Construct a VideoCapture instance with the requested width and height using the specified video device. The actual height and width of the captured frames may not equal the requested size if the underlying platform-specific grabber is not able to honor the request. The actual size can be inspected through the getWidth() and getHeight() methods.

Parameters:

width - the requested video width.

height - the requested video height.

device - the requested video device.

Throws:

VideoCaptureException - if there is a problem opening the webcam

VideoCapture

public VideoCapture(int width,
                    int height,
                    double fps,
                    Device device)
             throws VideoCaptureException

Construct a VideoCapture instance with the requested width and height using the specified video device. The actual height and width of the captured frames may not equal the requested size if the underlying platform-specific grabber is not able to honor the request. The actual size can be inspected through the getWidth() and getHeight() methods.

Parameters:

width - the requested video width.

height - the requested video height.

fps - the requested frame rate

device - the requested video device.

Throws:

VideoCaptureException - if there is a problem opening the webcam

Method Detail

getVideoDevices

public static List<Device> getVideoDevices()

Get a list of all compatible video devices attached to the machine.

Returns:

a list of devices.

startSession

protected boolean startSession(int requestedWidth,
                               int requestedHeight,
                               double requestedFPS,
                               Device device)

startSession

protected boolean startSession(int requestedWidth,
                               int requestedHeight,
                               double requestedFPS)

stopCapture

public void stopCapture()

Stop the video capture system. Once stopped, it can only be started again by constructing a new instance of VideoCapture.

getCurrentFrame

public MBFImage getCurrentFrame()

Description copied from class: Video

Get the current frame

Specified by:

getCurrentFrame in class Video<MBFImage>

Returns:

the current frame

getNextFrame

public MBFImage getNextFrame()

Get the next frame. Increments the frame counter by 1.

Specified by:

getNextFrame in class Video<MBFImage>

Returns:

the next frame

Throws:

RuntimeException - wrapping a VideoCaptureException with the message "Timed out waiting for next frame" if there is a timeout waiting for the next frame. This could potentially be caught and ignored (i.e. the frame is dropped).

RuntimeException - wrapping a VideoCaptureException with the message "Error occurred getting next frame" if there is an error the next frame. Currently this can only occur on linux.

hasNextFrame

public boolean hasNextFrame()

Description copied from class: Video

Returns whether this video has another frame to provide.

Specified by:

hasNextFrame in class Video<MBFImage>

Returns:

Whether the video has another frame available

countFrames

public long countFrames()

Description copied from class: Video

Return the number of frames in the whole video. If the video is a live stream, then this method should return -1.

Specified by:

countFrames in class Video<MBFImage>

Returns:

the number of frames in the whole video or -1 if unknown

main

public static void main(String[] args)
                 throws VideoCaptureException

Test main method. Lists the available devices, and then opens the first and second capture devices if they are available and displays their video.

Parameters:

args - ignored.

Throws:

VideoCaptureException

getWidth

public int getWidth()

Get the width of the video frame

Specified by:

getWidth in class Video<MBFImage>

Returns:

the width of the video frame.

See Also:

Video.getWidth()

getHeight

public int getHeight()

Get the height of the video frame.

Specified by:

getHeight in class Video<MBFImage>

Returns:

the height of the video frame.

See Also:

Video.getHeight()

reset

public void reset()

Description copied from class: Video

Reset the video - putting the frame counter back to the start.

Specified by:

reset in class Video<MBFImage>

getTimeStamp

public long getTimeStamp()

Get the timestamp of the current frame in milliseconds

Specified by:

getTimeStamp in class Video<MBFImage>

Returns:

the time stamp in milliseconds

See Also:

Video.getTimeStamp()

setCurrentFrameIndex

public void setCurrentFrameIndex(long newFrame)

Description copied from class: Video

Set the current frame index (i.e. skips to a certain frame). If your video subclass can implement this in a cleverer way, then override this method, otherwise this method will simply grab frames until it gets to the given frame index. This method is naive and may take some time as each frame will be decoded by the video decoder.

Overrides:

setCurrentFrameIndex in class Video<MBFImage>

Parameters:

newFrame - the new index

getFPS

public double getFPS()

Get the frame rate

Specified by:

getFPS in class Video<MBFImage>

Returns:

the frame rate

See Also:

Video.getFPS()

setFPS

public void setFPS(double fps)

Set the number of frames per second.

Parameters:

fps - The number of frames per second.

close

public void close()

Description copied from class: Video

Close the video object

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Overrides:

close in class Video<MBFImage>

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable