LabTalk Object Type:

External Object

The vr object reads a video file and imports frame (or frames) of video to matrix object/matrix book.


Method Description
vr.Open(fname) Open a video with the specified file name (include the complete file path)

Return value:

  • 0: successful.
  • Other values: failure and the value is the standard error code.
vr.SeekFrame(frameOffset, nOrigin) Move the pointer associated with the video to a new location that is framesOffset frames from nOrigin. nOrigin values:
  • -1: the first frame of the video
  • 0: default value. The current frame
  • 1: the last frame of the video
vr.SeekTime(msecOffset, nOrigin) Move the pointer associated with the video to a frame that locates msecOffset micro-seconds after nOrigin micro-seconds. nOrigin values
  • -1: the beginning of the video
  • 0: default value. The current time
  • 1: the end of the video
vr.ReadFrame([dataset]) Import a frame to the specified dataset. If the dataset is not given then the active one is used.
vr.ReadFrame(MBookName, layerIndex, objectIndex) Import a frame to the specified matrix object [MBookName]LayerIndex!"ojectIndex".
vr.ReadFrames(MBookName, frameCount, skipFrames) Import frameCount frames to the first matrix sheet of MBookName, skipping every skipFrames frames. Each frame is imported into a matrix object.
vr.Close( ) Close the video.

Return value:

  • 0: successful.
  • 1: failure.


All Vr properties are read-only.

Property Access Description
Vr.FourCC Read only


A number corresponding to the video's four character codec.
Vr.FourCC$ Read only


Four character code used to identify the video codec.
Vr.Format Read only


OpenCV format code. See below Channel properties for extracted info:

Channels: number of channels per frame

ChannelBits: bits per channel

ChannelInt: channel data integer values

ChannelSigned: channel data signed values

Note: the format and channel properties are based on the lastly read frame.

Vr.Channels Read only


Number of channels per frame
Vr.ChannelBits Read only


Bits per channel
Vr.ChannelInt Read only


Channel data integer values
Vr.ChannelSigned Read only


Channel data signed values
Vr.FPS Read only


Frames per second
Vr.FrameCount Read only


Number of frames in the video file
Vr.Width Read only


Video width in pixels
Vr.Height Read only


Video height in pixels
Vr.PosFrames Read only


Current position in frame.
Vr.PosMSec Read only


Current position in micro-seconds.


This script shows how to import 1 out of every 15 frames into the active matrix book, each frame to a matrix object.

string vfilename$ = "C:\test.mp4";
int StepSize = 15; // skip every 15 frames

int err = vr.Open(%(vfilename$));// Open the video file.
if( 0 == err )
	int TotalFrames = vr.FrameCount/StepSize;
	// Read from beginning to the end of the file into matrix.
	vr.ReadFrames(%h, TotalFrames, StepSize);
	vr.Close();// Close the video file.

There is also a full example of how to import 100 frames from a video into a new matrix book.