SDK download and compilation

This section provides guidance on setting up the development environment for building 3D vision applications, including the steps to download and compile the PercipioDC Camport SDK (hereinafter referred to as Camport SDK) on various operating systems.

Users can use the Camport SDK to obtain depth images, infrared images, color images and point clouds for applications such as navigation, obstacle avoidance, 3D modeling and gesture recognition.

Development environment for host computer

Please configure the development environment of the host computer before running or developing image application software.

Linux platform

• C++

• Python

Windows platform

• C++

• Python

• Csharp

ROS platform

• ROS

Third-party platform

• Halcon

• VisionPro

Linux platform (C++)

Linux SDK supports AArch64, ARMv7hf, RaspberryPi, i686 and x86-64 hardware platforms, and provides corresponding library files for developers to compile programs. Linux SDK does not provide executable applications, you can generate executable applications by compiling sample programs.

The following is an example of setting up the development environment for Percipio depth camera on Linux platform, using Ubuntu 18.04:

1. Downloading Camport3 SDK

2. Installing USB driver

3. Installing dependencies

4. Setting permissions

5. Compiling sample programs

6. Running

Downloading Camport3 SDK

Choose any of the following methods to download Camport3 SDK:

• Access https://github.com/percipioxyz/ using a browser and download the Camport3 SDK.

• Use the git command to obtain a local copy: Open the terminal, switch to the directory where the SDK should be stored, and enter the git clone command to clone the remote repository.

  git clone https://github.com/percipioxyz/camport3.git
  

The directory structure of Camport3 SDK is shown in the following figure:

Camport3 SDK directory structure

Doc directory

It stores the SDK API reference documentation. The documentation is a PDF file generated by Doxygen and includes descriptive information about classes, structures and interfaces.

include directory

It stores the header files used to call dynamic libraries:

• TYImageProc.h: the header file for the image post-processing function interfaces.

• TYCoordinateMapper.h: the header file for mapping of image space transformation.

• TYApi.h: the header file for configuring the depth camera and obtaining image data. Users can develop their own applications based on these APIs.

lib/linux directory

It stores library files which support the Linux operating system and are compatible with AArch64, ARMv7hf, RaspberryPi, i686 and x86-64 hardware platforms.

lib/win directory

It stores library files which support the Windows operating system and are compatible with x64 and x86 hardware platforms.

sample directory

It stores sample programs for user programming reference. For more information about the sample programs, please refer to Sample program instructions.

Installing USB driver

The Camport SDK uses LibUSB as the user-space driver library for the USB depth camera by default. LibUSB software needs to be installed before using the Percipio USB depth camera.

sudo apt-get install libusb-1.0-0-dev

Installing dependencies

CMake

CMake is a powerful, cross-platform tool tailored for software compilation. It streamlines the build process by enabling developers to define the build procedure in a platform-agnostic way through straightforward statements. CMake is capable of producing a range of makefiles or project files, facilitating the testing of C++ features supported by the compiler, akin to automake in UNIX environments. Notably, CMake’s configuration file is distinctively named CMakeLists.txt. Unlike directly assembling the final software, CMake’s primary role is to generate standardized build files, such as Makefiles for UNIX or projects/workspaces for Windows Visual C++, which are subsequently compiled using alternative tools.

The Camport SDK utilizes CMake to build standard projects. By harnessing the native build systems’ capabilities across different platforms, it can seamlessly adapt to a wide range of platform environments.

sudo apt-get install cmake

Note

Camport SDK requires users to install CMake 2.8.0 or higher versions.

OpenCV

The Camport SDK utilizes the OpenCV image processing library to render depth data transmitted from a Percipio depth camera. Prior to compiling the sample program, ensure the OpenCV image processing software library is installed.

sudo apt-get install libopencv-dev

Note

1. Camport SDK requires users to install OpenCV 2.4.8 or higher versions.

2. If the target application does not use OpenCV for image display or other image processing calculations, there is no need to install OpenCV.

Setting permissions

According to the permission management mechanism of Linux system, by default, root permission is required to access the Percipio USB depth camera. Non-root users can create a udev rule to modify the device permissions.

In the directory where the etc/udev/rules.d file is located, create a rule file with the extension .rules (such as 88-tyusb.rules), and add the user to the group specified in the file (such as: tofu). After rebooting the PC, you will have access to the USB depth camera. The content of the rule file is as follows:

SUBSYSTEM== "usb",ATTRS{idProduct}=="1003",ATTRS{idVendor}=="04b4",GROUP="tofu",MODE="0666"

Note

The beginning of the rule file name must be a number (0 ~ 99), the larger the number, the higher the priority. Accessing the Percipio network depth camera does not require root permission.

Compiling sample programs

Enter the camport3 directory and execute the following command to compile the sample programs.

