C++ (Windows)¶
This topic introduces how to configure the Mech-Eye API C++ samples with CMake and then build the samples with Visual Studio on Windows.
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.
Calibration: perform hand-eye calibration through Mech-Eye API.
Halcon: obtain HALCON-readable point clouds through 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, firmware version and temperatures.
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.
Calibration
HandEyeCalibration: Perform hand-eye calibration.
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.
Install the required software.
Install the optional software on which samples depend and add relevant environment variables.
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, Mech-Eye SDK, CMake and Visual Studio must be installed.
- Install the latest version of Mech-Eye SDK
Please install or upgrade Mech-Eye SDK according to Mech-Eye SDK Installation Guide.
- Install CMake (version 3.2 or above)
Download CMake: download the installer to the right of Windows x64 Installer.
When installing, select the following two options to add CMake to environment variables and create a desktop shortcut for CMake.
Add CMake to the system PATH for all users
Create Cmake Desktop Icon
- Install Visual Studio (version 2017 or above)
Download the Visual Studio installer.
When installing, select the following two workloads in the Desktop & Mobile category, and then click Install.
Desktop development with C++
Universal Windows Platform development
Hint
Please restart your computer after installing Visual Studio. If you still need to install the optional software, you can restart your computer after adding environment variables.
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: version 3.4.5 or above
PCL: version 1.8.1 or above
HALCON: version 20.11 or above
Note
HALCON versions below 20.11 are not fully tested.
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
Download and install OpenCV. Note down the installation directory of OpenCV.
Add OpenCV to environment variables. Refer to Add Environment Variables for instructions.
- Install PCL
Refer to the following table and determine the version of PCL to install based on the version of Visual Studio.
Visual Studio version
Supported PCL versions
2017
1.8.1–1.9.1
2019
1.8.1–1.12.1
2022
1.8.1 and above
Open the PCL download page, click on Assets under the corresponding version, and download the EXE installer.
Run the installer to install PCL. When installing, select Add PCL to the system PATH for all users to add PCL to environment variables.
Hint
The following error message might pop up during installation:
Warning! PATH too long installer unable to modify PATH!
In this case, you need to add PCL to environment variables manually. Refer to Add Environment Variables for instructions.
Add OpenNI2 on which PCL depends to environment variables. Refer to Add Environment Variables for instructions.
- Install HALCON
Install HALCON 20.11 or above. Please confirm that your HALCON license is still valid.
Add Environment Variables¶
If you need to use samples that depend on OpenCV or PCL, please add the relevant environment variables according to the following steps.
Right-click This PC on the desktop and select Properties.
Click Advanced system settings, and click Environment Variables in the popped up System Properties window.
Double-click Path in the user variables to enter the Edit environment variable page. Click New in the upper-right and add the following directories one by one. Then, click OK to exit the window.
For PCL: C:\Program Files\OpenNI2\Tools
For OpenCV: xxx\opencv\build\x64\vc14\bin
For OpenCV: xxx\opencv\build\x64\vc14\lib
If you encountered the error message while installing PCL, please add the following directories as well:
xxx\PCL 1.12.1\bin
xxx\PCL 1.12.1\3rdParty\VTK\bin
Hint
Please restart your computer after adding the environment variables. If not restarted, the environmental variables added to PATH may not be effective.
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.
Open CMakeLists.txt in xxx\Mech-Eye SDK-x.x.x\API\samples.
Edit lines containing options: find the lines starting 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.
Save the changes and close CMakeLists.txt.
Configure Samples in CMake¶
Right-click CMake and select Run as administrator.
Enter the directories of source code and binaries.
To build all samples at once, enter the following directories.
Where is the source code
xxx\Mech-Eye SDK-x.x.x\API\samples
Where to build the binaries
xxx\Mech-Eye SDK-x.x.x\API\samples\build
To build one sample individually, enter the following directories. Replace Category with the category name of the sample and SampleName with the name of the sample.
Where is the source code
xxx\Mech-Eye SDK-x.x.x\API\samples\Category\SampleName
Where to build the binaries
xxx\Mech-Eye SDK-x.x.x\API\samples\Category\SampleName\build
Click Configure in the bottom to open the configuration page.
Select Visual Studio version, and set the platform to x64. Then, click Finish. When the configuration completes, the log will display Configuring done.
Click Generate to generate Visual Studio solution. When the generation completes, the log will display Generating done. Then, click Open Project to open the solution in Visual Studio.
Build Samples in Visual Studio¶
In Visual Studio toolbar, change the solution configuration from Debug to Release.
In Solution Explorer, right-click Solution ‘xxx’ at the top, and select Build Solution. An EXE format executable file is generated for each sample. The executable files are saved to the Release folder, located in the Where to build the binaries directory that you entered in CMake.
Run a Sample¶
You can run the samples in Visual Studio after building them, or run the samples by double-clicking the executable files.
- Run a sample in Visual Studio
In Solution Explorer, right-click a sample, and select Set as Startup Project.
Click Local Windows Debugger in the toolbar to run 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.
If image and/or point cloud files are saved by the sample, you can find the files in the build folder (the Where to build the binaries directory that you entered in CMake).
- Run the executable file of a sample
Navigate to the Where to build the binaries directory that you entered in CMake, and open the Release folder.
Run the EXE file with the same name as 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.
If image and/or point cloud files are saved by the sample, you can find the files in the Release folder.