Operation Guides

This section covers how to use Percipio Viewer:

1. Launch Software

2. Set Camera IP

3. Run the Camera

4. Capture and View Data

5. View and Adjust Views

6. Adjust Parameters

7. Save Data

Before using Percipio Viewer:

1. Connect the Percipio camera to the host computer. For connection details, see Hardware Connections.

2. If you are using a USB camera for the first time, complete the following steps:

   • Windows: Visit the Percipio Download Center to download the Camport4 SDK and install the driver. For installation instructions, see Install USB Driver.

   • Linux: See Installing USB driver and Setting permissions to complete the required configuration.

Launch Software

For the current Viewer package and installation files, see Download, Install, and Uninstall. Follow the steps below to launch it after installation or extraction:

Windows Version

After extracting the files, double-click percipio-viewer.x.x.x.exe to launch the software.

Linux Version (Ubuntu)

1. After extracting, open a terminal and enter sudo chmod +x percipio-viewer.x.x.x to add executable permissions.

   

2. Double-click percipio-viewer.x.x.x or enter the run command sudo ./percipio-viewer.x.x.x in the terminal.

   

Set Camera IP

To ensure that the Percipio Viewer can successfully open the camera, it is recommended to first check the IP address of the camera and make sure it is in the same network segment as the IP address of the host computer. The Percipio Viewer supports modifying the IP address of the network camera to a static or dynamic IP address.

Prerequisites

1. The Percipio Viewer has not opened any camera.

2. Before setting a static IP address, ensure that the IP address of the host computer is in the target network segment.

Operation Steps

1. Click Tools ‣ IP setting in the menu bar to enter the Device IP Settings page.

   

   Device IP Settings Page

2. Optional step: If the target camera is not found in the camera list, click Refresh to refresh the camera list.

3. Depending on the camera enumeration situation, choose one of the following methods to set the IP:

   If the target camera is found in the list:

   1. Click the target camera in the list to open the settings page.

   2. Fill in the camera IP address in the Device target ip field, the default gateway in the Device target gate, and the subnet mask in the Device target mask.

      Leaving the Device target ip field blank means setting the current camera to a dynamic IP address, while filling it means setting it to a static IP address.

   3. Click Accept.

   If the target camera cannot be found in the list:

   1. Click Advanced to enter the settings page.

   2. Select the network card to which the camera is connected in the Net interface list field.

   3. Fill in camera MAC address in the Device mac addr field. The MAC address is obtained from the label on the camera body.

   4. Fill in the camera IP address in the Device target ip field, the default gateway in the Device target gate field, and the subnet mask in the Device target mask.

      Leaving the Device target ip field blank will set the current camera to use a dynamic IP address. Filling in this field will set the camera to use a static IP address.

   5. Click Accept.

4. Check the Log display area:

   • If “Device IP setting is successful.” is displayed, it indicates the IP setting is successful.

   • If “Device IP setting failed.” is displayed, it indicates the IP setting has failed. Please check the computer network configuration, hardware wiring, and whether the parameters filled in on the Device IP Settings page are correct.

Run the camera

The Percipio Viewer only supports retrieving cameras via Ethernet. Starting from version V1.2.3, the Percipio Viewer will not automatically open the camera after startup and needs to be manually selected and opened.

Operation Steps

Take a camera with the serial number 207000128018 as an example:

1. After the camera initialization is completed, click Preferences, and then click Refresh Source in the drop-down menu to refresh the device list.

2. Select the serial number 207000128018 of the target camera in the device list.

   

   Note

   If the camera status code and firmware error code (such as -1005, 0x00000000) are displayed after the serial number in the device list, it indicates that the camera cannot be opened normally. See Error Codes for troubleshooting.

Capture and View Data

Capture Images

Percipio Viewer supports the following ways of capturing images:

• Trigger Off (Continuous Capture Mode): The camera continuously captures images at the highest frame rate.

• HW Trigger (Hardware Trigger Mode): The camera captures images according to the trigger signal frequency of the externally connected hard trigger signal source.

• SW Trigger(continue) (Continuous Software Trigger Mode): The camera continuously receives software trigger signals and captures images.

• SW Trigger(single) (Single-frame Software Trigger Mode): The camera captures one frame of image upon receiving a software trigger signal once.

Trigger OffHW TriggerSW Trigger (continue)SW Trigger (single)

Operation Steps

1. When all data streams are in the state, expand the Device > Controls parameter page and set TriggerMode to Trigger Off.

2. Turn on the data stream, and you can preview the images in real-time.

   The name, resolution, and frame rate of the current image are displayed in the title bar above the image.

   

   Preview Image in Continuous Capture Mode

View Images and Adjust Views

1. Check the view

   DepthColorGrayscalePoint cloudRGB-DColor 3D

   Turn on the Depth Stream, and you can view the depth map in the 2D view.

   

   Depth Map