sudo cp lib/linux/lib_x64/libtycam.so* /usr/lib/
cd sample
mkdir build
cd build
cmake ..
make

Several compiled executable files will be generated in the camport3/sample/build/bin directory.

Running

After connecting to the computer, the depth camera starts system initialization until the Power light on the back of the camera blinks at a frequency of 1Hz. After initialization, run the following command with root privileges to capture images.

sudo ./SimpleView_FetchFrame

Linux platform (Python)

Downloading SDK

Choose any of the following methods to download the MultiLanguage SDK:

• Download from Percipio.XYZ official website download center: https://www.percipio.xyz/downloadcenter/.

• Use the git command to obtain a local copy: Open the terminal, switch to the working directory where the SDK should be stored, and enter the git clone command to clone the remote repository.

  git clone https://github.com/alphaliang/pcammls.git
  

Sample program instructions

The sample programs are stored in the python folder in the root directory of the development package:

• framefetch.py: This sample program is used to capture depth and color images in free acquisition mode.

• frame_fetchIR.py: This sample program is used to capture IR images in free acquisition mode.

• frame_isp.py: This sample program is used to perform ISP post-processing on color images at the software level, converting RAW BAYER images with color cast into color images with standard color space.

• frame_registration.py: This sample program is used to capture images of RGB-D registration.

• frame_trigger.py: This sample program is used to set the camera to work in software trigger mode to capture depth images.

• multidevice_fetch.py: This sample program is used to set up multiple cameras for image acquisition.

• point3d_fetch.py: This sample program is used to capture 3D point clouds (not displayed). Log information displays the number of point clouds and the coordinates of the center point cloud (X, Y, Z).

Installing dependencies

Before compiling, please:

1. Install Python.

2. Open the terminal and run the following commands to install NumPy and OpenCV:

   pip install numpy
   pip install opencv-python -i https://pypi.tuna.tsinghua.edu.cn/simple
   

