How to Build an App with the ZED SDK

Introduction

The goal of this tutorial is to show you how to build applications using the ZED SDK.

All our programs are developed in C++, therefore working knowledge of C++ programming and the C++ compilation pipeline is required (command line or IDE) for this tutorial.

Prerequisites

First of all, make sure that your environment is set up correctly, as explained here.
Note: On Windows, please use Visual Studio 2015.

Then start coding your first program using the ZED camera. Here is a very simple “Hello World” program, that just initializes the ZED camera and prints its serial number:

#include <sl/Camera.hpp>
using namespace sl;

int main(int argc, char **argv) {

    // Create a ZED camera object
    Camera zed;

    // Set configuration parameters
    InitParameters init_params;
    init_params.sdk_verbose = false; // Disable verbose mode

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

    // Get camera information (ZED serial number)
    int zed_serial = zed.getCameraInformation().serial_number;
    printf("Hello! This is my serial number: %d\n", zed_serial);

    // Close the camera
    zed.close();
    return 0;
}

Let’s see how to compile this!

Cross-platform method using CMake

The compilation method works on every platform supported by the ZED SDK and provides an easy way to generate a project for every major IDE.

CMake 3.5.0 is the recommended minimum version.

1. Folders and files

Create a folder where you want to put your project. Create a sub-folder named src/. In this folder, add the file main.cpp given above.

Then in the folder of the project, create a file named CMakeLists.txt :

SET(execName ZED_Project)
CMAKE_MINIMUM_REQUIRED(VERSION 2.8)
PROJECT(${execName})

if(COMMAND cmake_policy)
	cmake_policy(SET CMP0003 OLD)
	cmake_policy(SET CMP0015 OLD)
endif(COMMAND cmake_policy)

SET(EXECUTABLE_OUTPUT_PATH ".")

SET(VERSION_REQ_CUDA "8.0")

IF(WIN32) # Windows
    if (CMAKE_CL_64) 
        SET(ZED_INCLUDE_DIRS $ENV{ZED_INCLUDE_DIRS})
        SET(ZED_LIBRARIES $ENV{ZED_LIBRARIES_64})
        SET(ZED_LIBRARY_DIR $ENV{ZED_LIBRARY_DIR})
    else()
        message(FATAL_ERROR "You've selected the 32bit version of ${CMAKE_GENERATOR}. \n Please delete the cache (file->Delete Cache) and use the 64bit version. (${CMAKE_GENERATOR} Win64)")
    endif()
ELSE() # Linux
    find_package(ZED 2 REQUIRED)
    SET(SPECIAL_OS_LIBS "pthread")
ENDIF(WIN32)

find_package(CUDA ${VERSION_REQ_CUDA} REQUIRED)
 
include_directories(${CUDA_INCLUDE_DIRS})
include_directories(${ZED_INCLUDE_DIRS})
#include_directories(${CMAKE_CURRENT_SOURCE_DIR}/include)

link_directories(${ZED_LIBRARY_DIR})
link_directories(${CUDA_LIBRARY_DIRS})

SET(SRC_FOLDER src)
FILE(GLOB_RECURSE SRC_FILES "${SRC_FOLDER}/*.cpp")  
ADD_EXECUTABLE(${execName} ${SRC_FILES})

add_definitions(-std=c++0x -g -O3)

# Add the required libraries for linking:
TARGET_LINK_LIBRARIES(${execName}
                        ${ZED_LIBRARIES}
                        ${SPECIAL_OS_LIBS}
                        ${CUDA_LIBRARIES} ${CUDA_npps_LIBRARY} ${CUDA_nppi_LIBRARY} )

This file is used by CMake as a description of the project to generate. Using that file, CMake is able to generate the following files:

• a Makefile;
• an IDE project file;
• or both (for IDE supporting Makefile)

Note: The folder containing the cpp source file is given in the CMakeLists.txt file, in our case ‘src’. The standard cpp project compiled with CMake typically contain a ‘src’ and ‘include’ folder for the source code and the header files. The CMakeLists is often in the root folder of the project and the binary generation is done in a build folder. This is for good-practice and clarity but nothing prevent you from putting everything in the same folder, as long as you update the source folder in the CMakeLists.txt

To get more information about how to write a CMakeLists.txt file, check the last section of this tutorial.

2. Generate project on Windows

Open cmake-gui.

In “Where is the source code“, enter the path of your project folder, ie where the CMakeLists.txt file is.

In “Where to build the binaries“, enter the previous path and add: /build.

Click the “Configure” button.

A dialog window asks you if CMake can create the folder “build” itself. Say yes.

Then another dialog window will ask you the generator of your project. Choose Visual Studio. For example, we choose “Visual Studio 14 2015 Win64” (it is impotant to select the “Win64” version). Click the “Finish” button.

CMake may take few seconds to configure the project. Then, some red lines should be displayed in the cmake-gui window.

Click the “Generate” button.

CMake has just generated your project in the build folder. Now, you can close the cmake-gui window and go to the build folder.