2. Adjust the view according to requirements:

   • Zoom the image: Place the mouse on the 2D/3D map and roll the mouse wheel.

   • Pan the image (only supported in 3D/Color 3D views): Hold down the mouse wheel and drag.

   • Rotate the image (only supported in 3D/Color 3D views): Hold down the left mouse button and drag.

   • Reset the view (only supported in 3D/Color 3D views): Click .

   • Pause the real-time image display: Press the Space key on the keyboard to pause the real-time image display.

   A pause icon will appear in the image display area. Press the Space key again or switch the view, and the pause icon will disappear, and the image will be displayed in real-time.

   

   Pause Image Display

   • Press the W, S, A, and D keys to zoom in, zoom out, and move the view left or right.

Adjust Point Cloud Rendering

In the 3D or Color 3D view, use the mouse wheel to zoom, hold the mouse wheel to pan, and hold the left mouse button to rotate the point cloud. Click to restore the default viewpoint.

Adjust Depth Rendering

In the Depth or RGB-D view, depth rendering updates in real time when you adjust the display-related parameters in the control panel. Use the rendered view for visual inspection and the unrendered output when you need the original depth values for analysis or export.

Adjust Parameters

Notes on Parameter Adjustment

1. Different camera models support different attributes, so the parameters displayed in the Percipio Viewer interface will also change accordingly.

   Note

   If you want to query all the components and attributes supported by a specified camera, you can generate a fetch_config.xml file for the camera, which lists detailed information. The operation steps are below:

   1. Create a new .xml file named “fetch_config”.

   2. Place the .xml file in the same directory level as the Percipio Viewer software.

   3. After opening the software and selecting the camera, the system will automatically generate the corresponding fetch_config.xml file for the camera.

2. When the data stream is in the state, some parameters will be grayed out, which means these parameters can only be modified when all data streams are in the state.

   

3. For the adjustment instructions of each parameter, see Parameter Descriptions.

Select the API Level

Parameters in Percipio Viewer are grouped into three API levels: Beginner, Expert, and Guru.

Click > API level in the drop-down menu to set the API level.

API Level Settings

Different API level settings display different parameters.

• The Beginner level contains the most commonly used basic parameters.

• The Expert level contains all the parameters of the Beginner level and also supports SGBM parameters.

• The Guru level contains all the parameters of the Beginner level and also supports SGBM parameters.

In most cases, Beginner-level parameters are sufficient. If data quality is still not satisfactory, you can adjust Expert/Guru-level SGBM parameters.

Manage Parameter Configuration

• Save Parameter Configuration

• Load Parameter Configuration

• Copy Parameter Configuration

• Clear Parameter Configuration from the camera storage area

Additionally, the Percipio Viewer also supports Automatically Load Storage Parameter Configuration.

Save Parameter Configuration

The Percipio Viewer supports saving the adjusted camera properties (parameters in the Controls category and image resolution) to a local .json file or writing them to the camera’s Storage area, so that this set of parameter configurations is directly loaded when using the camera later.

Operation Steps

1. Run the target camera.

2. Adjust the camera properties as needed to achieve the best imaging effect. Camera properties include parameters in the Controls category and image resolution.

   

   Save Parameter Settings

3. Click Tools > Parameters in the menu bar to enter the Camera parameters configuration page.

   

   Camera Parameters Configuration Page

4. Perform the saving operation:

   • If you want to save the parameter configuration to the camera’s Storage area, select Storage in the Target field and click Save.

   • If you want to save the parameter configuration to a local file, select Local file in the Target field, click Save, set the .json file name, and click Save.

5. Check the Log display area. If “The operation was successfully completed.” is displayed, it indicates the parameter configuration has been successfully saved.

Note

Please remember to turn all data streams to before you save the parameter configuration.

Follow-up Operations

If you want to automatically load the parameter configuration saved in the camera’s Storage area when opening the camera in Percipio Viewer, enable Auto-Load. For steps, see Automatically Load Storage Parameter Configuration.

Load Parameter Configuration

1. Run the target camera.

2. Click Tools > Parameters in the menu bar to enter the Camera parameters configuration page.

3. Perform the loading operation:

   • If you want to load the parameter configuration from the camera’s Storage area, select Storage in the Source field and click Load.

   • If you want to load the parameter configuration from a local file, select Local file in the Source field, click Load, specify the local .json file, and click Open.

4. Check the Log display area:

   • If “The operation was successfully completed.” is displayed, it indicates the parameter configuration has been successfully loaded.

   • If “Check code is invalid, maybe the data in the storage area is empty.” is displayed, it indicates there is no saved parameter configuration in the camera’s Storage area, and the loading has failed.

Copy Parameter Configuration

1. Run the target camera.

2. Click Tools > Parameters in the menu bar to enter the Camera parameters configuration page.

3. Perform the copying operation:

   • If you want to copy the parameter configuration from the camera’s Storage area to a local file, select Storage To Local file in the Direction field, click Copy, set the .json file name, and click Save.

   • If you want to copy the parameter configuration from a local file to the camera’s Storage area, select Local file To Storage in the Direction field, click Copy, specify the local .json file, and click Open.

4. Check the Log display area. If “The operation was successfully completed.” is displayed, it indicates the parameter configuration has been successfully copied.

Clear Camera Storage Parameter Configuration

