C++ (Ubuntu)

This topic introduces how to configure the Mech-Eye API C++ samples with CMake and then build the samples with the make command on Ubuntu.

Sample List

Samples are divided into 7 categories, Basic, Advanced, Util, Laser, UHP, Calibration, and Halcon.

  • Basic: camera connection and basic capturing functions.

  • Advanced: advanced capturing functions.

  • Util: obtain information from a camera and set camera parameters.

  • Laser: for the Laser, DEEP and LSR series cameras only.

  • UHP: for the UHP series cameras only.

  • Calibration: perform hand-eye calibration through Mech-Eye API.

  • Halcon: obtain HALCON-readable point clouds through Mech-Eye API.

The samples in each category and their descriptions are provided below.

Basic
  • ConnectToCamera: Connects to a camera.

  • ConnectAndCaptureImage: Connects to a camera and obtains the 2D image, depth map and point cloud data.

  • CaptureColorMap: Obtains and saves the 2D image from a camera.

  • CaptureDepthMap: Obtains and saves the depth map from a camera.

  • CapturePointCloud: Obtains and save untextured and textured point clouds generated from images captured with a single exposure time.

  • CaptureHDRPointCloud: Obtains and save untextured and textured point clouds generated from images captured with multiple exposure times.

  • CapturePointCloudROI: Obtains and save untextured and textured point clouds of the objects in the ROI from a camera.

  • CapturePointCloudFromTextureMask: Constructs and saves untextured and textured point clouds generated from a depth map and masked 2D image.

Advanced
Util
  • GetCameraIntri: Gets and prints a camera’s intrinsic parameters.

  • PrintDeviceInfo: Gets and prints a camera’s information such as model, serial number, firmware version and temperatures.

  • SetDepthRange: Sets the range of depth values to be retained by a camera.

  • SetParameters: Sets specified parameters to a camera.

  • SetUserSets: Performs functions related to parameter groups, such as obtaining the names of all available parameter groups, selecting a parameter group, and saving the parameter values to the current parameter group. The parameter group feature allows user to save and quickly apply a set of parameter values.

Laser
  • SetLaserFramePartitionCount: Divides the projector FOV into partitions and project structured light in one partition at a time. The output of the entire FOV is composed from images of all partitions.

  • SetLaserFrameRange: Sets the projection range of the structured light. The entire projector FOV is from 0 to 100.

  • SetLaserFringeCodingMode: Sets the coding mode of the structured light pattern.

  • SetLaserPowerLevel: Sets the output power of the laser projector in percentage of max power. This affects the intensity of the laser light.

UHP
  • SetUHPCaptureMode: Sets the capture mode (capture images with 2D camera 1, with 2D camera 2, or with both 2D cameras and compose the outputs).

  • SetUHPFringeCodingMode: Sets the coding mode of the structured light pattern.

Calibration
Halcon
  • CaptureHalconPointCloud: Obtains point cloud data from a camera, and then transforms and saves the point clouds using HALCON C++ interface.

Prerequisites

In order to use the C++ samples of Mech-Eye API, the following prerequisites must be satisfied:

  • Connect the camera and computer correctly.

  • The version of the Ubuntu operating system is 18 or above.

  • Obtain the samples.

  • Install the required software.

  • Install the optional software on which samples depend.

If using a Ubuntu virtual machine, please ensure that the available disk space is greater than 20 GB. Otherwise, installation of the software may fail.

Obtain the Samples

C++ samples are included in the installation directory of Mech-Eye SDK or can be obtained from GitHub by cloning. The samples in the installation directory are the version at the time of Mech-Eye SDK release. The version on GitHub may contain later changes.

  • The samples in the installation directory are located in /opt/mech-mind/mech-eye-sdk/samples/c++/source.

  • The samples cloned from GitHub are located in xxx/mecheye_cpp_samples/source.

Install Required Software

In order to use the C++ samples of Mech-Eye API, the software source list must be updated, and Mech-Eye SDK and dependencies must be installed.

  1. Update software source list:

    sudo apt-get update
  2. Install dependencies:

    sudo apt-get install -y build-essential pkg-config cmake
  3. Install Mech-Eye SDK: Please refer to Mech-Eye SDK Installation Guide (Ubuntu).

Install Optional Software

Some samples contain functions that depend on the following third-party software libraries. If you need to use the samples listed in the table below, you must install the software on which the samples depend.

  • OpenCV: latest version

  • PCL: latest version

  • HALCON: version 20.11 or above

    HALCON versions below 20.11 are not fully tested.

If any of the optional software is not installed, then you must complete the steps in Disable Unneeded Samples (Optional) before configuring the samples.

Refer to the following table for the samples that depend on third-party software libraries.

Sample OpenCV PCL Halcon

CaptureColorMap

