Operation Guides

The following section mainly introduces the usage of Percipio Viewer:

1. Set Camera IP

2. Run the Camera

3. Capture and View Data

4. View and Adjust Views

5. Adjust Parameters

6. Save Data

Before Using Percipio Viewer, Please:

1. Download Percipio Viewer from Percipio Official Website Download Section. After extracting the files, you will get percipio-viewer.X.X.X.exe.

2. Connect the Percipio camera to the host computer. For connection methods, please refer to Hardware Connections.

3. If you are using a USB camera for the first time, please complete the following operations:

   • Windows: Download and install the driver from Percipio Official Website Download Section. For installation instructions, please refer to Installing USB driver.

   • Linux: Please refer to Installing USB driver and Setting permissions to complete the relevant configurations.

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 can be found in the list:

   1. Click on the target camera in the list to enter 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 can be 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. Please refer to Error Codes to troubleshoot the problem.

Capture and View Data

Capture Images

Percipio Viewer supports the following ways of capturing images:

• Trigger Off (Free 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 can be viewed in the title bar above the image.

   

   Preview Image in Free Capture Mode

View 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 Stream

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 、 D keys on the keyboard respectively to zoom in, zoom out, and move the 3D/Color 3D view left and right.

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 as follows:

   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, please refer to Parameter Descriptions.

Select the API Level

The parameters in the Percipio Viewer are divided 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 provides SGBM parameters.

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

Typically, adjusting the Beginner-level parameters can fulfill the requirements. If the data quality is still not satisfactory, you can adjust the 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

In addition, 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 can be 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 strems to before you save the parameter configuration.

Follow-up Operations

If you need to automatically load the parameter configuration saved in the camera’s Storage area when opening the camera in the Percipio Viewer, please enable the Auto-Load function. For specific operation steps, please refer to 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 “√” indicates that this function has been 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 that there are no saved parameter configurations in the camera’s Storage area, leading to a loading failure.

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, please refer to 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 map, file name format: color_time_index-numer.png.
Left-IR	Left IR Stream	Left grayscale map, file name format: leftIR_time_index-numer.png.
Right-IR	Right IR Stream	Right grayscale map, file name format: rightIR_time_index-numer.png.
Piont3D	Depth Stream	Original point cloud data, file name format: Point3D_time_index-numer.xyz.
RGB2D	Depth Stream + Color Stream	Aligned map of color map and depth map, file name format: RGB2D_time_index-numer.png.
D2RGB	Depth Stream + Color Stream	Rendered aligned map of depth map and color map, file name format: D2RGB_time_index-numer.jpg. Unrendered aligned map of depth map and color map, file name format: D2RGB_time_index-numer.png. Distortion-corrected color map, file name format: undistort_color_time_index-numer.png.
Color3D	Depth Stream + Color Stream	Note When saving Color3D, in addition to turning on the Depth Stream and Color Stream, you also need to check the D2RGB or RGB2D image type before you can check Color3D and perform the continuous image-saving operation. 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 map, file name format: D2RGB_time_index-numer.jpg. Unrendered aligned map of depth map and color map, file name format: D2RGB_time_index-numer.png. Distortion-corrected color map, 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 map and depth map, file name format: RGB2D_time_index-numer.png. Distortion-corrected color map, 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 the video recording process, some parameters can be adjusted, while closing/opening 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