Visual Studio files has been generated and a Visual Studio project file named “Project.sln” too. Open it with Visual Studio. You can now edit and compile your program with the Visual Studio IDE.

3. Generate project on Linux

Open your terminal, and move your prompt to your project’s folder.

$ cd path/to/your/project/folder

Create a build folder and change directory.

$ mkdir build
$ cd build

Ask CMake to generate your project with the location of the CMakeLists.txt (one folder above).

$ cmake ..

You should get the following outputs:

-- The C compiler identification is GNU 4.8.4
-- The CXX compiler identification is GNU 4.8.4
-- Check for working C compiler: /usr/bin/cc
-- Check for working C compiler: /usr/bin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Found CUDA: /usr/local/cuda (found suitable exact version "8.0")
-- Configuring done
-- Generating done
-- Build files have been written to: /path/to/your/project/folder/build
$

And if you list the folder’s content, you must have the following output:

$ ls
CMakeCache.txt  CMakeFiles  cmake_install.cmake Makefile

Now, you can edit and change your code as you wish. Then to compile your program, enter the following command:

$ make

Finally to test the program:

$ ./ZED_Project

You should get something like:

Hello! This is my serial number: 12042

4. CMakeLists.txt : writing your own cmake program

Let’s break into the CMakeLists.txt to see how it works.

Setting the project attributes

At the beginning of the CMakeList.txt file, you can find the following lines:

SET(execName ZED_Project)
CMAKE_MINIMUM_REQUIRED(VERSION 2.8)
PROJECT(${execName})
if(COMMAND cmake_policy)
	cmake_policy(SET CMP0003 OLD)
	cmake_policy(SET CMP0015 OLD)
endif(COMMAND cmake_policy)

The project is named ZED_Project and the minimum required version of CMAKE is 2.8. Even if 2.8 is the minimum requirment, CMake 3.5.0 is recommended.

The path where the executable of your program must be generated is then set. Using this command:

SET(EXECUTABLE_OUTPUT_PATH ".")

Setting the path of dependencies

Now, the dependencies of your program must be set. But you have to set the specific location for each system (Windows and Linux). Here, you need ZED and CUDA libraries+headers.

Please note that on Windows, the ZED SDK will specify the environment path during installation of the SDK. Therefore, you can call $ENV(…) with the tags ZED_INCLUDE_DIRS, ZED_LIBRARIES_32/64 to get the include and libs path of the ZED SDK.

On Linux, we also provide a zed-config.cmake to automatically find the include and libs folder of the ZED SDK through a find_package(…).

IF(WIN32) # Windows
    if (CMAKE_CL_64) 
        SET(ZED_INCLUDE_DIRS $ENV{ZED_INCLUDE_DIRS})
        SET(ZED_LIBRARIES $ENV{ZED_LIBRARIES_64})
        SET(ZED_LIBRARY_DIR $ENV{ZED_LIBRARY_DIR})
    else()
        message(FATAL_ERROR "You've selected the 32bit version of ${CMAKE_GENERATOR}. \n Please delete the cache (file->Delete Cache) and use the 64bit version. (${CMAKE_GENERATOR} Win64)")
    endif()
ELSE() # Linux
    find_package(ZED 2 REQUIRED)
    SET(SPECIAL_OS_LIBS "pthread")
ENDIF(WIN32)
find_package(CUDA ${VERSION_REQ_CUDA} REQUIRED)

Linking the dependencies to CMAKE

Now that your environment contains the path, you must tell CMAKE what will be the include directories (headers) and link directories (libs). Here is how to do this:

include_directories(${CUDA_INCLUDE_DIRS})
include_directories(${ZED_INCLUDE_DIRS})
include_directories(${CMAKE_CURRENT_SOURCE_DIR}/include)

link_directories(${ZED_LIBRARY_DIR})
link_directories(${CUDA_LIBRARY_DIRS})

Dependencies are linked to CMAKE.

Setting the path of the source code

Now, you must tell CMAKE where to find the source code to compile. In this tutorial, the source code is in the sub-folder src/.

SET(SRC_FOLDER src)
FILE(GLOB_RECURSE SRC_FILES "${SRC_FOLDER}/*.cpp")
ADD_EXECUTABLE(${execName} ${SRC_FILES})

The second line specifies that the SRC_FILES will contain all the cpp file of the directory. The last line specifies which files to add to the executable, in this case we generate only one program with every source file.

Now your CMakeList.txt file is almost set. The next step is the last one ;).

Linking the libraries during compiling process

Indeed, you just have to tell CMAKE to link the libraries during the compiling process.

# Add the required libraries for linking:
TARGET_LINK_LIBRARIES(${execName}
                        ${ZED_LIBRARIES}
                        ${SPECIAL_OS_LIBS}
                        ${CUDA_LIBRARIES} ${CUDA_npps_LIBRARY} ${CUDA_nppi_LIBRARY} )

ZED libraries use C++11. So you must tell your compiler.

add_definitions(-std=c++0x)

File ready

Now, your project is ready to be generated.

Note: you can add compile tags for better performance :

SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -g -O3" ) # Release Perf mode