videoinput
Create video input object
Description
A videoinput
object represents a connection between MATLAB® and an image acquisition device.
Creation
Syntax
Description
vid = videoinput(
creates a video
input object adaptor
)vid
. adaptor
is a character vector or
string scalar that specifies the name of the adaptor used to communicate with the device.
Use imaqhwinfo
to determine the adaptors available on your
system.
vid = videoinput(
creates a video input object adaptor
,deviceID
)vid
, where deviceID
is a numeric scalar value that identifies a particular device available through the
specified adaptor, adaptor
. Use
imaqhwinfo(adaptor)
to determine the devices available through the
specified adaptor. If deviceID
is not specified, the first available
device ID is used. You can also use a device's name in place of
deviceID
. If multiple devices have the same name, the first
available device is used.
vid = videoinput(
creates a video input object adaptor
,deviceID
,format
)vid
, where format
is
a character vector or string scalar that specifies a particular video format supported by
the device or the full path of a device configuration file (also known as a camera file).
To get a list of the formats supported by a particular device, view the
DeviceInfo
structure for the device that is returned by
imaqhwinfo
. Each DeviceInfo
structure contains a
SupportedFormats
field. If format
is not
specified, the device's default format is used. When the video input object is created,
its VideoFormat
property contains the format name or device
configuration file that you specify.
vid = videoinput(___,
creates a video input object and sets additional properties using one or more name-value
arguments in addition to the input arguments in previous syntaxes. If an invalid property
name or property value is specified, the object is not created. Use tab-completion to see
a full list of properties that you can set for your adaptor using name-value
arguments.Name,Value
)
To view a complete list of video input object functions and properties, use
imaqhelp
.
Note
The toolbox chooses the first available video source object as the selected source and
specifies this video source object's name in the object's
SelectedSourceName
property. Use
getselectedsource(obj)
to access the video source object that is used
for acquisition.
Properties
General Properties
BayerSensorAlignment
— Sensor alignment for Bayer demosaicing
"grbg"
(default) | "gbrg"
| "rggb"
| "bggr"
Sensor alignment for Bayer demosaicing, specified as "grbg"
,
"gbrg"
, "rggb"
, or "bggr"
. If
the ReturnedColorSpace
property is set to "bayer"
,
then the Image Acquisition Toolbox™ will demosaic Bayer patterns returned by the hardware. This color space
setting interpolates Bayer pattern encoded images into standard RGB images. If your
camera uses Bayer filtering, the toolbox supports the Bayer pattern and can return color
if desired.
In order to perform the demosaicing, the toolbox needs to know the pixel alignment of the sensor. This is the order of the red, green, and blue sensors and is normally specified by describing the four pixels in the upper-left corner of the sensor. It is the band sensitivity alignment of the pixels as interpreted by the camera's internal hardware. You must get this information from the camera's documentation and then specify the value for the alignment, as described in the following table.
There are four possible sensor alignments.
Value | Description |
---|---|
| The 2-by-2 sensor alignment is green blue red green |
| The 2-by-2 sensor alignment is green red blue green |
| The 2-by-2 sensor alignment is blue green green red |
| The 2-by-2 sensor alignment is red green green blue |
The value of this property is only used if the ReturnedColorSpace
property is set to "bayer"
.
For examples showing how to convert Bayer images, see Converting Bayer Images.
Data Types: char
| string
DeviceID
— Image acquisition device ID
1 (default) | nonnegative integer
This property is read-only.
Image acquisition device ID for the specified adaptor, specified as a nonnegative integer. This property identifies the device represented by the video input object.
A device ID is a number, assigned by an adaptor, that uniquely identifies an image
acquisition device. The adaptor assigns the first device it detects the identifier
1
, the second device it detects the identifier
2
, and so on.
You can specify the device ID as an input for the videoinput
function when you create a video input object. The object stores the value in the
DeviceID
property and also uses the value when constructing the
default value of the Name
property.
To get a list of the IDs of the devices connected to your system, use the
imaqhwinfo
function, specifying the name of a particular adaptor as
an argument.
Data Types: double
FrameGrabInterval
— How often to acquire frame from video stream
1
(default) | positive integer.
How often the video input object acquires a frame from the video stream, specified as a positive integer. By default, objects acquire every frame in the video stream, but you can use this property to specify other acquisition intervals.
Note
Do not confuse the frame grab interval with the frame rate. The frame rate describes the rate at which an image acquisition device provides frames, typically measured in seconds, such as 30 frames per second. The frame grab interval is measured in frames, not seconds. If a particular device's frame rate is configurable, the video source object might include the frame rate as a device-specific property.
For example, when you specify a FrameGrabInterval
value of
3
, the object acquires every third frame from the video stream, as
illustrated in this figure. The object acquires the first frame in the video stream
before applying the FrameGrabInterval
.
You specify the source of the video stream in the
SelectedSourceName
property.
Data Types: double
FramesAcquired
— Total number of frames acquired
0
(default) | nonnegative integer
This property is read-only.
Total number of frames that the object has acquired, regardless of how many frames
have been extracted from the memory buffer, specified as a nonnegative integer. The
video input object continuously updates the value of the
FramesAcquired
property as it acquires frames.
Note
When you issue a start
command, the video input object resets
the value of the FramesAcquired
property to 0
(zero) and flushes the buffer.
To find out how many frames are available in the memory buffer, use the
FramesAvailable
property.
Data Types: double
FramesAvailable
— Number of frames available in memory buffer
0
(default) | nonnegative integer
This property is read-only.
Total number of frames that are available in the memory buffer, specified as a
nonnegative integer. When you extract data, the object reduces the value of the
FramesAvailable
property by the appropriate number of frames. You
use the getdata
function to extract data and move it into the
MATLAB workspace.
Note
When you issue a start
command, the video input object resets
the value of the FramesAvailable
property to 0
(zero) and flushes the buffer.
To view the total number of frames that have been acquired since the last
start
command, use the FramesAcquired
property.
Data Types: double
Name
— Name of image acquisition object
character vector | string scalar
Name of the image acquisition object, specified as a character vector or string scalar.
The toolbox creates the default name by combining the values of the
VideoFormat
and DeviceID
properties with the
adaptor name in this format: VideoFormat
+
'
-'
+ adaptor name +
'
-'
+ DeviceID
Data Types: char
| string
NumberOfBands
— Number of color bands in data to be acquired
positive integer
This property is read-only.
Number of color bands in the data to be acquired, specified as a positive integer. The toolbox defines band as the third dimension in a 3-D array, as shown in this figure.
The value of the NumberOfBands
property indicates the number of
color bands in the data returned by getsnapshot
,
getdata
, and peekdata
.
Data Types: double
PreviewFullBitDepth
— Whether preview data is displayed in full bit depth
"off"
(default) | "on"
Whether the image data in the Preview window is being displayed in full bit depth,
specified as "off"
or "on"
.
Note
The Image Acquisition Toolbox Preview window
supports the display of up to 16-bit image data. The Preview window was designed to
only show 8-bit data, but many cameras return 10-, 12-, 14-, or 16-bit data. The
Preview window display supports these higher bit-depth cameras. However, larger bit
data is scaled to 8-bit for the purpose of displaying previewed data. To capture the
image data in the Preview window in its full bit depth for grayscale images, set the
PreviewFullBitDepth
property to 'on'
.
If you set this property to "off"
, image data in the preview
window is scaled down from its bit depth to 8-bit. If you set this property to
"on"
, the image data in the preview window is being captured in its
full bit depth.
This property can be set to "on"
only when the value of the
ReturnedColorspace
property is set to
"grayscale"
and for video formats higher than 8-bit
depth.
Data Types: char
| string
Previewing
— Whether object is currently previewing data in separate window
"off"
(default) | "on"
This property is read-only.
Whether the object is currently previewing data in a separate window, specified as
"off"
or "on"
.
The object sets the Previewing
property to
"on"
when you call the preview
function.
The object sets the Previewing
property to
"off"
when you close the preview window using the
closepreview
function or by clicking the
Close button in the preview window title bar.
Data Types: char
ReturnedColorSpace
— Color space used in MATLAB
"grayscale"
| "rgb"
| "YCbCr"
| "bayer"
Color space you want the toolbox to use when it returns image data to the
MATLAB workspace, specified as "grayscale"
,
"rgb"
, "YCbCr"
, or "bayer"
.
This is only relevant when you are accessing acquired image data with the
getsnapshot
, getdata
, and
peekdata
functions.
This property can have any of the following values:
Value | Description |
---|---|
"grayscale" | MATLAB grayscale color space. |
"rgb" | MATLAB RGB color space. |
"YCbCr" | MATLAB YCbCr color space. Note that YCbCr is often imprecisely referred to as YUV. (YUV is similar, but not identical. They differ by the scaling factor applied to the result. YUV refers to a particular scaling factor used in composite NTSC and PAL formats. In most cases, you can specify the YCbCr color space for devices that support YUV.) |
"bayer" | Convert grayscale Bayer color patterns to RGB images. The
To use the |
Note
For some adaptors, such as GigE and GenTL, if you use a format that starts with
Bayer (e.g. BayerGB8_640x480
), the raw Bayer pattern is
automatically converted to color – the ReturnedColorSpace
is RGB.
If you set the ReturnedColorSpace
to
"grayscale"
, you'll get the raw pattern.
For an example showing how to determine the default color space and change the color space setting, see Specifying the Color Space.
Data Types: char
| string
ROIPosition
— Region-of-interest (ROI) window
[ 0 0 width height ]
(default) | 1-by-4 element vector
Region-of-interest acquisition window, specified as a 1-by-4 element vector. The ROI defines the actual size of the frame logged by the toolbox, measured with respect to the top left corner of an image frame.
ROIPosition
is specified as a 1-by-4 element vector
[XOffset YOffset Width Height]
.
XOffset | Position of the upper left corner of the ROI, measured in pixels. |
YOffset | Position of the upper left corner of the ROI, measured in pixels. |
Width | Width of the ROI, measured in pixels. The sum of
|
Height | Height of the ROI, measured in pixels. The sum of
|
Note
The Width
does not include both end points as well as the width
between the pixels. It includes one end point, plus the width between pixels. For
example, if you want to capture an ROI of pixels 20 through 30, including both end
pixels 20 and 30, set an XOffset
of 19
and a
Width
of 11
. The same rule applies to
height
.
In the figure shown above, the width of the captured ROI contains pixels 51
through 170, including both end points, because the XOffset
is set
to 50
and the Width
is set to
120
.
Data Types: double
Running
— Whether video input object is ready to acquire data
"off"
(default) | "on"
This property is read-only.
Whether the video input object is ready to acquire data, specified as
"off"
or "on"
.
Along with the Logging
property, Running
reflects the state of a video input object. The Running
property
indicates that the object is ready to acquire data, while the Logging
property indicates that the object is acquiring data.
The object sets the Running
property to "on"
when you issue the start
command. When Running
is
"on"
, you can acquire data from a video source.
The object sets the Running
property to "off"
when any of the following conditions is met:
The specified number of frames has been acquired.
A run-time error occurs.
You issue the
stop
command.
When Running
is "off"
, you cannot acquire
image data. However, you can acquire one image frame with the
getsnapshot
function.
Data Types: char
Timeout
— Amount of time to wait for image data
10 (default) | positive integer
Amount of time in seconds that the getdata
and
getsnapshot
functions wait for data to be returned, specified as a
positive integer. The Timeout
property is only associated with these
blocking functions. If the specified time period expires, the functions return control
to the MATLAB command line.
A timeout is one of the conditions for stopping an acquisition. When a timeout
occurs, and the object is running, the MATLAB file function specified by ErrorFcn
is called.
Note
The Timeout
property is not associated with hardware timeout
conditions.
Data Types: double
UserData
— Stored data to associate with image acquisition object
any type
Stored data that you want to associate with an image acquisition object, specified as any MATLAB data type.
Note
The object does not use the data in UserData
directly. However,
you can access the data by referencing the property as you would a field in a
MATLAB structure using dot notation.
VideoFormat
— Video format or name of device configuration file
character vector
This property is read-only.
Video format used by the image acquisition device or the name of a device configuration file, depending on which you specified when you created the object, specified as a character vector.
Image acquisition devices typically support multiple video formats. When you create
a video input object, you can specify the video format that you want the device to use.
If you do not specify the video format as an argument, the videoinput
function uses the default format. Use the imaqhwinfo
function to
determine which video formats a particular device supports and find out which format is
the default.
As an alternative, you can specify the name of a device configuration file, also
known as a camera file or digitizer configuration format (DCF) file. Some image
acquisition devices use these files to store device configuration information. The
videoinput
function can use this file to determine the video format
and other configuration information.
Use the imaqhwinfo
function to determine if your device supports
device configuration files.
Data Types: char
VideoResolution
— Width and height of incoming video stream
[width height]
This property is read-only.
Width and height in pixels of the frames in the incoming video stream, specified as
a two-element vector [width height]
.
Note
You specify the video resolution when you create the video input object, by
passing in the video format argument to the videoinput
function. If
you do not specify a video format, the videoinput
function uses the
default video format. Use the imaqhwinfo
function to determine
which video formats a particular device supports and find out which format is the
default.
Data Types: double
Data Logging Properties
Logging
— Whether object is currently logging data
"off"
(default) | "on"
This property is read-only.
Whether video input object is currently logging data, specified as
"off"
or "on"
.
When a trigger occurs, the object sets the Logging
property to
"on"
and logs data to memory, a disk file, or both, depending on
the value of the LoggingMode
property.
The object sets the Logging
property to "off"
when it acquires the requested number of frames, an error occurs, or you issue a
stop
command.
To acquire data when the object is running but not logging, use the
peekdata
function. The peekdata
function does
not guarantee that all the requested image data is returned. To acquire all the data
without gaps, you must have the object log the data to memory or to a disk file.
Data Types: char
LoggingMode
— Destination for acquired data
"memory"
(default) | "disk"
| "disk&memory"
Destination for acquired data, specified as "memory"
,
"disk"
, or "disk&memory"
. This property
specifies where you want the video input object to store the acquired data. You can
specify any of the following values:
Value | Description |
---|---|
"disk" | Log acquired data to a disk file. |
"disk&memory" | Log acquired data to both a disk file and to a memory buffer. |
"memory" | Log acquired data to a memory buffer. |
If you select "disk"
or "disk&memory"
, you
must specify the AVI file object used to access the disk file as the value of the
DiskLogger
property.
Note
When logging data to memory, you must extract the acquired data in a timely manner
with the getdata
function to avoid using up all the memory that is
available on your system.
Note
The peekdata
function does not return any data while running if
in disk logging mode.
Data Types: char
| string
DiskLogger
— MATLAB VideoWriter
file used to log data
[]
(default) | VideoWriter
object
MATLAB
VideoWriter
file used to log data, specified as a
VideoWriter
object. This property specifies the
VideoWriter
file object used to log data when the
LoggingMode
property is set to "disk"
or
"disk&memory"
.
For the best performance, logging to disk requires a MATLAB
VideoWriter
object, which is a MATLAB object, not an Image Acquisition Toolbox object. After you create and configure a VideoWriter
object, you can specify it with the DiskLogger
property.
A MATLAB
VideoWriter
object specifies the file name and other characteristics.
For example, you can use VideoWriter
properties to specify the
profile used for data compression and the desired quality of the output. For complete
information about the VideoWriter
object and its properties, see the
VideoWriter
.
Note
Do not use the variable returned by the VideoWriter
function to
perform any operation on a VideoWriter
file while it is being used
by a video input object for data logging. For example, do not change any of the
VideoWriter
file properties, add frames, or close the object.
Your changes could conflict with the video input object.
After Logging
and Running
are off, it is
possible that the DiskLogger
might still be writing data to disk.
When the DiskLogger
finishes writing data to disk, the value of the
DiskLoggerFrameCount
property should equal the value of the
FramesAcquired
property. Do not close or modify the
DiskLogger
until this condition is met.
For more information about logging image data using a VideoWriter
file, see Logging Image Data to Disk.
Note
The peekdata
function does not return any data while running if
in disk logging mode.
DiskLoggerFrameCount
— Number of frames written to disk
nonnegative integer
This property is read-only.
Number of frames written to disk, specified as any nonnegative integer. This
property indicates the current number of frames written to disk by the
DiskLogger
. This value is only updated when the
LoggingMode
property is set to "disk"
or
"disk&memory"
.
After Logging
and Running
are off, it is
possible that the DiskLogger
might still be writing data to disk.
When the DiskLogger
finishes writing data to disk, the value of the
DiskLoggerFrameCount
property should equal the value of the
FramesAcquired
property. Do not close or modify the
DiskLogger
until this condition is met.
Data Types: double
Event and Callback Properties
EventLog
— Information about events
array of structures
This property is read-only.
Information about events, specified as an array of structures. Each structure in the
array represents one event. Events are recorded in the order in which they occur. The
first EventLog
structure reflects the first event recorded, the
second EventLog
structure reflects the second event recorded, and so
on.
Each event log structure contains two fields: Type
and
Data
.
The Type
field stores a character array that identifies the event
type. The Image Acquisition Toolbox defines many different event types, listed in this table. Note that not
all event types are logged.
Event Type | Description | Included in Log |
---|---|---|
Error | Run-time error occurred. Run-time errors include timeouts and hardware errors. | Yes |
Frames Acquired | The number of frames specified in the
| No |
Start | Object was started by calling the | Yes |
Stop | Object stopped executing. | Yes |
Timer | Timer expired. | No |
Trigger | Trigger executed. | Yes |
The Data
field stores information associated with the specific
event. For example, all events return the absolute time the event occurred in the
AbsTime
field. Other event-specific fields are included in
Data
. For more information, see Retrieving Event Information.
EventLog
can store a maximum of 1000 events. If this value is
exceeded, then the most recent 1000 events are stored.
Data Types: struct
ErrorFcn
— Callback function to execute when run-time error occurs
imaqcallback
(default) | character vector | function handle | cell array
Callback function to execute when an error event occurs, specified as a character vector, function handle, or cell array. A run-time error event is generated immediately after a run-time error occurs.
Run-time errors include hardware errors and timeouts. Run-time errors do not include configuration errors such as setting an invalid property value.
Run-time error event information is stored in the EventLog
property. You can retrieve any error message with the Data.Message
field of EventLog
.
Note
Callbacks, including ErrorFcn
, are executed only when the video
object is in a running state. If you need to use the ErrorFcn
callback for error handling during previewing, you must start the video object before
previewing. To do that without logging data, use a manual trigger.
Data Types: char
| string
| cell
| function_handle
FramesAcquiredFcn
— Callback function to execute when specified number of frames have been acquired
[]
(default) | character vector | function handle | cell array
Callback function to execute every time a predefined number of frames have been acquired, specified as a character vector, function handle, or cell array.
A frames acquired event is generated immediately after the number of frames
specified by the FramesAcquiredFcnCount
property is acquired from the
selected video source. This event executes the MATLAB file specified for FramesAcquiredFcn
.
Use the FramesAcquiredFcn
callback if you must access each frame
that is acquired. If you do not have this requirement, you might want to use the
TimerFcn
property.
Frames acquired event information is not stored in the EventLog
property.
Data Types: char
| string
| cell
| function_handle
FramesAcquiredFcnCount
— Number of frames that must be acquired before frames acquired event is generated
0
(default) | positive integer
Number of frames to acquire from the selected video source before a frames acquired event is generated, specified as a positive integer.
The object generates a frames acquired event immediately after the number of frames
specified by FramesAcquiredFcnCount
is acquired from the selected
video source.
Data Types: double
StartFcn
— Callback function to execute when start event occurs
[]
(default) | character vector | function handle | cell array
Callback function to execute when a start event occurs, specified as a character
vector, function handle, or cell array. A start event occurs immediately after you issue
the start
command.
The StartFcn
callback executes synchronously. The toolbox does
not set the object's Running
property to "on"
until the callback function finishes executing. If the callback function encounters an
error, the object never starts running.
Start event information is stored in the EventLog
property.
Data Types: char
| string
| cell
| function_handle
StopFcn
— Callback function to execute when stop event occurs
[]
(default) | character vector | function handle | cell array
Callback function to execute when a stop event occurs, specified as a character
vector, function handle, or cell array. A stop event occurs immediately after you issue
the stop
command.
The StopFcn
callback executes synchronously. Under most
circumstances, the image acquisition object will be stopped and the
Running
property will be set to "off"
by the
time the MATLAB file completes execution.
Stop event information is stored in the EventLog
property.
Data Types: char
| string
| cell
| function_handle
TimerFcn
— Callback function to execute when timer event occurs
[]
(default) | character vector | function handle | cell array
Callback function to execute when a timer event occurs, specified as a character
vector, function handle, or cell array. A timer event occurs when the time period
specified by the TimerPeriod
property expires.
The toolbox measures time relative to when the object is started with the
start
function. Timer events stop being generated when the image
acquisition object stops running.
Note
Some timer events might not be processed if your system is significantly slowed or
if the TimerPeriod
value you specify is too small.
Data Types: char
| string
| cell
| function_handle
TimerPeriod
— Number of seconds between timer events
1 (default) | positive value greater than 0.01
Amount of time, in seconds, that must pass before a timer event is triggered, specified as a positive value greater than 0.01.
The toolbox measures time relative to when the object is started with the
start
function. Timer events stop being generated when the image
acquisition object stops running.
Note
Some timer events might not be processed if your system is significantly slowed or
if the TimerPeriod
value you specify is too small.
Data Types: double
TriggerFcn
— Callback function to execute when trigger event occurs
[]
(default) | character vector | function handle | cell array
Callback function to execute when a trigger event occurs, specified as a character
vector, function handle, or cell array. The toolbox generates a trigger event when a
trigger is executed based on the configured TriggerType
, and data
logging is initiated.
Under most circumstances, the MATLAB file callback function is not guaranteed to complete execution until
sometime after the toolbox sets the Logging
property to
"on"
.
Trigger event information is stored in the EventLog
property.
Data Types: char
| string
| cell
| function_handle
Trigger Properties
TriggerType
— Type of trigger used by video input object
"immediate"
(default) | "hardware"
| "manual"
This property is read-only.
Type of trigger used by the video input object, specified as
"immediate"
, "hardware"
, or
"manual"
. Triggers initiate data acquisition.
You use the triggerconfig
function to specify one of the
following values for this property.
| Description |
---|---|
| Trigger executes when a specified condition is met. You specify the
condition using the |
| Trigger executes immediately after you call the
|
| Trigger executes immediately after you call the
|
Data Types: char
TriggerCondition
— Required condition before trigger event occurs
character vector
This property is read-only.
Condition that must be met, via the TriggerSource
, before a
trigger event occurs, specified as a character vector. The trigger conditions that you
can specify depend on the value of the TriggerType
property.
| Conditions Available |
---|---|
| Device-specific. For example, some Matrox® hardware supports conditions such as
|
|
|
|
|
You must use the triggerconfig
function to set the value of this
property.
Data Types: char
TriggerSource
— Hardware source to monitor for trigger conditions
character vector
This property is read-only.
Hardware source the image acquisition object monitors for trigger conditions,
specified as a character vector. When the condition specified in the
TriggerCondition
property is met, the object executes the trigger
and starts acquiring data.
You use the triggerconfig
function to specify this value. The
value of the TriggerSource
property is device specific. You specify
whatever mechanism a particular device uses to generate triggers.
For example, for Matrox hardware, the TriggerSource
property could have values
such as "Port0"
or "Port1"
. Use the
triggerinfo
function to view a list of values that are valid for
your image acquisition device.
You must use the triggerconfig
function to set the value of this
property.
Note
The TriggerSource
property is only used when the
TriggerType
property is set to
"hardware"
.
Data Types: char
FramesPerTrigger
— Number of frames to acquire per trigger using selected video source
10
(default) | positive integer
Number of frames the video input object acquires each time it executes a trigger using the selected video source, specified as a positive integer.
When the value of the FramesPerTrigger
property is set to
Inf
, the object keeps acquiring frames until an error occurs or you
issue a stop
command.
Note
When the FramesPerTrigger
property is set to
Inf
, the object ignores the value of the
TriggerRepeat
property.
Data Types: double
InitialTriggerTime
— Absolute time of first trigger
[]
(default) | MATLAB clock vector
This property is read-only.
Absolute time of the first trigger, returned as a MATLAB clock vector.
For all trigger types, InitialTriggerTime
records the time when
the Logging
property is set to "on"
.
To find the time when a subsequent trigger executed, view the
Data.AbsTime
field of the EventLog
property for
the particular trigger.
Data Types: double
TriggerFrameDelay
— Number of frames to skip before acquiring frames after trigger occurs
0 (default) | integer
Number of frames to skip before acquiring frames after a trigger occurs, specified as an integer. The object waits the specified number of frames after the trigger before starting to log frames.
In this figure, the TriggerFrameDelay
is set to
5
, so the object lets five frames pass before starting to acquire
frames. The number of frames captured is defined by the
FramesPerTrigger
property.
Data Types: double
TriggerRepeat
— Number of additional times to execute trigger
0 (default) | nonnegative integer
Number of additional times you want the object to execute a trigger, specified as a
nonnegative integer. This table describes the behavior for several typical
TriggerRepeat
values.
Value | Behavior |
---|---|
| Execute the trigger once when the trigger condition is met. |
Any positive integer | Execute the trigger the specified number of additional times when the trigger condition is met. |
| Keep executing the trigger every time the trigger condition is met
until the |
To determine how many triggers have executed, check the value of the
TriggersExecuted
property.
Note
If the FramesPerTrigger
property is set to
Inf
, the object ignores the value of the
TriggerRepeat
property.
Data Types: double
TriggersExecuted
— Total number of executed triggers
0 (default) | nonnegative integer
This property is read-only.
Total number of triggers that the video input object has executed, specified as a nonnegative integer.
Data Types: double
Video Source Object Properties
Parent
— Video input object that is parent of video source object
videoinput
object
This property is read-only.
Video input object that is the parent of a video source object, specified as a
videoinput
object.
The parent of a video source object is defined as the video input object owning the video source object.
Selected
— Whether video source object will be used for acquisition
"off"
(default) | "on"
This property is read-only.
Whether the video source object will be used for acquisition, specified as
"off"
or "on"
. You select a video source object
by specifying its name as the value of the video input object's
SelectedSourceName
property. The video input object
Source
property is an array of all the video source objects
associated with the video input object.
If Selected
is "on"
, the video source object
is selected. If the value is "off"
, the video source object is not
selected.
A video source is defined to be a collection of one or more physical data sources that are treated as a single entity. For example, hardware supporting multiple RGB sources, each of which is made up of three physical connections (red, green, and blue), is treated as a single video source object.
Data Types: char
SourceName
— Name of video source object
character vector
This property is read-only.
Name of a video source object, specified as a character vector.
SourceName
is one of the values in the video input object's
SelectedSourceName
property.
Data Types: char
Tag
— Descriptive text to associate with image acquisition object
character vector | string scalar
Descriptive text that you want to associate with an image acquisition object, specified as a character vector or string scalar.
The Tag
property can be useful when you are constructing programs
that would otherwise need to define the image acquisition object as a global variable,
or pass the object as an argument between callback routines.
You can use the value of the Tag
property to search for
particular image acquisition objects when using the imaqfind
function.
Data Types: char
| string
Type
— Type of image acquisition object
"videoinput"
| "videosource"
This property is read-only.
Type of image acquisition object, specified as "videoinput"
or
"videosource"
. An image acquisition object can be either one of two
types:
Video input object
Video source object
Data Types: char
Acquisition Source Properties
SelectedSourceName
— Name of currently selected video source
character vector | string scalar
Name of the video source object from which the video input object acquires data,
specified as a character vector or string scalar. By default, the video input object
selects the first available video source object stored in the Source
property.
The toolbox defines a video source as one or more hardware inputs that are treated as a single entity. For example, hardware supporting multiple RGB sources, each of which is made up of three physical connections (red-green-blue), is treated as a single video source object.
Data Types: char
| string
Source
— Video source objects associated with video input object
video source object
This property is read-only.
Vector of video source objects that represent the physical data sources connected to a device. When a video input object is created, the toolbox creates a vector of video source objects associated with the video input object.
Each video source object created is provided a unique source name. You can use the
source name to select the desired acquisition source by configuring the
SelectedSourceName
property of the video input object.
A video source object's name is stored in its SourceName
property. If a video source object's SourceName
is equivalent to the
video input object's SelectedSourceName
, the video source object's
Selected
property has a value of "on"
.
The video source object supports a set of common properties, such as
SourceName
. Each video source object can also support
device-specific properties that control characteristics of the physical device such as
brightness, hue, and saturation. Different image acquisition devices expose different
sets of properties.
A video source is defined to be a collection of one or more physical data sources that are treated as a single entity. For example, hardware supporting multiple RGB sources, each of which is made up of three physical connections (red-green-blue), is treated as a single video source object.
The Source
property encapsulates one or more video sources. To
reference a video source, you use a numerical integer to index into the vector of video
source objects.
GigE Properties
IgnoreDroppedFrames
— Whether the acquisition continues when it encounters a dropped frame
"off"
(default) | "on"
Whether the acquisition continues when it encounters a dropped frame, specified as
"off"
or "on"
.
If this property is set to "off"
, the acquisition stops when it
encounters a dropped frame. If this property is set to "on"
, the
acquisition continues by ignoring the dropped frames.
When this property is "on"
, keep track of the number of frames
dropped while the acquisition is running with the NumDroppedFrames
property.
Note
This property is only supported on videoinput
objects using the
gige
adaptor and is not supported on gigecam
objects.
Data Types: char
| string
NumDroppedFrames
— Number of frames dropped while acquisition is running
0 (default) | nonnegative integer
This property is read-only.
Number of frames dropped while the acquisition is running if the
IgnoreDroppedFrames
property is set to 'on'
,
specified as a nonnegative integer.
This property does not keep track of the number of frames dropped while previewing.
Note
This property is only supported on videoinput
objects using the
gige
adaptor and is not supported on gigecam
objects.
Data Types: double
Object Functions
Configuration
Execution
getselectedsource | Return currently selected video source object |
start | Obtain exclusive use of image acquisition device |
stop | Stop video input object |
wait | Wait until image acquisition object stops running or logging |
Trigger Functions
trigger | Initiate data logging |
triggerconfig | Configure video input object trigger properties |
triggerinfo | Provide information about available trigger configurations |
Data Functions
flushdata | Remove data from memory buffer used to store acquired image frames |
getdata | Acquired image frames to MATLAB workspace |
getsnapshot | Immediately return single image frame |
peekdata | Most recently acquired image data |
Tools
closepreview | Close Video Preview window |
imaqmontage | Sequence of image frames as montage |
preview | Preview of live video data |
General
Information and Help
imaqhelp | Help for image acquisition object functions and properties |
imaqhwinfo | Information about available image acquisition hardware |
propinfo | Property characteristics for image acquisition objects |
Examples
Create Video Input Object
Construct a video input object.
obj = videoinput("matrox",1);
Select the source to use for acquisition.
obj.SelectedSourceName = "input1"
View the properties for the selected video source object.
src_obj = getselectedsource(obj); get(src_obj)
Preview a stream of image frames.
preview(obj);
Acquire and display a single image frame.
frame = getsnapshot(obj); image(frame);
Remove video input object from memory.
delete(obj);
Use VideoWriter
Create a video input object that accesses a GigE Vision® image acquisition device and uses grayscale format at 10 bits per pixel.
vidobj = videoinput("gige",1,"Mono10");
You can log acquired data to memory, to disk, or both. By default, data is logged to
memory. To change the logging mode to disk, configure the video input object's
LoggingMode
property.
vidobj.LoggingMode = "disk"
Create a VideoWriter
object with the profile set to Motion JPEG
2000. Motion JPEG 2000 allows writing the full 10 bits per pixel data to the
file.
vidobj.DiskLogger = VideoWriter("logfile.mj2","Motion JPEG 2000")
Now that the video input object is configured for logging data to a Motion JPEG 2000 file, initiate the acquisition.
start(vidobj)
Wait for the acquisition to finish.
wait(vidobj)
When logging large amounts of data to disk, disk writing occasionally lags behind
the acquisition. To determine whether all frames are written to disk, you can optionally
use the DiskLoggerFrameCount
property.
while (vidobj.FramesAcquired ~= vidobj.DiskLoggerFrameCount) pause(.1) end
You can verify that the FramesAcquired
and
DiskLoggerFrameCount
properties have identical values by using
these commands and comparing the output.
vidobj.FramesAcquired vidobj.DiskLoggerFrameCount
When the video input object is no longer needed, delete it and clear it from the workspace.
delete(vidobj)
clear vidobj
Version History
Introduced before R2006a
MATLAB 명령
다음 MATLAB 명령에 해당하는 링크를 클릭했습니다.
명령을 실행하려면 MATLAB 명령 창에 입력하십시오. 웹 브라우저는 MATLAB 명령을 지원하지 않습니다.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)