1. Run the target camera.

2. Click Tools > Parameters in the menu bar to enter the Camera parameters configuration page.

3. Click Erase camera storage data to clear all the data in the current camera’s Storage area.

4. Check the Log display area. If “The operation was successfully completed.” is displayed, it indicates the clearing has been successful.

Automatically Load Storage Parameter Configuration

Percipio Viewer supports automatically loading the parameter configuration in the camera’s Storage area after opening the camera.

Click Settings > Auto-Load in the menu bar. A check mark indicates this function is enabled.

Enable the Auto-Load Function

Verification

1. Click Preferences, select the camera SN number, and open the camera.

2. Check the Log display area:

   • If “Loading configuration parameters completed.” is displayed, it indicates the parameter configuration in the camera’s Storage area has been successfully loaded.

   • If “Check code is invalid, maybe the data in the storage area is empty.” is displayed, it indicates there is no saved parameter configuration in the camera’s Storage area, and loading failed.

Save Data

• Save a Single Image

• Continuously Save Images

• Record Videos

Save a Single Image

Operation Steps

• Switch to the 2D view, click , select the save path, and click Save.

• Switch to the 3D/Color 3D view, click , select the file format (supporting “.xyz” and “.ply” formats) for exporting the 3D point cloud map and the save path, and click Save.

Note

Image files are saved in the C drive by default. If they cannot be saved to the default path, see Unable to save the file to the C drive, what should I do?.

Continuously Save Images

Percipio Viewer supports continuously saving images according to the preset number of frames. The supported image types include depth maps, color maps, left and right grayscale maps, aligned maps of depth maps mapped to color maps, aligned maps of color maps mapped to depth maps, point cloud maps, point cloud maps generated after aligning depth and color.

Prerequisites

According to the type of images to be saved, turn on the corresponding data streams. The correspondence between image types and data streams is shown in the following table.

Table of Correspondence between Image Types, Data Streams, and File Formats

Image Type	Data Stream	Content and File Format of Continuously Saved Images
Depth	Depth Stream	Rendered depth map, file name format: depth_time_index-numer.jpg. Unrendered depth map, file name format: depth_time_index-numer.png.
Color	Color Stream	color image, file name format: color_time_index-numer.png.
Left-IR	Left IR Stream	Left grayscale image, file name format: leftIR_time_index-numer.png.
Right-IR	Right IR Stream	Right grayscale image, file name format: rightIR_time_index-numer.png.
Point3D	Depth Stream	Original point cloud data, file name format: Point3D_time_index-numer.xyz.
RGB2D	Depth Stream + Color Stream	Aligned map of color image and depth map, file name format: RGB2D_time_index-numer.png.
D2RGB	Depth Stream + Color Stream	Rendered aligned map of depth map and color image, file name format: D2RGB_time_index-numer.jpg. Unrendered aligned map of depth map and color image, file name format: D2RGB_time_index-numer.png. Distortion-corrected color image, file name format: undistort_color_time_index-numer.png.
Color3D	Depth Stream + Color Stream	Note When saving Color3D, in addition to enabling the Depth Stream and Color Stream, you must also select either D2RGB or RGB2D before selecting Color3D and starting continuous image saving. D2RGB+Color3D Color point cloud map aligned with color, file name format: Color3D(map_to_color)_time_index-numer.xyz. Rendered aligned map of depth map and color image, file name format: D2RGB_time_index-numer.jpg. Unrendered aligned map of depth map and color image, file name format: D2RGB_time_index-numer.png. Distortion-corrected color image, file name format: undistort_color_time_index-numer.png. RGB2D+Color3D Color point cloud map aligned with depth, file name format: Color3D_time_index-numer.xyz. Aligned map of color image and depth map, file name format: RGB2D_time_index-numer.png. Distortion-corrected color image, file name format: undistort_color_time_index-numer.png.

Operation Steps

1. Click , and the parameter setting interface will appear.

   

   Record Parameter Setting Interface

2. Select the save Type to Images.

3. Set the frame cnt parameter, that is, the number of images to be saved.

4. Select the types of images to be saved, supporting single selection or multiple combined selections.

   

   Selecting Image Types

5. Click on the right side of “Path”, and select the image save path.

6. Click Save to start continuously saving images.

   

   Continuous_Save Saving Process

   After saving the specified number of images, the continuous image-saving operation will stop automatically. If you need to stop the saving operation during the process, click .

Record Videos

Percipio Viewer supports recording videos when the camera is capturing images. During recording, some parameters can be adjusted, but opening or closing data streams is not supported.

Prerequisites

Turn on the corresponding data streams according to the recording content.

Operation Steps

1.Click , and the parameter setting interface will appear.

Record Parameter Setting Interface

2. Select Bag for the “Save type” Type.

3. Click the on the right side of “Path” to select the video save path.

   The file name of the .bag file is the default timestamp and cannot be modified.

4. Click Save to start recording.

5. Click to end the recording.

If you need to play back the recorded video, click Preferences, click Load Recorded Sequence in the dropdown menu, and select the target .bag file.

Video Playback