CaptureDepthMap

CapturePointCloud

CaptureHDRPointCloud

CapturePointCloudROI

CapturePointCloudFromTextureMask

CaptureCloudFromDepth

CaptureTimedAndPeriodically

CaptureSimultaneouslyMultiCamera

CaptureSequentiallyMultiCamera

CaptureHalconPointCloud

  • Install OpenCV:

    sudo apt update && sudo apt install -y unzip
    wget -O opencv.zip https://github.com/opencv/opencv/archive/4.x.zip
    unzip opencv.zip
    mkdir build && cd build
    cmake ../opencv-4.x
    cmake --build .
    sudo make install
  • Install PCL:

    sudo apt-get install libpcl-dev
    On different versions of Ubuntu, this command installs different versions of PCL. On Ubuntu 18.04, PCL 1.8.1 is installed; on Ubuntu 20.04, PCL 1.10.0 is installed.
  • Install HALCON and add environmental variables:

    • After downloading HALCON installer, use the following command to install HALCON (taking version 20.11 as an example):

      tar zxvfHALCON-20.11.3.0-linux.tar.gz
      sudo sh install-linux.sh #Note down the installation directory ofHALCON.
    • Add HALCON-relevant environment variables: open /etc/profile in an editor (such as vi) and paste the following lines to the end of the file. Replace /opt/halcon with the actual installation directory of HALCON.

      HALCONARCH=x64-linux; exportHALCONARCH
      HALCONROOT="/opt/halcon"; exportHALCONROOT
      HALCONEXAMPLES=${HALCONROOT}/examples; exportHALCONEXAMPLES
      HALCONIMAGES=${HALCONROOT}/examples/images; exportHALCONIMAGES
      PATH=${HALCONROOT}/bin/${HALCONARCH}:${PATH}; export PATH
      if [ ${LD_LIBRARY_PATH} ]; then
         LD_LIBRARY_PATH=${HALCONROOT}/lib/${HALCONARCH}:${LD_LIBRARY_PATH}; export LD_LIBRARY_PATH
      else
         LD_LIBRARY_PATH=${HALCONROOT}/lib/${HALCONARCH}; export LD_LIBRARY_PATH
      fi
    • The changes are applied when you log in again. Or, you can run the source /etc/profile/ command before you configure and build the samples.

    • For more information, please refer to HALCON’s installation guide.

Build and Run Samples

You can build all samples at once or build a single sample individually.

The paths provided in this section correspond to the samples included in the installation directory. If you are using the samples cloned from GitHub, please modify the paths correspondingly.

Disable Unneeded Samples (Optional)

If you did not install some of the optional software and still want to build all samples at once, then you must complete the steps in this section. Otherwise, an error will occur during the configuration of samples using CMake.

If you do not need the samples that depend on OpenCV, PCL or HALCON, please edit the CMakeLists file to disable these samples before building all samples at once.

  1. Open /opt/mech-mind/eye-sdk/samples/c++/source/CMakeLists.txt in an editor (such as vi).

  2. Edit lines containing options: find the lines starting with options, change ON at the end of the line to OFF to disable the samples that depend on the software mentioned in that line. Example: If you do not need to build the sample that depends on HALCON, change ON at the end of the line starting with option(USE_HALCON to OFF.

  3. Save the changes in the editor and close the CMakeLists file.

Build Samples

Please follow these steps to run the sample:

  1. Enter the directory of the sample(s):

    • If building all samples at once, please use the following command.

      cd /opt/mech-mind/eye-sdk/samples/c++/source/
    • If building a single sample individually, please use the following command. Replace Category with the category name of the sample and SampleName with the name of the sample.

      cd /opt/mech-mind/eye-sdk/samples/c++/source/Category/SampleName/
  2. Create a build folder in the directory for saving the built samples and so on.

    mkdir build && cd build
  3. Configure and build the sample(s):

    cmake ..
    make
If the source code files in the sample folder are altered, please delete the build folder and repeat steps 2 and 3 to rebuild the samples.

Run Samples

After building the samples, follow these steps to run the sample:

  1. Enter the build folder in the directory of the sample(s) (Skip this step if you are running the sample(s) directly after building the sample(s):

    • If building all samples at once, please use the following command.

      cd /opt/mech-mind/eye-sdk/samples/c++/source/build/
    • If building a single sample individually, please use the following command. Replace Category with the category name of the sample and SampleName with the name of the sample.

      cd /opt/mech-mind/eye-sdk/samples/c++/source/Category/SampleName/build/
  2. Run the sample: replace SampleName with the name of the sample. While the sample is running, input the device index of the camera to which you want to connect according to the instruction, and press Enter to connect.

    ./SampleName
  3. If image and/or point cloud files are saved by the sample, you can find the files in the build folder.