Tutorial - Image Capture

This tutorial shows how to capture the left image of the ZED camera and print its timestamp and image size in the terminal. The program will loop until it has successfully grabbed 50 images. We assume that you have read the Hello ZED tutorial before.

Getting Started #

  • First, download the latest version of the ZED SDK.
  • Download the Image Capture sample code in C++, Python or C#.

Code Overview #

Open the camera #

As in the previous tutorial, here we create, configure and open the ZED. We set the 3D camera to dual HD 1080 resolution at 30 fps.

// Create a ZED camera object
Camera zed;

// Set configuration parameters
InitParameters init_params;
init_params.camera_resolution = RESOLUTION_HD1080; // Use HD1080 video mode
init_params.camera_fps = 30; // Set fps at 30

// Open the camera
ERROR_CODE err = zed.open(init_params);
if (err != ERROR_CODE::SUCCESS)
    exit(-1);

# Create a ZED camera object
zed = sl.Camera()

# Set configuration parameters
init_params = sl.InitParameters()
init_params.camera_resolution = sl.RESOLUTION.HD1080  # Use HD1080 video mode
init_params.camera_fps = 30  # Set fps at 30

# Open the camera
err = zed.open(init_params)
if err != sl.ERROR_CODE.SUCCESS:
    exit(1)

// Create a ZED camera object
Camera zed = new Camera(0);

// Set configuration parameters
InitParameters init_params = new InitParameters();
init_params.resolution = RESOLUTION.HD1080; // Use HD1080 video mode
init_params.cameraFPS = 30; // Set fps at 30

// Open the camera
ERROR_CODE err = zed.Open(ref init_params);
if (err != ERROR_CODE.SUCCESS)
    Environment.Exit(-1);

Capture Image Data #

Now that the ZED is opened, we can capture the live stream coming from the camera. Let’s create a loop that captures 50 images and exits.

To capture an image and process it, you need to call the Camera::grab() function. This function can take runtime parameters as well, but we leave them to default in this tutorial.

If grab() returns SUCCESS, a new image has been captured and is now available. You can also check the status of grab() which tells you if there is an issue during capture.

// Grab an image
if (zed.grab() == ERROR_CODE::SUCCESS) {
	// A new image is available if grab() returns ERROR_CODE::SUCCESS
}

# Grab an image
runtime_parameters = sl.RuntimeParameters()
if zed.grab(runtime_parameters) == sl.ERROR_CODE.SUCCESS:
    # A new image is available if grab() returns ERROR_CODE.SUCCESS

// Grab an image
RuntimeParameters runtimeParameters = new RuntimeParameters();
if (zed.Grab(ref runtimeParameters) == ERROR_CODE.SUCCESS) {
    // A new image is available if Grab() returns ERROR_CODE.SUCCESS
}

Once the grab() method has been executed, you can retrieve the new image and its metadata. In this tutorial, we will retrieve the left image and its timestamp using retrieveImage() and getTimestamp().

retrieveImage() takes an sl::Mat as well as a VIEW mode as parameters. When creating the Mat, you don’t need to allocate memory. The first time retrieveImage() is called, the Mat is filled with image data and memory is allocated automatically.

// Capture 50 frames and stop
int i = 0;
sl::Mat image;
while (i < 50) {
    // Grab an image
    if (zed.grab() == ERROR_CODE::SUCCESS) {
        // A new image is available if grab() returns ERROR_CODE::SUCCESS
        zed.retrieveImage(image, VIEW::LEFT); // Get the left image
        auto timestamp = zed.getTimestamp(sl::TIME_REFERENCE::IMAGE); // Get image timestamp
        printf("Image resolution: %d x %d  || Image timestamp: %llu\n", image.getWidth(), image.getHeight(), timestamp);
        i++;
    }
}

# Capture 50 frames and stop
i = 0
image = sl.Mat()
runtime_parameters = sl.RuntimeParameters()
while i < 50:
    # Grab an image, a RuntimeParameters object must be given to grab()
    if zed.grab(runtime_parameters) == sl.ERROR_CODE.SUCCESS:
        # A new image is available if grab() returns ERROR_CODE.SUCCESS
        zed.retrieve_image(image, sl.VIEW.LEFT) # Get the left image
        timestamp = zed.get_timestamp(sl.TIME_REFERENCE.IMAGE)  # Get the image timestamp
        print("Image resolution: {0} x {1} || Image timestamp: {2}\n".format(image.get_width(), image.get_height(), timestamp.get_milliseconds()))
        i = i + 1

uint mWidth = (uint)zed.ImageWidth;
uint mHeight = (uint)zed.ImageHeight;
// Initialize the Mat that will contain the left image
Mat image = new Mat();
image.Create(mWidth, mHeight, MAT_TYPE.MAT_8U_C4, MEM.CPU); // Mat needs to be created before use.

// Capture 50 frames and stop
int i = 0;
RuntimeParameters runtimeParameters = new RuntimeParameters();
while (i < 50) {
    // Grab an image
    if (zed.Grab(ref runtimeParameters) == ERROR_CODE.SUCCESS) {
        // A new image is available if grab() returns ERROR_CODE::SUCCESS
        zed.RetrieveImage(image, VIEW.LEFT); // Get the left image
        ulong timestamp = zed.GetCameraTimeStamp(); // Get image timestamp
        Console.WriteLine("Image resolution: " + image.GetWidth() + "x" + image.GetHeight() + " || Image timestamp: " + timestamp);
        i++;
    }
}

📌 Note: Image timestamp is given in nanoseconds and Epoch format. You can compare the timestamps between two grab(): it should be close to the framerate time, if you don’t have any dropped frames.

For more information on Camera and Video parameters, read Using the Video API.

Close the Camera #

Now that we have captured 50 images, let’s close the camera and exit the program.

// Close the camera
zed.close();

# Close the camera
zed.close()

// Close the camera
zed.Close();

Additional Example #

To learn how to adjust camera settings like Exposure, Gain, Contrast, Sharpness, etc. and display the resulting image, check the Camera Control sample code.

Next Steps #

At this point, you know how to open the camera, access the camera and sensor configuration, and grab and retrieve image frames and metadata.

Read the Depth Sensing tutorial to learn how to retrieve depth maps from ZED stereo cameras.