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 six categories, Basic, Advanced, Util, Laser, UHP 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 Laser, LSR and DEEP series cameras only.

• UHP: for UHP series cameras only.

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

Basic

• ConnectToCamera: Connect to a Mech-Eye Industrial 3D Camera.

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

• CaptureColorMap: Obtain and save the 2D image from a camera.

• CaptureDepthMap: Obtain and save the depth map from a camera.

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

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

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

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

Advanced

• CaptureCloudFromDepth: Construct and save point clouds from the depth map and 2D image obtained from a camera.

• CaptureSequentiallyMultiCamera: Obtain and save 2D images, depth maps and point clouds sequentially from multiple cameras.

• CaptureSimultaneouslyMultiCamera: Obtain and save 2D images, depth maps and point clouds simultaneously from multiple cameras.

• CaptureTimedAndPeriodically: Obtain and save 2D images, depth maps and point clouds periodically for the specified duration from a camera.

Util

• GetCameraIntri: Get and print a camera’s intrinsic parameters.

• PrintDeviceInfo: Get and print a camera’s information such as model, serial number and firmware version.

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

• SetParameters: Set specified parameters to a camera.

• SetUserSets: Perform functions related to parameter groups, such as switching to a different parameter group, adding and deleting parameter groups, etc. The parameter group feature allows user to save and quickly apply a set of parameter values.

Laser

• SetLaserFramePartitionCount: Divide 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: Set the projection range of the structured light. The entire projector FOV is from 0 to 100.

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

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

UHP

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

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

Halcon

• CaptureHalconPointCloud: Obtain point cloud data from a camera, and then transform and save 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 IPC correctly.

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

• Install the required software.

• Install the optional software on which samples depend.

Attention

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.

For instructions on installing the required and optional software, please refer to the following sections.

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 according to Install Mech-Eye SDK on Ubuntu.

   Once Mech-Eye SDK is successfully installed, the Mech-Eye API C++ samples are located in /opt/mech-mind/mech-eye-sdk/samples/.

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

Attention

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
  

• Install HALCON and add environmental variables.

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

     tar zxvf halcon-20.11.3.0-linux.tar.gz
     sudo sh install-linux.sh #Note down the installation directory of HALCON.
     

  2. 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 actuall installation directory of HALCON.

     HALCONARCH=x64-linux; export HALCONARCH
     HALCONROOT="/opt/halcon"; export HALCONROOT
     HALCONEXAMPLES=${HALCONROOT}/examples; export HALCONEXAMPLES
     HALCONIMAGES=${HALCONROOT}/examples/images; export HALCONIMAGES
     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
     

  Note

  • The changes are applied when you log in again. Or, you can source /etc/profile/ 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.

Disable Unneeded Samples (Optional)

Attention

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 CMakeLists.txt in xxx\Mech-Eye SDK-x.x.x\API\samples 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

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

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

     cd /opt/mech-mind/mech-eye-sdk/samples/
     

   • 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/mech-eye-sdk/samples/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
   

Tip

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

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/mech-eye-sdk/samples/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/mech-eye-sdk/samples/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.