3. Download the SWIG source code (https://www.swig.org/download.html) to your host computer, extract it, and switch to the source code directory. Then, execute the following commands in order:

   ./configure
   make
   sudo make install
   

Compiling sample programs

To compile the sample programs, do the following:

1. Open CMakeLists.txt in the pcammls directory, modify the target language (PYTHON), and the python version.

   

2. Open the terminal in the pcammls directory and execute the following commands:

   mkdir build
   cd build
   cmake ..
   make
   sudo make install
   

   

3. Switch to the pcammls/camport3 directory and execute the following command:

   sudo cp lib/linux/lib_x64/libtycam.so* /usr/lib/
   

After compilation, switch to the /usr/local/PYTHON directory according to the interface prompt and run the generated python file.

Windows platform (C++)

Windows SDK supports X86 (32-bit) and X64 (64-bit) hardware platforms, and provides driver files for Windows 7 and above operating systems. Windows SDK includes some executable applications (such as viewing depth images) and sample programs for some applications.

The following is an example of setting up the development environment for Percipio depth camera on Windows platform, using Windows 10 64-bit system:

1. Downloading Camport3 SDK

2. Installing USB driver

3. Installing dependencies

4. Compiling sample programs

Downloading Camport3 SDK

Choose any of the following methods to download Camport3 SDK:

• Access https://github.com/percipioxyz/ using a browser and download the Camport3 SDK.

• Use the git command to obtain a local copy: Open the terminal, switch to the working directory where the SDK should be stored, and enter the git clone command to clone the remote repository.

  git clone https://github.com/percipioxyz/camport3.git
  

The directory structure of Camport3 SDK is shown in the following figure:

Camport3 SDK directory Structure

Doc directory

It stores the SDK API reference documentation. The documentation is a PDF file generated by Doxygen and includes descriptive information about classes, structures and interfaces.

include directory

It stores the header files used to call dynamic libraries:

• TYImageProc.h: the header file for the image post-processing function interfaces.

• TYCoordinateMapper.h: the header file for mapping of image space transformation.

• TY_API.h: the header file for configuring the depth camera and obtaining image data. Users can develop their own applications based on these APIs.

lib/linux directory

It stores library files which support Linux operating system and are compatible with AArch64, ARMv7hf, RaspberryPi, i686 and x86-64 hardware platforms.

lib/win directory

It stores library files which support the Windows operating system and are compatible with x64 and x86 hardware platforms.

sample directory

It stores sample programs for user programming reference. For more information about the sample programs, please refer to Sample program instructions.

Installing USB driver

1. After connecting the Percipio depth camera to a Windows PC using a USB cable, right-click on the Start in the bottom left corner of the desktop and click on Device Manager in the Start menu. In Device Manager, an unrecognized USB device PERCIPIO DEVICEEE can be found, as shown in the following image:

   

   Unrecognized USB device

2. Right-click on the device and select Update driver. Choose the driver from the lib/win/driver directory in the Camport3 SDK according to the Windows version of your PC, and follow the system prompts to complete the driver installation.

   

   Camport3 device driver

After successful installation of the driver, you can find the Percipio Device in the Device Manager.

Percipio Device

Installing dependencies

CMake

CMake is a powerful, cross-platform tool tailored for software compilation. It streamlines the build process by enabling developers to define the build procedure in a platform-agnostic way through straightforward statements. CMake is capable of producing a range of makefiles or project files, facilitating the testing of C++ features supported by the compiler, akin to automake in UNIX environments. Notably, CMake’s configuration file is distinctively named CMakeLists.txt. Unlike directly assembling the final software, CMake’s primary role is to generate standardized build files, such as Makefiles for UNIX or projects/workspaces for Windows Visual C++, which are subsequently compiled using alternative tools.

The Camport SDK utilizes CMake to build standard projects. By harnessing the native build systems’ capabilities across different platforms, it can seamlessly adapt to a wide range of platform environments.

Note

Camport SDK requires users to install CMake 2.8.0 or higher versions.

OpenCV

The Camport SDK utilizes the OpenCV image processing library to render depth data transmitted from a Percipio depth camera. Prior to compiling the sample program, ensure the OpenCV image processing software library is installed.

Note

1. Camport SDK requires users to install OpenCV 2.4.8 or higher versions.

2. If the target application does not use OpenCV for image display or other image processing calculations, there is no need to install OpenCV.

Compiling sample programs

Before compiling, please:

1. Install Visual Studio.

2. Install dependencies.

Note

When installing Visual Studio, you need to select the Visual C++ library module for installation as well, otherwise compilation will not be successful. If you do not know how to install the Visual C++ library, you can contact Percipio technical support.

To compile the sample programs, do the following:

1. Create a directory named build in the SDK sample directory.

2. Start cmake-gui.

3. Specify the source code directory as sample and the output directory for compilation as sample/build.

   

4. Click on Configure, select your version of Visual Studio, and click on Finish.

   

5. Specify the file path in the OpenCV_DIR column as opencv/build.

   

6. Configure the path of the OpenCV library in the system environment variables.

   Specific steps: Enter Environment Variables dialog box, select the “Path” column and click on Edit, and configure the path of the OpenCV library in the Edit Environment Variables dialog box.

   

7. Click on Generate.

   

8. Click on Open Project to open the project.

   

Note

Afterwards, the project can be opened with the Project.sln or ALL_BUILD.vcxproj file in the camport3/sample/build path.

9. Build Project: In the Visual Studio menu bar, click on Build> Build Solution.

   

Running

After connecting to the PC, the depth camera will start initializing until the Power light on the back of the camera flashes at a frequency of 1Hz. After successful initialization, in the Windows 10 X64 system, you can get the depth image by running the executable file lib/win/hostapp/x64/SimpleView_FetchFrame.exe in the development package. Alternatively, you can copy tycam.dll from the development package lib/win/hostapp/x64 directory to the folder sample/build/bin/Release generated by the compilation, and run SimpleView_FetchFrame.exe in the folder to capture the depth image.

Windows platform (Python)

Downloading SDK

Choose any of the following methods to download the MultiLanguage SDK:

• Download from Percipio.XYZ official website download center: https://www.percipio.xyz/downloadcenter/.

• Use the git command to obtain a local copy: Open the terminal, switch to the working directory where the SDK should be stored, and enter the git clone command to clone the remote repository.

  git clone https://github.com/alphaliang/pcammls.git
  

Sample program instructions

The sample programs are stored in the python folder in the root directory of the development package:

• framefetch.py: This sample program is used to capture depth and color images in free acquisition mode.

• frame_fetchIR.py: This sample program is used to capture IR images in free acquisition mode.

• frame_isp.py: This sample program is used to perform ISP post-processing on color images at the software level, converting RAW BAYER images with color cast into color images with standard color space.

• frame_registration.py: This sample program is used to capture images of RGB-D registration.

• frame_trigger.py: This sample program is used to set the camera to work in software trigger mode to capture depth images.

• multidevice_fetch.py: This sample program is used to set up multiple cameras for image acquisition.

• point3d_fetch.py: This sample program is used to capture 3D point clouds (not displayed). Log information displays the number of point clouds and the coordinates of the center point cloud (X, Y, Z).

Installing dependencies

Before compiling, please:

• Install Python.

• Install NumPy and OpenCV.

  pip install numpy
  pip install opencv-python -i https://pypi.tuna.tsinghua.edu.cn/simple
  

• Install SWIG (version 4.0.1 or above).

  Download link: https://www.swig.org/download.html

• Install CMake (version 3.15.0 or above).

  Download link: https://cmake.org/download/

• Install Visual Studio.

Compiling sample programs

To compile the sample programs, do the following:

1. Configure environment variables: Right-click on This PC, select Properties > Advanced system settings > Environment Variables, in the Environment Variables page, add the executable file path of the local SWIG to the system variable Path.

   

2. Open the CMakeLists.txt in the pcammls directory, and modify the target language (PYTHON), PYTHON version, and SWIG’s local path in the file as shown in the following figure:

   

3. Create a new folder in the pcammls directory and name it python_build_x64.

4. Start cmake-gui, specify the source code directory as pcammls, and specify the build output directory as pcammls/python_build_x64.

   

5. Click on Configure, select the Visual Studio version and X86/X64 version settings.

   

6. Click on Generate.

7. Click on Open Project to open the project, then select Release in the Visual Studio menu bar and click on Build > Build Solution in order.

   

After compilation, copy the generated dynamic libraries pcammls.py and _pcammls.pyd, as well as the tycam.dll, to the pcammls/python directory. Open Windows PowerShell and run the generated python file.

• pcammls.py: python_build_x64/swig/swig/_output

• _pcammls.pyd: python_build_x64/swig/Release

• tycam.dll: camport3/lib/win/hostapp/x64

Windows platform (Csharp)

Downloading SDK

Choose any of the following methods to download the MultiLanguage SDK:

• Download from Percipio.XYZ official website download center: https://www.percipio.xyz/downloadcenter/.

• Use the git command to obtain a local copy: Open the terminal, switch to the working directory where the SDK should be stored, and enter the git clone command to clone the remote repository.

  git clone https://github.com/alphaliang/pcammls.git
  

Sample program instructions

The sample programs are stored in the csharp folder in the root directory of the development package:

• fetch_frame.cs: This sample program is used to capture depth and color images in free acquisition mode.

• fetch_IR.cs: This sample program is used to capture IR images in free acquisition mode.

• fetch_isp.cs: This sample program is used to perform ISP post-processing on color images at the software level, converting RAW BAYER images with color cast into color images with standard color space.

• fetch_registration.cs: This sample program is used to capture images of RGB-D registration.

• fetch_trigger.cs: This sample program is used to set the camera to work in software trigger mode to capture depth images.

• fetch_point3d.cs: This sample program is used to capture 3D point clouds (not displayed). Log information displays the number of point clouds and the coordinates of the center point cloud (X, Y, Z).

Installing dependencies

Before compiling, please:

• Install SWIG (version 4.0.1 or above).

  Download link: https://www.swig.org/download.html

• Install CMake (version 3.15.0 or above).

  Download link: https://cmake.org/download/

• Install Visual Studio and .NET components.

Compiling sample programs

To compile the sample programs, do the following:

1. Configure environment variables: Right-click on This PC, select Properties > Advanced system settings > Environment Variables, in the Environment Variables page, add the executable file path of the local SWIG to the system variable Path.

   

2. Open the CMakeLists.txt in the pcammls directory, modify the target language (CSHARP), the installed version of .NET Framework on your host computer, and the local path of SWIG.

   

3. Create a new folder in the pcammls directory and name it csharp_build_x64.

4. Start cmake-gui, specify the source code directory as pcammls, and specify the build output directory as pcammls/csharp_build_x64.

   

5. Click on Configure, select the Visual Studio version and X86/X64 version settings.

   

6. Click on Generate.

7. Click on Open Project to open the project, then select “Release” in the Visual Studio menu bar and click on Build > Build Solution in order.

   Note

   After modifying the source code, you need to rebuild the executable files by selecting “Release” in the Visual Studio menu bar and then click on Build > Rebuild Solution.

   

After compilation, copy the dynamic library tycam.dll in the camport3/lib/win/hostapp/x64 directory to the pcammls/csharp_build_x64/Bin/Release directory, open Windows PowerShell, and run the generated executable files.

ROS platform

ROS (Robot Operating System, hereinafter referred to as ROS) is an open-source meta-operating system suitable for robots. It provides the services that an operating system should have, including hardware abstraction, underlying device control, implementation of common functions, inter-process messaging, and package management.

Setting up ROS development environment

Install the corresponding ROS development platform according to the Ubuntu version.

• Ubuntu16.04: ROS Kinetic

• Ubuntu18.04: ROS Melodic

• Ubuntu20.04: ROS Noetic

Downloading Camport ROS SDK

ROS SDK supports the ROS Kinetic, ROS Melodic and ROS Noetic platforms.

Choose any of the following methods to download the Camport ROS SDK:

• Access https://github.com/percipioxyz/ using a browser and download the Camport ROS SDK.

• Use the git command to obtain a local copy: Open the terminal, switch to the working directory where the SDK should be stored, and enter the git clone command to clone the remote repository.

  git clone https://github.com/percipioxyz/camport_ros.git
  

The directory of Camport ROS SDK is shown in the following figure:

Camport ROS SDK directory

• percipio_camera: includes source files and configuration files.

• percipio_launch: launch package.

Compiling sample programs

To compile the sample programs, execute the following command in the root directory of the development package:

catkin_make

Tip

If the catkin command is not installed, you need to install catkin first.

After compilation, the build folder (containing intermediate files) and the devel folder (containing header files, dynamic/static libraries and executable files) will be generated.

Configuring environment variables

To configure the environment variables, execute the following command in the root directory of the development package:

echo "source <the root directory of the development package>/camport_ros/devel/setup.bash" >> ~/.bashrc

Modifying Launch Configuration

To configure the parameters loaded when the camera starts in the percipio.launch file, do the following:

1. Execute the following command to open the percipio.launch file:

cd src/percipio_launch/launch/
gedit percipio.launch

2. Modify the configuration as needed.

• Specify camera SN in default:

<arg name="device_id" default="207000106930" />

Tip

The device_id is set to #1 by default, which means the first camera found will be opened by default.

• Set the switch for exposure synchronization of left and right infrared images in the default:

<arg name="color_depth_synchronization" default="true" />

• Set the switch for alignment of depth and color images in the default:

<arg name="depth_registration" default="true" />

Note

This enable switch will only take effect when the color image and the depth image are both captured. This setting is invalid for cameras without RGB modules.

Modifying Percipio.cfg configuration

The parameters in the Percipio.cfg file support dynamic adjustment. After modifying the maximum and minimum values of the Percipio.cfg parameters, refer to the running section to bring up the rqt_reconfigure_Param page and make adjustments.

1. Execute the following command in the root directory of the software package to open the Percipio.cfg file.

   cd src/percipio_camera/cfg/
   gedit Percipio.cfg
   

   

2. Set the minimum and maximum values for the parameters in gen.add().

   Tip

   1. gen.add(name, type, level, description, default, min, max) represents the feature name, type, level, description, default value, minimum value, and maximum value.

   2. Boolean values must be written as True or False (with the first letter capitalized).

   Note

   1. If you don’t know the minimum and maximum values of camera features, you can view the supported components and features of the camera by one of the following steps:

      • Run the SDK sample program DumpAllFeatures to view the components and features supported by the camera in the listed information.

      • Run the SDK sample program DumpAllFeatures -d and check the supported components and features of the camera in the generated fetch_config.xml file.

   2. The setting range of the following parameters can be customized:

      • depth_speckle_filter: Speckle filter switch. Speckle filtering is used to filter out small speckle noise in the depth image.

      • max_speckle_size: The maximum size of speckle noise. Speckles larger than this setting are considered not to be noise. It is recommended to set the range between [10, 3000].

      • max_speckle_diff: The maximum depth difference between adjacent pixels in the same speckle. If the depth difference between adjacent pixels is greater than this set value, then those adjacent pixels are considered to belong to two different speckles. It is recommended to set the range between [10, 1500].

      • data_skip: Frame skipping. For example, if the publishing node of Percipio is actually 30fps, but the receiving node of ROS only wants to receive 10fps, you can set data_skip to 3. It is recommended to set the range between [0,20].

      • z_scaling: the depth value unit of the pixel in the depth image. It is recommended to set the range to [0,8].

      • use_device_time: Default setting is True, indicating the use of the camera’s internal timestamp; when set to False, it indicates the use of ROS timestamp.

3. Execute the following commands to recompile. After compilation, the changes made to Percipio.cfg will take effect.

   catkin_make
   

Subscribing

Execute the following command in the root directory of the development package to subscribe to the service:

roslaunch percipio_launch percipio.launch

Note

During operation, please do not close this service terminal.

Running

1. Open a new terminal and execute the following command to run RViz:

   rosrun rviz rviz
   

2. Add image display.

   1. In the left side of the page, in the Global Options settings, set “Fixed Frame” to “camera_depth_frame”.

      

   2. Add depth image display.

      1. Click on add, add “Camera”, name it “Depth Camera”.

         

      2. In the newly added Depth Camera settings on the left side of the page, set “Image Topic” to “/camera/depth/image”.

         

   3. Add color image display.

      1. Click on add, add “Camera”, and name it “Color Camera”.

      2. Check the newly added Color Camera on the left side of the page and set the “Image Topic” to “/camera/rgb/image_raw” in the settings.

   4. Add IR image display.

      1. Click on add, add “Image”, name it “IR Camera”.

      2. Check the newly added IR Camera on the left side of the page and set the “Image Topic” to “/camera/ir/image” in the settings.

   5. Add point cloud display.

      1. Click on add, add “DepthCloud”, name it “Point Cloud”.

      2. Check the newly added Point Cloud on the left side of the page and set the “Depth Map Topic” to “/camera/depth/image”.

3. According to the imaging situation, dynamically adjust the camera parameters.

   Execute the following command to bring up the rqt_reconfigure_Param page. Select the driver and adjust the parameters on the page.

   rosrun rqt_reconfigure  rqt_reconfigure
   

   

Solution for multi-device simultaneous access

1. Edit .launch file.

   Refer to the percipio.launch document to create multiple .launch. Configure “camera” and “device_id” with different values in each .launch file. For example, to run two devices simultaneously, create two .launch files, namely percipio_camera1.launch and percipio_camera2.launch.

   percipio_camera1.launch contains the following content:

   <arg name="camera" default="camera1">
   ......
   <arg name="device_id" default="207000010443">
   ......
   

   percipio_camera2.launch contains the following content:

   <arg name="camera" default="camera2">
   ......
   <arg name="device_id" default="207000010113">
   ......
   

2. Execute the following command in the root directory of the development package to reconfigure the environment variables:

   source ./devel/setup.bash
   

3. Open the device with serial number 207000010443 by running the command roslaunch percipio_launch percipio_camera1.launch.

   Open the device with serial number 207000010113 by running the command roslaunch percipio_launch percipio_camera2.launch.

Third-party platform (Halcon)

Downloading and installing Halcon

Download the Halcon (Windows version) installation package from the Halcon official website (https://www.mvtec.com/downloads) and install Halcon according to the official documentation.

Important

The installation package Image Acquisition Interfaces must be installed. If there are no special requirements, it is recommended to check all installation packages and install them.

Downloading SDK

Note

• If the Halcon version is 18.11.04.0 or above, please follow the steps below to download the Camport3_Halcon_gentl SDK.

• If the Halcon version is lower than 18.11.04.0, please go to the official GitHub page of Percipio to download the Camport3_Halcon SDK. This section does not introduce the usage of the SDK. If you have any questions, please contact Percipio technical support.

Choose any of the following methods to download the Camport3_Halcon_gentl SDK:

• Download from the official GitHub page of Percipio: https://github.com/percipioxyz/.

• Use the git command to obtain a local copy: Open the terminal, switch to the working directory where the SDK should be stored, and enter the git clone command to clone the remote repository.

  git clone https://github.com/percipioxyz/camport3_halcon_gentl.git
  

Camport3_Halcon_gentl SDK directory structure is shown in the following figure:

Camport3_Halcon_gentl SDK directory

Samples directory

It stores sample programs for user programming reference.

• check_status.hdev: This sample program is used to display the status of the camera connection.

• fetchframe.hdev: This sample program is used to capture image data from one depth camera.

• fetchframe_2cameras.hdev: This sample program is used to simultaneously capture images with two depth cameras and output image data.

• fetchframe_p3d.hdev: This sample program is used to capture 3D point clouds.

• genicamtl_parameters.hdev: This sample program is used to enumerate the parameters supported by Percipio.

• triggermode1.hdev: This sample program is used to set the depth camera to work in mode 1. The camera captures images and outputs image data when it receives a software trigger command or a hardware trigger signal.

Others

The samples directory also includes:

• percipio.cti: The implementation file of GenTL Producer.

• tycam.dll: The dynamic link library of Percipio SDK, which is a dependency for GenTL Producer.

• README.md: The README documentation.

Configuring environment variables

Enter the environment variables page and create a new environment variable. The variable name is GENICAM_GENTL64_PATH, and the variable value is the storage path of percipio.cti, which is the Camport3_Halcon_gentl SDK folder path. After rebooting the computer, the configuration will take effect.

Configure environment variables

Running

Take the camera with serial number 207000144850 as an example to explain how to run the camera in Halcon. The steps are as follows:

1. To find the camera, enter the following code in the program window and run it.

   info_framegrabber ('GenICamTL', 'info_boards', BoardInfo, BoardInfoValues)
   

   

   BoardInfoValues will display all discoverable devices.

2. To open the camera and capture the image, enter the following code in the program window and run it.

   Here ‘PercipioTL_DEV_207000144850’ is provided as an example, please replace it with the target camera before running.

   open_framegrabber ('GenICamTL', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1, 'false', 'default', 'PercipioTL_DEV_207000144850', 0, -1, AcqHandle)
   set_framegrabber_param(AcqHandle, 'SourceSelector', 'Source_Color')
   set_framegrabber_param(AcqHandle, 'SourceMode', 'On')
   set_framegrabber_param(AcqHandle, 'SourceSelector', 'Source_Depth')
   set_framegrabber_param(AcqHandle, 'SourceMode', 'Off')
   grab_data_async(Image, Region, Contours, AcqHandle, -1, Data)
   

   

   AcqHandle displays the obtained handle. The Image variable and the graphic window display the captured color image.

3. The sample code of reading and writing parameters according to the camera features is as follows. For more information about camera features, please refer to Viewing camera features.

   get_framegrabber_param(AcqHandle, 'ImageMode_values', ImageModeValues)
   set_framegrabber_param(AcqHandle, 'ImageMode', ImageModeValues[0])
   

Viewing camera features

1. Double-click on the genicamtl_parameters.hdev file under the samples path.

2. Modify the serial number of the camera to be opened in the program window, and click on the run button.

   Here, ‘PercipioTL_DEV_207000144850’ is provided as an example, please replace it with the target camera before running.

   open_framegrabber ('GenICamTL', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1, 'false', 'default', 'PercipioTL_DEV_207000144850', 0, -1, AcqHandle)
   

   

   The parameter file parameters_info.dat will be generated in the same directory as the genicamtl_parameters.hdev file.

   

3. Open the parameters_info.dat file, and view the list of supported features for the camera.

   

Tip

parameters_info.dat File Description

Structure: Parameter Name + <Prefix> + Current Value + [Parameter Range]

Third-party platform (VisionPro)

Downloading and installing VisionPro

Please download VisionPro from Cognex official website (https://www.cognex.cn/zh-cn/products/machine-vision/vision-software/visionpro-software).

Note

Percipio has tested VisionPro 9.0 and confirmed that it can open the Percipio camera normally. It is recommended to use this tested version of VisionPro.

Downloading VisionPro SDK

Please download the Percipio VisionPro SDK from Percipio official website download center (https://www.percipio.xyz/downloadcenter/).

The directory structure of VisionPro SDK is shown in the following figure:

VisionPro SDK directory

Configuring environment

1. Right-click on the VisionPro shortcut icon and select “Open file location” from the shortcut menu to access the installation directory of VisionPro.

2. Copy PercipioCamera.dll, PercipioCameraExtern.dll, tycam.dll and opencv_world460.dll to bin folder in the VisionPro installation directory.

3. Copy PercipioCameraToolBlock.vtt to bin/Templates/Tools folder in the VisionPro installation directory.

Running

This section mainly introduces how to run the Percipio camera in VisionPro. The steps are as follows:

1. Double-click to run the VisionPro software.

2. Double-click on “Image Source” to enter VisionPro(R) QuickBuild Job Editor - CogJob1 page.

   

3. Click on the “Show VisionPro Tools” icon to bring up the VisionPro Tools page.

   

4. Double-click on “PercipioCameraToolBlock” and add it to the ToolGroup.

   

5. Double-click on “PercipioCameraToolBlock”, select the “Input/Output” tab in the PercipioCameraToolBlock page, and set the input parameters.

   

   • CameraId: Set camera serial number.

   • Z: Set the distance between the camera and the projection plane in the Z direction, in millimeters. Perform an orthogonal projection of the depth image onto this projection plane. With the camera field of view at this distance and the depth image resolution, the size of a single pixel (in millimeters) can be calculated for subsequent calculations.

   • ScaleUnit: Set the ScaleUnit feature of the camera to output depth values with different precisions.

   • RegistrationMode: Set the RGBD registration switch. 0: no registration; 1: rgb2depth; 2: depth2rgb.

6. Click on the “Run” icon. You can view the images captured by the camera in the output terminal.

   

   Afterwards, add other tools according to actual needs, and connect the output port of PercipioCameraToolBlock to the input port of other tools.

7. Optional: If you have secondary development needs for PercipioCameraToolBlock, you can click on the “Create/Edit Script” icon and edit the script.

   

Cross-compilation development environment for host computer and camera

Percipio network cameras support to run the customized embedded applications within the camera, and allow users to fully utilize their internal computational resources for image pre-processing or application logic processing. For specific camera models that support embedded applications, please consult Percipio technical support. .. Percipio network cameras allow users to fully utilize their internal computational resources for image pre-processing or application logic processing.

Note

USB depth cameras do not support users running embedded applications within the camera.

Compiling sample programs

1. Download Camport SOC SDK, link: https://github.com/percipioxyz/camport3_soc.git

2. Execute ./build.sh in the SDK root directory. After execution is complete, you will find the generated executable file RawFetchFrame in the ./build/bin directory.

3. Copy the executable file to the camera’s user application folder using scp or sftp. Please refer to Installation of programs and library files.

Compiling user programs

1. Refer to the SDK’s ./Sample/RawFetchFrame, develop the application after creating a user program directory in the Sample directory.

2. Modify ./Sample/CMakeLists.txt, add the user program directory path in ALL_SAMPLES.

3. Execute ./build.sh, after execution is completed, an executable file will be generated in the ./build/bin directory.

4. Copy the executable file to the user application folder of the camera using scp or sftp , please refer to Installation of programs and library files.

Compiling programs using Opencv

1. Refer to the SDK’s ./Sample/RawFetchFrame, develop the application after creating a program directory using OpenCV in the Sample directory.

2. Modify ./Sample/CMakeLists.txt, add the program directory path that uses OpenCV in ALL_SAMPLES.

3. Execute ./build.sh opencv, after execution is completed, an executable file will be generated in the ./build/bin directory.

4. Copy the executable file to the user application folder of the camera using scp or sftp . At the same time, copy the required OpenCV library to the camera. The OpenCV library is located in the ./ThirdPartyLib/Opencv-3.4/lib directory. Please refer to Installation of programs and library files.

Installing programs and library files

1. Using scp or sftp command, copy the files that need to be installed to the camera’s /mnt/ram directory:

   scp ur_FILES percipio@XXX.XXX.XXX.XXX:/mnt/ram
   

2. Use putty or other terminals to remotely log in to the camera:

   ssh percipio@XXX.XXX.XXX.XXX
   

3. Extract the compressed file inside the camera, and copy the executable file and shared libraries to the corresponding directory under /usr/local :

   cd /mnt/ram
   cp ur_ELFS_FILENNAME /usr/local/bin
   cp ur_lib*.so /usr/local/lib/
   cp ur*config /usr/local/etc
   

4. Execute the sync command to permanently save the modifications to the flash.

Note

1. The copying process is divided into two steps. First, it is necessary to copy to the /mnt/ram directory to prevent errors due to insufficient file system space during the decompression process if the application is a compressed package.

2. When there are few files, you can choose not to use compressed files. However, when there are many files, it is recommended to pack them and then copy them to the camera for decompression. Currently, the camera supports several types of compressed files: tar, tar.gz, tar.bz2, and unencrypted zip files. They can be decompressed using the following commands: tar -xvf, tar -xzvf, tar -xjvf and unzip.

3. The maximum storage capacity for the user’s secondary development directory /usr/local is 25MB.

4. After decompressing the file, be sure to copy it to the user directory, otherwise the content in /mnt/ram will be lost after rebooting.

5. The library file libtycam.so used in development is already included in the camera file system, so users do not need to copy it again to /usr/local/lib.

6. Users need to use the command chmod a+x ELFS_FILENNAME to grant execution permissions to applications or scripts.

7. XXX.XXX.XXX.XXX is the IP address of the target camera.

Setting program to start up on boot

1. Login camera

   ssh percipio@XXX.XXX.XXX.XXX
   

2. Modify the startup script

   vi /usr/local/etc/start_app.sh
   
   1 #!/bin/bash
   2 # Created By:      Leon Zhou
   3 # Created Time:    2019-04-26 20:29:12
   4 # Modified Time:   2019-04-26 20:33:22
   5 export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib/
   6 export PATH=$PATH:/usr/local/sbin:/usr/sbin:/sbin
   7
   8 #Add your app start command below
   

   Add the startup command for your app on line 8, for example:

   1 #!/bin/bash
   2 # Created By:      Leon Zhou
   3 # Created Time:    2019-04-26 20:29:12
   4 # Modified Time:   2019-04-26 20:33:22
   5 export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib/
   6 export PATH=$PATH:/usr/local/sbin:/usr/sbin:/sbin
   7
   8 #Add your app start command below
   9 /usr/loca/bin/your_app
   

3. Execute the sync command in the console to write to the storage system and reboot the device.

Warning

1. If a reboot of gevcam is required during the debugging process, you need to run killall percipio_gev_disd.

2. Do not add statements like reboot in the startup script!

Network Configuration

1. IP settings

   By default, the system uses DHCP mode to obtain an IP address dynamically.

   • Static IP settings

     Log in to the camera to execute the instructions below, or modify the configuration file below in the application or script to configure the IP. It is not recommended to use ifconfig or other methods to directly modify the IP to avoid confusion in camera IP management. After modifying the configuration file using this method, it will be permanently stored in the camera and take effect after rebooting.

     echo "your_ip" > /etc/device_ip
     echo "your_gw" > /etc/device_gw
     echo "your_netmask" > /etc/device_netmask
     

   • Dynamic IP settings

   echo "" > /etc/device_ip
   echo "" > /etc/device_gw
   echo "" > /etc/device_netmask
   

   Warning

   1. Please be cautious when modifying the IP address, subnet mask, and gateway; setting incorrect values may result in being unable to connect to the camera.

   2. Be sure to execute the sync command in the console to write the changes to the storage system and reboot the device.

2. NTP server configuration

   Tip

   Before configuring the NTP server, you need to set the camera’s time synchronization method to NTP time synchronization. For more details, please refer to Time synchronization settings.

   The camera supports NTP time synchronization and the default NTP servers used are: ‘cn.ntp.org.cn’, ‘0.ubuntu.pool.ntp.org’, ‘1.ubuntu.pool.ntp.org’.

   If the user has set up an NTP server, they can execute the following command to add the IP or domain name of the NTP server in /etc/ntp_server :

   echo your_ntp_server > /etc/ntp_server