Grabbing an Image

This article shows in detail how to set up a data stream from a video capture device and grab a single image.

Opening and Configuring the Video Capture Device

First, the library is initialized, and the first available video capture device is opened:

// Initialize the library
ic4::initLibrary();
 
// Create a grabber object
ic4::Grabber grabber;
 
// Open the first available video capture device
auto firstDevInfo = ic4::DeviceEnum::enumDevices().front();
grabber.deviceOpen(firstDevInfo);
 
std::cout << "Opened device " << grabber.deviceInfo().modelName() << std::endl;
static std::vector< DeviceInfo > enumDevices(Error &err=Error::Default())
Get a list of the devices currently attached to the system.
Definition DeviceEnum.h:446
std::string modelName(Error &err=Error::Default()) const
Gets the model name for this device.
Definition DeviceEnum.h:116
Represents an opened video capture device, allowing device configuration and stream setup.
Definition Grabber.h:82
bool deviceOpen(const DeviceInfo &dev, Error &err=Error::Default())
Opens the video capture device specified by the passed device information object.
Definition Grabber.h:147
DeviceInfo deviceInfo(Error &err=Error::Default()) const
Returns information about the currently opened video capture device.
Definition Grabber.h:504
bool initLibrary(const InitLibraryConfig &config={})
This function must be used to initialize the library.
Definition InitLibrary.h:89

Then, the device has to be configured. This step is important because in most situations, programs want the camera to be in a defined state before starting operation. In this example, the resolution is configured using the device's ic4::PropId::Width and ic4::PropId::Height properties:

// Set the resolution to 640x480
grabber.devicePropertyMap().setValue(ic4::PropId::Width, 640);
grabber.devicePropertyMap().setValue(ic4::PropId::Height, 480);
PropertyMap devicePropertyMap(Error &err=Error::Default()) const
Returns the property map for the currently opened video capture device.
Definition Grabber.h:561
bool setValue(const char *integer_name, int64_t value, Error &err=Error::Default())
Set the value of a property with a known name to the passed integer value.
Definition Properties.h:1982
constexpr PropIdInteger Height
Height of the image provided by the device (in pixels).
Definition PropertyConstants.h:700
constexpr PropIdInteger Width
Width of the image provided by the device (in pixels).
Definition PropertyConstants.h:1100

At this point, an application could also load a prepared device configuration file (using ic4::Grabber::deviceOpenFromState or apply a serialized property configuration using ic4::PropertyMap::deSerialize).

Setting up the Sink and Data Stream

After the device has been configured, it is time to setup a data stream. To receive image data from the video capture device, a Sink object has to be created. The ic4::SnapSink is the sink most suitable to grab images on demand.

// Create a SnapSink. A SnapSink allows grabbing single images (or image sequences) out of a data stream.
auto sink = ic4::SnapSink::create();
// Setup data stream from the video capture device to the sink and start image acqui
bool streamSetup(const std::shared_ptr< Sink > &sink, const std::shared_ptr< Display > &display, StreamSetupOption action=StreamSetupOption::AcquisitionStart, Error &err=Error::Default())
Establishes the data stream from the device.
Definition Grabber.h:271
static std::shared_ptr< SnapSink > create(Error &err=Error::Default())
Creates a SnapSink using the default configuration.
Definition SnapSink.h:161
@ AcquisitionStart
Start acquisition after the stream was set up.

The data stream is established by calling ic4::Grabber::streamSetup, passing the sink as a parameter. We also set the setupOption parameter to ic4::StreamSetupOption::AcquisitionStart, so that the device is instructed to start image acquisition immediately after the data stream was created.

After the streamSetup call returned successfully, the device is continuously sending images to the host computer.

Grabbing an Image

By calling ic4::SnapSink::snapSingle, the sink is instructed to wait for the next image to arrive at the sink and, if an image is received during the specified timeout period, return it:

try
{
    // Grab a single image out of the data stream.
    auto image = sink->snapSingle(std::chrono::milliseconds(1000));
 
    // Print image information.
    std::cout << "Received an image: " << to_string(image->imageType()) << std::endl;
 
    // Save the image.
    ic4::imageBufferSaveAsBitmap(*image, "test.bmp");
}
catch (ic4::IC4Exception ex)
{
    std::cerr << ex.what() << std::endl;
}
Exception thrown if an error occurs and exceptions are enabled for the failing function call.
Definition Error.h:298
const char * what() const noexcept final
Returns the error message of the error that caused this exception.
Definition Error.h:328
bool imageBufferSaveAsBitmap(const ic4::ImageBuffer &buffer, const char *file_path, const SaveBitmapOptions &opt={}, Error &err=Error::Default())
Saves an image buffer as a Bitmap file.
Definition SaveImages.h:44

In this example, we print information about the received image and save it in a bitmap file.

Both ic4::SnapSink::snapSingle and ic4::imageBufferSaveAsBitmap could potentially fail. Therefore, we wrap the code into a try..catch block to print the error message in case an error occurs.

Stopping the Data Stream

A call to ic4::Grabber::streamStop stops the data stream:

/ Stop the data stream.
grabber.streamStop();
bool streamStop(Error &err=Error::Default())
Stops a data stream that was previously set up by a call to Grabber::streamSetup().
Definition Grabber.h:461

Stopping acquisition and data stream is important, because keeping the acquisition active would waste CPU and memory resources as well as bandwidth on the transmission medium.