DTC 1.2 User Guide - Quanergydownloads.quanergy.com/qortex-bulldog/QortexDTC_1... · QORTEX DTC 1.2 User Guide, QPN 96-00017 Rev G Page 3 Revision History Version Date What Changed

DTC 1.2 User Guide

Detection, Tracking, Classification

QORTEX DTC 1.2 User Guide, QPN 96-00017 Rev G Page 2

Notices

Copyright © 2019, Quanergy Systems, Inc. All rights reserved.

This document is protected by copyright law, whereby all rights established therein remain with Quanergy Systems, Inc. Reproduction of this document or parts of this document, without permission from Quanergy, is only permissible within the limits of applicable copyright law. Alteration or abridgement of the document is not permitted without the explicit written approval of Quanergy.

QUANERGY, the QUANERGY Logo, QORTEX, QORTEX DTC and associated logos, M8, S3, Q-GUARD, Q-VIEW, QSPU, QPU-L7, QPU Mini, MULTI-LIDAR FUSION are all trademarks of Quanergy Systems, Inc. All other trademarks are the property of their respective owners.

See also Acknowledgments of copyrighted material: http://downloads.quanergy.com/License.txt and End User Software License Terms that apply to all platforms hosting the Q-View software: http://downloads.quanergy.com/quanergy_end_user_software_license_terms.pdf

ISO 9001:2015 Certified

Contact

Quanergy Systems, Inc. 482 Mercury Drive Sunnyvale, CA 94085-4706 http://quanergy.com

For purchases made directly from Quanergy: contact [email protected]

For purchases from a third party such as value-added reseller/system integrator: contact them for support

Follow Us!

https://www.linkedin.com/company/quanergy/

https://twitter.com/quanergy/

https://www.facebook.com/quanergy/

https://www.youtube.com/c/QuanergySystems/


Revision History

Version Date What Changed

A 03/31/17 Released to support Q-Guard version Beta 1. B 07/17/17 Released to support Q-Guard version Beta 2.

Updated sections related to Live, Record, and Playback modes. Added Figure 25, Figure 26, Figure 30, Figure 33, and Table 9. Added “Object Types,” “Handling Locations,” “Downloading Recorded Data,” “Disconnecting,” and “Eliminate Cross-Talk” sections.

C 10/16/17 Released to support Q-Guard version Beta 3. Removed support for Mac OS. Added various new client/server Linux-based configurations, including QSPU. Added AXIS camera, QLog recording/playback, zone events, Library errors. Omitted “Eliminate Cross-Talk” section. Updated most tables and figures.

D 03/30/18 Released to support Q-Guard version 1.0. Added social media “Follow Us!” Removed support for QPU, and added specs for QPU-L7, QPU Mini, and PC. Updated Camera section and added Appendix 2 to support ONVIF Platform S. Moved all API information into Appendix 1. Added Index.

E 08/31/18 Released to support QORTEX DTC version 1.1 (formerly Q-Guard). Updated to support Ubuntu 16.04 LTS (18, 21, 23, 24), QSPU handling 20 sensors (17-19), ”3D Controls” (50), location directory (54), zone visibility (69), zone events (71, 84), “M8 LiDAR Sensors” reduced data packet (13), “State List” (104), and Appendix 1 “API for Port Monitoring” (99-110). Added Figure 37, Figure 40, Figure 61, new cover art (1), legal text (2), side view reset (46, 48), settings templates (52, 57), elevated zones (66, 70), “Sensor Health” (97), “Version Discovery” (98), list of GUI-equivalent commands (110), and Appendix 3 to explain the coordinate system (112). Renamed many tables and figures.

F 10/12/18 Fixed underscore display error. Updated QSPU model description (19-20).

G 02/07/19 10/15/19 12/17/19

Released to support QORTEX DTC version 1.2 and M8 PoE+ sensor. Updated “Notices” (2), “User Documents” (15), “QSPU or QSPU-Comparable” (19), “QPU Mini” (23), debian versions (28), license duration (29), multi-camera usage and high priority zones (74-87), length of unique object ID (99), and Zone List publication frequency (101). Added Figure 2, Figure 45. Updated Table 2, Table 3, Table 5, Figure 3, Figure 7, Figure 38, Figure 41. Updated license expiration description (29, 32, 37). Added missing information to the bottom of Figure 57.


This page intentionally left blank.


Contents

Notices.................................................................................................................................. 2 Contact ................................................................................................................................. 2 Follow Us! ............................................................................................................................. 2 Revision History..................................................................................................................... 3 Contents ............................................................................................................................... 5 Figures .................................................................................................................................. 9 Tables ................................................................................................................................. 10

1. Getting Started ........................................................................................................ 11

Unique Features .................................................................................................................. 11 Assumptions ....................................................................................................................... 12 System Architecture ............................................................................................................ 12

M8 LiDAR Sensors .......................................................................................................................... 13 QORTEX DTC Server ........................................................................................................................ 13 QORTEX DTC Client......................................................................................................................... 14

2. Preparing the QORTEX DTC Environment ................................................................. 15

User Documents.................................................................................................................. 15 User-Supplied Items ............................................................................................................ 16

Accessories ..................................................................................................................................... 16 Hard Drive ...................................................................................................................................... 16 Host Computer ............................................................................................................................... 16

Installation Configurations .................................................................................................. 17 QSPU or QSPU-Comparable .......................................................................................................... 19 QPU-L7 ........................................................................................................................................... 21 QPU Mini ........................................................................................................................................ 23 PC Desktop or Laptop, Ubuntu 16.04 Certified ............................................................................. 24

Connect and Start the Host Computer(s) ............................................................................ 25

3. Acquiring the QORTEX DTC Software ....................................................................... 26

Download New Debian Package and Documents ............................................................... 26 Move New Debian Package to Destination Computer ........................................................ 28 Install New Debian Packages .............................................................................................. 28

4. Managing the QORTEX DTC License .......................................................................... 29

Learn about the License Portal ............................................................................................ 30 Use the License Portal ......................................................................................................... 31 Activate a License ............................................................................................................... 32 Refresh a License ................................................................................................................ 33 Deactivate a License ........................................................................................................... 34 Renew a License.................................................................................................................. 35

First Expiration Warning ................................................................................................................. 35


Final Expiration Warning ................................................................................................................ 35

Check a License .................................................................................................................. 36 Manage the License of an Air-Gapped Computer .............................................................. 37

5. Launching the QORTEX DTC Software ....................................................................... 39

Launch the QORTEX DTC Server .......................................................................................... 39 Install and Start the QORTEX DTC Client .............................................................................. 40 Configure the Client via global_settings.ini File .................................................................. 41

6. Controlling QORTEX DTC Operation ......................................................................... 43

QORTEX DTC Server Stop, Start, and Status ........................................................................ 43 QORTEX DTC Client Stop and Start ..................................................................................... 43

Stop the Client ............................................................................................................................... 43 Start the Client ............................................................................................................................... 43

7. Using the QORTEX DTC Client Interface .................................................................... 44

Menu Bar ............................................................................................................................ 45 Mode Controls .................................................................................................................... 47 Viewing Controls ................................................................................................................. 48 Display Area ........................................................................................................................ 49

Configuration Choices .................................................................................................................... 49 3D Controls .................................................................................................................................... 50 Object Types .................................................................................................................................. 50

Tracking Box ....................................................................................................................... 51

8. Handling Locations ................................................................................................... 52

Create a New Location ....................................................................................................... 52 Learn a Location’s Background ........................................................................................... 55 Rename or Delete a Location .............................................................................................. 56 Update a Location ............................................................................................................... 57

9. Visualizing the Raw Data .......................................................................................... 58

Via Live Mode ..................................................................................................................... 58 Via Playback Mode .............................................................................................................. 60

10. Preserving the Raw Data via Record Mode ............................................................. 61

Record Data ........................................................................................................................ 62 Visualize Recorded Data ..................................................................................................... 62 Share/Download Recorded Data......................................................................................... 63

11. Adjusting the Data Display ...................................................................................... 64

12. Working with Special Zones ..................................................................................... 65

Enable and Disable Zones ................................................................................................... 65 Draw a Zone ........................................................................................................................ 66


Name a Zone ...................................................................................................................... 68 Hide/Show a Zone .............................................................................................................. 69 Adjust the Zone Distance Above the Floor ......................................................................... 70 Define an Event (For Event Zones Only) .............................................................................. 71 Delete a Zone ..................................................................................................................... 73

13. Enabling and Using Cameras.................................................................................... 74

Learn about Supported Cameras ........................................................................................ 74 Set Up the Camera .............................................................................................................. 75 Customize the Camera Values ............................................................................................ 76 Use the Camera to Draw Attention ..................................................................................... 80

In a Location ................................................................................................................................... 80 In a Zone Within a Location ............................................................................................................ 84 Camera Track-Following Logic ....................................................................................................... 86

Switching Camera-Sensor Affiliation ................................................................................... 87

14. Accomplishing Multi-LiDAR Fusion .......................................................................... 88

Share the Data to Enable Fusion ......................................................................................... 88 Create a New calibration.ini File .................................................................................................... 89 Create a New settings.ini File ........................................................................................................ 89 Update the calibration.ini File ........................................................................................................ 90

See the Visual Storyboard of Fusion .................................................................................... 92

15. Disconnecting ........................................................................................................... 94

Unplanned Server Disconnect ............................................................................................. 94 Planned Client Disconnect .................................................................................................. 94

16. Troubleshooting ....................................................................................................... 95

Library Errors ....................................................................................................................... 95 Quanergy Folder ................................................................................................................. 95 Licensing ............................................................................................................................. 96

Activation Error 5008 ...................................................................................................................... 96 Deactivation Error 9015 ................................................................................................................. 96 Settings File Error ........................................................................................................................... 96

Server Crash ........................................................................................................................ 97 Client Crash ........................................................................................................................ 97 Sensor Health ...................................................................................................................... 97 Version Discovery ................................................................................................................ 98 Remove Previous Software .................................................................................................. 98 Any Other Issue .................................................................................................................. 98

Appendix 1: API for Port Monitoring ............................................................................ 99

Outputs to Consume .......................................................................................................... 99 Object List ...................................................................................................................................... 99


Zone List ....................................................................................................................................... 101 Object Point Cloud....................................................................................................................... 103 State List ....................................................................................................................................... 104

Server Ports to Monitor ..................................................................................................... 106 Port-Monitoring Tool ........................................................................................................ 107

Request ......................................................................................................................................... 108 Requirements ............................................................................................................................... 108 Build ............................................................................................................................................. 108 Execute ......................................................................................................................................... 109 Stop .............................................................................................................................................. 109

Publication-Confirmation Utility ........................................................................................ 109 Command Alternatives to Client GUI ................................................................................ 110

Background Save .......................................................................................................................... 110 Background Load ......................................................................................................................... 110 Background Learn ........................................................................................................................ 110 Help .............................................................................................................................................. 110

Appendix 2: ONVIF Camera Commands ..................................................................... 111

PTZ Service Commands .................................................................................................... 111 Device Service Commands ............................................................................................... 111 Media Service Commands ................................................................................................ 111

Appendix 3: Cartesian Coordinate System ................................................................. 112

Index ............................................................................................................................ 113


Figures Figure 1. QORTEX DTC System Architecture Overview .............................................................. 12 Figure 2. QSPU Example Illustration of the R640 Front Panel (top), Rear Panel (bottom) .......... 20 Figure 3. QSPU Example Illustration of the R630 Rear Panel (top), Front Panel (bottom) .......... 20 Figure 4. QPU-L7 Rear Panel (top), Front Panel (bottom) .......................................................... 22 Figure 5. QPU Mini in IP67-Rated Enclosure ............................................................................. 24 Figure 6. Network Manager Reveals Host Computer’s IP Address ............................................ 25 Figure 7. Quanergy Download Center ...................................................................................... 27 Figure 8. SoftwareKey Customer License Portal ........................................................................ 30 Figure 9. SoftwareKey Customer License Portal Downloads Page ............................................ 31 Figure 10. License Activate at the Command Line .................................................................... 32 Figure 11. License Refresh at the Command Line ..................................................................... 33 Figure 12. License Deactivate at the Command Line ................................................................ 34 Figure 13. Invalid (top) and Valid (bottom) License, Server Version at the Command Line ....... 36 Figure 14. SoftwareKey Customer License Portal Manual Request ........................................... 38 Figure 15. Server IPv4 Address Request ................................................................................... 40 Figure 16. global_settings.ini File: Edit the Parameter Values (Defaults Values Shown) ............ 42 Figure 17. Client Window on Startup ........................................................................................ 44 Figure 18. Menu Bar ................................................................................................................. 45 Figure 19. Live Mode ................................................................................................................ 47 Figure 20. Playback Mode ........................................................................................................ 47 Figure 21. Record Mode ........................................................................................................... 47 Figure 22. Client Viewing Controls Affect 3D Display ............................................................... 49 Figure 23. Client Resets to 2D Top View (left) or to 2D Side View (right) .................................. 49 Figure 24. Visualizes Human and Unidentified Objects ............................................................. 50 Figure 25. Q-View Sensor Tile .................................................................................................. 52 Figure 26. Creating New Location ............................................................................................ 53 Figure 27. Locations Directory Containing settings.ini File (Example) ....................................... 54 Figure 28. Visualization of Raw Data ......................................................................................... 58 Figure 29. Live Mode: Play à Stop Load à Pause à Connected ............................................ 59 Figure 30. Live Mode: Disconnect and Pause ........................................................................... 60 Figure 31. Playback Mode: Play à Pause à Play/Step/Replay ................................................. 60 Figure 32. Record Mode: Start Record à Spinner à Stop Record ........................................... 62 Figure 33. Playback Mode: Compress (or Cancel) Download ................................................... 63 Figure 34. Newly Drawn Polygon Zone ..................................................................................... 67 Figure 35. Special Zone Rename Feature ................................................................................. 68 Figure 36. Hide/Show Zone ...................................................................................................... 69 Figure 37. Zone's Relative Height above Min Z Distance .......................................................... 70 Figure 38. Event Zone Only: Entry Action (left), Exit Action (middle), Tracking (right) ............... 72 Figure 39. Event Zone Only: Entry Action to Highlight ............................................................. 72 Figure 40. Zone Deletion .......................................................................................................... 73 Figure 41. settings.ini Example File for ONVIF Cameras ........................................................... 79


Figure 42. global_settings.ini File: Add an Occlusion Switch Delay .......................................... 81 Figure 43. Tracking Box: Main Location (top), Zone within a Location (bottom) ........................ 82 Figure 44. Camera Tracking in a Zone with All Features Enabled ............................................. 82 Figure 45. Camera Track-Following Evaluation Sequence ........................................................ 86 Figure 46. Q-View calibration.ini File Example.......................................................................... 88 Figure 47. settings.ini File: Edit Sensor Data ............................................................................. 90 Figure 48. Moves Alignment Data from calibration.ini into settings.ini File .............................. 91 Figure 49. Scene by Single Sensor A in Position X .................................................................... 92 Figure 50. Scene by Single Sensor B in Position Y .................................................................... 92 Figure 51. Unfused View of Scene by Dual Sensors A & B ........................................................ 93 Figure 52. Fused View of Scene by Primary Sensor A and Secondary Sensor B ........................ 93 Figure 53. Live Mode: Disconnect from Server ......................................................................... 94 Figure 54. Object List in Protobuf (top), JSON (left), and XML (right) ..................................... 100 Figure 55. Zone List in Protobuf .............................................................................................. 101 Figure 56. Zone List in JSON (left) and XML (right) ................................................................. 102 Figure 57. Object Point Cloud in Protobuf .............................................................................. 103 Figure 58. State List in Protobuf .............................................................................................. 105 Figure 59. External Applications Access Output on Server’s Host Computer ......................... 106 Figure 60. Port-Listening Tool qortex_listener Main Routine .................................................. 107 Figure 61. Coordinate System: Right-Hand Rule, M8 Sensor .................................................. 112

Tables Table 1. QORTEX DTC Installation Configuration Options ......................................................... 18 Table 2. Minimum Specifications for the QSPU or QSPU-Comparable System ......................... 19 Table 3. Bonus Specifications for the QSPU System ................................................................. 20 Table 4. Specifications for the QPU-L7 System ......................................................................... 21 Table 5. Specifications for the QPU Mini .................................................................................. 23 Table 6. Minimum Specifications for PC Desktop or Laptop ..................................................... 24 Table 7. Menu Bar Items ........................................................................................................... 45 Table 8. Viewing Controls Affect What Is Displayed ................................................................. 48 Table 9. Statistics of Example Recordings ................................................................................. 63 Table 10. Camera Menu Items Affect What Is Displayed .......................................................... 83


1. Getting Started QORTEX DTC™ (formerly known as Q-Guard™) is a LiDAR-based solution that provides three-dimensional perception and volumetric sensing. This package enables the detection, tracking, and classification (DTC) of human objects in order to:

• Accurately localize objects to be tracked uniquely in real time • Efficiently automate surveillance with control of ONVIF cameras • Customize event zones and exclusion zones with flexible commands

With data intelligence and centimeter-level accuracy, QORTEX DTC provides a cost-effective solution to enable Internet of Things (IoT) applications in different sectors such as security and crowd management, where people movement and analytics are important to monitor. Other applications include protecting critical infrastructure such as power and water stations, airports, harbors, oil refineries or any industrial premises holding valuable equipment, or for prisons where unapproved objects are forbidden.

Unique Features

QORTEX DTC accomplishes its demanding goals through the following features in a combined hardware/software solution that relies on Quanergy’s M8™ LiDAR sensor:

• Extended Detection Range in Real-Time. Enables accurate, real-time detection of static and moving objects within 50 meters of the sensor.

• Classification of Shape Data. The sensor produces surveillance data that the host computer collects, records, visualizes, analyzes, classifies, and outputs into an Object List that serves as the basis for further action, including the notification of external alarm systems via LAN, TCP, and HTTP GET.

• Persistence in Tracking. Commercial-grade, static LiDAR visualization system is able to sense and display the movement of human-sized objects over time, persisting even through blockages and crowd gaps. This gives users the ability to track and record the historical movements of potential threats.

• Resilience in Suboptimal Conditions. Designed for use indoors and outdoors in any weather, in the light or dark, with no infrared signature needed.

• Leverage Q-View Calibration. Q-View™ is Quanergy's sensor discovery and manage-ment toolkit, which can calibrate multiple sensors into the same space and output the resulting calibration.ini file. QORTEX DTC ingests that file and aligns the overlapping vision of multiple sensors into an enriched Multi-LiDAR Fusion™ view.

• Enhances Legacy Systems. QORTEX DTC reduces or eliminates false positive threats and dramatically boosts the surveillance effectiveness of Video Management Systems (VMS) by measuring and providing exact 3D coordinates of humans.


Assumptions What you should know about QORTEX DTC:

• Network connection. LiDAR sensors connect to the installation site’s local area network (LAN) via TCP/IP protocol. The QORTEX DTC server and QORTEX DTC client connect to the same LAN in order to access the visualization and alert system.

• Synergy. LiDAR sensors that integrate into existing VMS may be able to leverage that existing power and communication infrastructure, if compatible.

• Steady power supply. For LiDAR sensors deployed in areas where power outages occur, a backup power system is strongly advised.

• Weather tolerant. LiDAR sensors can withstand extreme weather from bitter cold to baking sun, with complete ingress protection from mist, rain, snow, and dust.

System Architecture The QORTEX DTC system architecture deploys in a simple distributed scenario that includes the QORTEX DTC server and a QORTEX DTC client or third-party application to consume the server’s output. The server receives input from multiple M8 LiDAR sensors and produces output to the customer’s own network infrastructure. The QORTEX DTC solution involves several blocks of functionality that produce output, as shown in Figure 1 and explained in the following subsections.

Figure 1. QORTEX DTC System Architecture Overview


M8 LiDAR Sensors

The QORTEX DTC system can include multiple M8 LiDAR sensors, including any of the following:

• M8-Core, M8-Plus, M8-Ultra: Rev D and up • M8 PoE+: Rev A and up

The sensor’s revision level is stated on the sensor’s manufacturing label. The sensors may be connected via the local Ethernet to create a unified point cloud for Multi-LiDAR Fusion surveillance.

The M8 sensor is able to measure, evaluate, and report the distances and intensities of up to three return pulses. QORTEX DTC supports the new M8 reduced data packet. For the M8 sensor,1 the user may select Return 0, Return 1, Return 2, or All 3 through the M8 Sensor Settings Management application (webserver) as explained in the M8 Sensor User Guide (https://quanergy.desk.com/customer/portal/articles/2687038).

Quanergy recommends selecting only one return to save on network bandwidth. When a single return is selected, an M8 sensor generates 20 megabits per second. When all three returns are selected, an M8 sensor generates close to 60 megabits per second. The single return option has no performance reduction because the object point cloud published by QORTEX DTC shows only a single return regardless.

QORTEX DTC Server

When connected to the same local Ethernet as the client, the QORTEX DTC server is the backend system that accomplishes three primary tasks:

1. Provides essential functionality:

• After initial bootup and login, the server is able to restart automatically as needed. • Connects to multiple M8 LiDAR sensors by IP address.2 • Accepts commands and parameters from the remote client via a shared interface. • Synchronizes to client settings files and calibration files (if any) upon initialization.

2. Processes data collected by the sensors:

• Collects, timestamps, unifies, and formats all point cloud data from each sensor. • Creates a static “background map” of the surveillance area of interest. • Detects objects of various sizes and shapes against the created map.

1 For M8 LiDAR sensor Rev D5 and up, or Rev D4 with a patch updating Base firmware to 7.03. 2 While the QORTEX DTC software has no limit on the number of sensors, in practice the physical limit is based on the current processor speed and available memory.


• Tracks each unique object through space and time using configurable parameters. • Measures the sizes and velocities of objects in the surveillance area. • Classifies objects in terms of motion, size, and velocity. • Detects if any active objects are in zones of interest.

3. Publishes output from its processing action in a serialized format (Protobuf, XML, or JSON) on the local Ethernet. Any number of potential third-party host infrastructure applications may subscribe to these published data stream outputs for surveillance or visualization, as discussed in Appendix 1, which starts on page 99. The outputs are:

• Object List • Zone List • State List • Object Point Cloud

In this “Client-Authoritative System,” only a single client at a time may connect directly to a server to push commands, settings, and server configuration data. (If multiple clients were allowed simultaneous control, data collisions would occur and clients would overwrite each other’s commands and locations). Note that as soon as the client releases its direct connection to the server, a different client is allowed to connect, and the original client is locked out until that new connection is closed.

QORTEX DTC Client

The QORTEX DTC client is a standalone application that renders a three-dimensional representation of the Object List, Zone List, and Object Point Cloud published by the server. The client accesses this data directly from the server in a fast pipeline interface designed only for client use. (It is not available to the user.)

The client connects to the same Ethernet network as the server. The client is responsible for posting command and data messages that control the server’s behavior, as follows:

• Overrides any settings in the file system to configure the server’s current behavior. • Determines the mode: Playback, Live (for real-time rendering), or Record (page 58). • Commands the recording activity to Start Record or Stop Record (page 61). • Defines and actuates EVENT ZONES, EXCLUSION ZONES, and the circumstances that trigger

a zone event (page 65).


2. Preparing the QORTEX DTC Environment This section explains how to set up the QORTEX DTC environment. In general, you must have a properly set up Ethernet network, properly installed M8 LiDAR sensors (see M8 Sensor User Guide), and be able to discover and manage those sensors (see Q-View User Guide). Essential user guides are listed below.

Sensors must be on the same subnet as the QORTEX DTC server’s Ethernet!

User Documents

A variety of user documents are available to support all the complete QORTEX DTC system, as follows:

QORTEX DTC-specific user documents include the following:

QORTEX DTC 1.x User Guide — https://quanergy.desk.com/customer/portal/articles/2755121 QORTEX DTC 1.x Quick Start Card — https://quanergy.desk.com/customer/portal/articles/2755133 QSPU with QORTEX DTC Server Quick Start Card — https://quanergy.desk.com/customer/portal/articles/2889649 QPU-L7 with QORTEX DTC Server Quick Start Card — https://quanergy.desk.com/customer/portal/articles/2920478 QPU Mini User Guide — https://quanergy.desk.com/customer/portal/articles/2914325 QPU Mini with QORTEX DTC Server Quick Start Card — https://quanergy.desk.com/customer/portal/articles/2914504

Essential user guides related to other parts of the QORTEX DTC system include:

M8 Sensor User Guide — https://quanergy.desk.com/customer/portal/articles/2687038 M8 Sensor Quick Start Card — https://quanergy.desk.com/customer/portal/articles/2687032 M8 PoE+ Sensor User Guide — https://quanergy.desk.com/customer/portal/articles/2959430 M8 PoE+ Sensor Quick Start Card — https://quanergy.desk.com/customer/portal/articles/2959431 Q-View User Guide — https://quanergy.desk.com/customer/portal/articles/2717074 Q-View Quick Start Card — https://quanergy.desk.com/customer/portal/articles/2748632

Other downloadable Quanergy documents are accessible through this list:

QORTEX DTC Documents List — https://quanergy.desk.com/customer/portal/articles/2923379


User-Supplied Items

Here are some items to supplement your QORTEX DTC system:

Accessories

A keyboard, mouse, and monitor are needed to use the QORTEX DTC client. Depending on how the QORTEX DTC server is configured, you might also need those accessories when you first set up the server. However, the server is designed to run headless, so you shouldn’t need them after the server starts running.

Hard Drive

Recordings can quickly consume a huge amount of memory, so if you plan to record, set up the system in a way that prevents overwhelming your hard drive. If you don’t have sufficient space, invest in and integrate an external hard drive of a capacity somewhat greater than you anticipate actually needing.

Host Computer

There are a variety of options for which computer(s) may host the QORTEX DTC server and QORTEX DTC client. Some of those options are supplied by the user. The various installation configurations are listed in Table 1.


Installation Configurations

Quanergy offers several options for great flexibility in configuring your QORTEX DTC system. These options are pre-loaded with QORTEX DTC server software:

• Quanergy Server Processing Unit (QSPU™) server — serves up to 20 sensors. • Quanergy Processing Unit-L7 (QPU-L7™) computer — serves up to 6 sensors. • QPU Mini™ platform — serves up to 2 sensors.

NOTE: The listed maximum number of sensors that our hardware can support is a recommendation, not a hard limit. The true number depends on a number of factors such as total surface area and height of the scanned world, size of the voxels, number of simultaneous active and moving objects, velocity and size of objects being tracked.

Other options allow you to select, set up, and install your own solutions. For best results in running the software: 3

• Make sure the QORTEX DTC server’s host computer has at the very minimum:

– For indoor, short-range applications (within 50x50m): i3 processor, 4 GB memory.

– For outdoor, long-range applications (beyond 50x50m): i5 processor, 8 GB memory.

• Make sure the QORTEX DTC client’s host computer has at the very minimum:

– For all applications: i3 processor, 4 GB memory, and OpenGL-compliant graphics such as GeForce 8800 or Radeon 4770.

All of these options for configuring the QORTEX DTC system are summarized in Table 1. Those configurations (or any other comparable desktop or laptop4) may employ a Linux® virtual machine (VM), and the QSPU should employ VMs for best use of cores, as follows:

• The computer hosting the VM must have at least 2 core processors5 and 4096 MB virtual memory.

• If the user will record data, the hard drive should have at least 20 GB storage. • VMware® ESXi 6.5 is the recommended VM.

3 Not all i3 and i5 processors are the same, and processor requirement should be informed by the number of sensors to support and the number of objects tracked. If you have any question about which processor is suitable, contact your support representative. 4 Other possible options are at https://www.digitaltrends.com/computing/best-virtual-machine-apps-for-mac-linux-and-windows-pcs/ 5 Not all cores are equal since processor ability varies, and performance is impacted by the number of sensors to support. If you have any question about which processors/cores are suitable, contact your support representative.


Table 1. QORTEX DTC Installation Configuration Options

Option Hardware OS Supplier QORTEX DTC Server Included

QORTEX DTC Client Included

1) ≤20 sensors

QSPU server. Linux Quanergy Factory-installed. See Table 2, Table 3.

Never install the client on Option 1, 2, 3, or 4. (If the server runs on Option 1, 2, 3, or 4, then the client must run on Option 5 or Linux VM.)

2) QSPU-comparable server. Linux User User-installed Debian package. See Table 2.

3) ≤6 sensors

QPU-L7 computer. Linux Quanergy Factory-installed. See Table 4.

4) ≤2 sensors

QPU Mini platform. Linux Quanergy Factory-installed. See Table 5.

5) PC desktop or laptop.6 Linux, Ubuntu® 16.04 LTS Certified

User User-installed Debian package. See Table 6.

If the server runs on Option 1, 2, 3, 4, or 5, then the client can run on Option 5 as a user-installed Debian pkg.

NOTE: If the QORTEX DTC server and client are running on separate host computers, then the server may operate headless — without monitor or peripherals.

6 PC requires certified Linux Ubuntu 16.04 (LTS Xenial Xerus) operating system. A list of desktops and laptops is at https://certification.ubuntu.com/


QSPU or QSPU-Comparable

The specifications listed in Table 2 for the QSPU system also serve as the minimum require-ments for the QSPU-comparable server that is listed in Table 1 as Option 2. This server configuration accepts inputs from up to 20 LiDAR sensors, where, for example, each of 5 virtual machines runs up to 4 sensors on 2 cores (4 vcores), that is, one sensor per vcore.

When purchased from Quanergy, the QSPU is pre-configured with a QORTEX DTC server on a virtual machine. For best results, distribute the sensors on separate vcores. Four Ethernet ports are enabled, but no more than 10 sensors should be assigned to a single port because of each M8 sensor’s data bandwidth demands, as discussed in the “M8 LiDAR Sensors” section on page 13.

Table 2. Minimum Specifications for the QSPU or QSPU-Comparable System

System Parameter R640 (Current Shipment) R630 (Before September 2018)

Hardware Central Processing Unit Intel® Xeon® Silver 4114 2.2 GHz 10-core (20-vcore) processor

Intel Xeon E5-2640 v4 2.4 GHz 10-core (20-vcore) processor

Random Access Memory 32 GB RAM (4 x 8 GB RAM) 32 GB RAM (4 x 8 GB RAM) Storage Memory 1 TB 7.2K RPM SATA 6 Gbps 512n

2.5 in hot-plug hard drive (x2) 1 TB 7.2K RPM SATA 6 Gbps 512n 2.5 in hot-plug hard drive (x2)

Ethernet Network Interface Cards 10GbE, Base-T LAN / WAN (x4) 1 Gbps LAN / WAN (x4) Software Operating System VMware® ESXi 6.5 VMware ESXi 6.5

The QSPU is a Linux-based Dell PowerEdge R6XX 1U rack server that hosts the pre-installed QORTEX DTC server software. The QSPU includes a 1U high rear panel (Figure 2 top) that allows a user to connect the QSPU to a power source and to the network. Through the network, the QSPU has access to the M8 sensors and to the QORTEX DTC client. When it is necessary to interact directly with the QSPU, the user may remote log in or attach accessories to the front panel (Figure 2 bottom; due to model differences, your QSPU may be configured differently). The processor package and system are protected by thermal management features. The QSPU includes acceleration for memory intensive virtualized applications.

QORTEX DTC does not exploit all the QSPU has to offer. Some additional hardware may be populated to offer capabilities (listed in Table 3) that may be unused (and not mentioned in Table 1), but they are still available to you for additional redundancy.


Table 3. Bonus Specifications for the QSPU System

Purpose R640 (Current Shipment) R630 (Before September 2018)

Disk Mirroring RAID 1 PERC H730P RAID controller, 2 GB cache

RAID 1 PERC H730 integrated RAID controller, 1 GB cache

Hypervisor Boot Image Internal dual SD module (IDSDM) for SD cards 16 GB microSDHC cards included (x2)

Internal dual SD module (IDSDM) for SD cards 16 GB SD cards included (x2)

Server Management Controller

Integrated Dell Remote Access Controller 9 (iDRAC9)

Integrated Dell Remote Access Controller 8 (iDRAC8)

For additional details about the QSPU capabilities, refer to:

• QSPU with QORTEX DTC Server Quick Start Card, https://quanergy.desk.com/customer/portal/articles/2889649 • Dell PowerEdge R640 Manuals, https://www.manualslib.com/products/Dell-Emc-Poweredge-R640-8725451.html • Dell PowerEdge R630 Manual, http://topics-cdn.dell.com/pdf/poweredge-r630_owner's%20manual_en-us.pdf

Figure 2. QSPU Example Illustration of the R640 Front Panel (top), Rear Panel (bottom)

Figure 3. QSPU Example Illustration of the R630 Rear Panel (top), Front Panel (bottom)

Power Indicator VGA USBs Control Panel Model

1 TB Drive (2)

Status & Health USB 3.0 Hard Drive (6) VGA 1 TB Drive (2)

Power Supply (2)

Power Button iDRAC Direct LED & Port USB 2.0

System ID

CMA Power iDRAC9 NIC (4)

PCIe PCIe Serial VGA USB 3.0 (2)

Redundant Power Ports (2) Ethernet Ports (4)


QPU-L7

The specifications for the QPU-L7 system (Option 3 in Table 1) are listed in Table 4. This configuration accepts inputs from up to 6 LiDAR sensors.

Table 4. Specifications for the QPU-L7 System

System Parameter Specification

Hardware Central Processing Unit Intel i7-6700TE up to 3.4 GHz 4-core processor Random Access Memory 16 GB RAM DDR4-2133 Storage Memory Primary drive: 64 GB for OS and applications

Secondary drive external bay Display Port Video, standard Intel chip set capability Serial Port RS232 or RS422 (2x) USB Port USB 3.0 (2x) for high speed devices such as extra memory

USB 2.0 (2x) for user input devices Ethernet Network Port LAN 10/100/1000 RJ45 (x2) Software Operating System Linux 16.04 LTS

The QPU-L7 is a Linux-based computer that hosts the pre-installed QORTEX DTC server software. The QPU-L7 includes a rear panel (Figure 4 top) that allows a user to connect the QPU-L7 to a power source and to the network. Through the network, the QPU-L7 has access to the M8 sensor and to the QORTEX DTC server. When necessary to interact directly with the QPU-L7, the user may remote log in or attach accessories to the front panel (Figure 4 bottom).


Figure 4. QPU-L7 Rear Panel (top), Front Panel (bottom)

Power LED Temp, HDD, and Digial I/O LEDs Dual Mode DP, HDMI ATX Power On/Off Ethernet LEDs (2)

USB 3.0 (2) Drive Bay

DC Power In DVI-I Video PS/2 Peripherals LAN (2) Serial (2) Sound (2)

USB 2.0 (2) DP1 Display Port USB 3.0 (4) External Fan Power Remote On/Off Remote Pwr Reset


QPU Mini

The specifications for the QPU Mini (Option 4 in Table 1) are listed in Table 5. This configuration accepts inputs from up to 2 LiDAR sensors.

Table 5. Specifications for the QPU Mini

Subsystem Parameter Specification

Hardware Central Processing Unit 4-core 64 bit ARM A57 Random Access Memory 4 GB RAM LPDDR4 Storage Memory 16 GB flash-based on-board program memory Software QORTEX DTC Server Ubuntu 16.04 LTS Electrical Input Power Voltage 24 VDC ± 5% Maximum Board Power

Consumption When the unit is processing load from 2 sensors: • 13 W not including power for sensors routed through the unit • 45 W including power for sensors that are connected and running

Minimum Turn-On Voltage 20 V (Unit does not draw power until voltage reaches 20 V) Physical Enclosure Size 179 mm wide x 52 mm high x 164 mm deep Thermal Enclosure Unit -40°C to +70°C ambient

The QPU Mini is an embedded computer that is pre-loaded with Qortex DTC server software. This software enables the LiDAR sensor to perform object detection, trackingm and classification, and outputs an Object List via Ethernet. (WiFi connectivity is also supported.) As part of an edge processing model, the QPU Mini’s goal is to process the sensor data and publish output to the user’s network infrastructure.

This low power, ARM-based, rugged IP67 edge appliance is suited for battery-operated and/or remote deployments. Its efficient design enables interoperation with the M8 sensor, with power and Ethernet carried over the same cable. A compact footprint makes it suitable for mounting to a pole or cabinet, and the thermal design supports a wide temperature range. It is also available as a board-only option.

The QPU Mini has passed shock/vibration testing and achieved FCC, ISED, and IEC/EN 61326-1:2013 (EMC) compliance. The CE, RoHS, and WEEE compliance applications are in progress.


Figure 5. QPU Mini in IP67-Rated Enclosure

PC Desktop or Laptop, Ubuntu 16.04 Certified

QORTEX DTC can be used with an off-the-shelf Ubuntu 16.04 certified PC desktop or laptop. The specifications listed in Table 6 are reasonable recommendations for running a single instance of QORTEX DTC on the PC listed in Table 1 as Option 5.

Table 6. Minimum Specifications for PC Desktop or Laptop

System Parameter For < 50x50 m area For > 50x50 m area

Hardware Central Processing Unit (CPU) Intel i3 processor Intel i5 processor Random Access Memory (RAM) 4 GB 8 GB Storage Memory (if recording) Recommend external storage for up to 100 MB per sensor per

minute. QORTEX DTC needs < 1 GB drive space for installation. Ethernet Network Ports Local Area Network (LAN) / Wide Area Network (WAN) Software Operating System Ubuntu 16.04 LTS or VMware ESXi 6.5

NOTE: From here forward, the various QORTEX DTC platforms are called “host computer” unless it is necessary to be specific.

RP-SMA

USB 3.0 (not shown)

RP-SMA

Power/GPIO

LAN Ethernet Uplink

LED Indicators

Sensor 2 Ethernet/Power

Sensor 1 Ethernet/Power


Connect and Start the Host Computer(s)

Before launching the software, all hardware components must be in place. Connect the computer(s) that will host the QORTEX DTC server, the QORTEX DTC client, and the virtual machine (if any) to power, accessories, sensors, and the network, as follows:

1. Connect the host computer to a power source.

2. If it doesn’t turn on automatically, turn on the power button for the host computer.

3. If it doesn’t come up automatically, boot up the Ubuntu operating system.

4. Connect user-supplied accessories (keyboard, mouse, monitor) to USB/HDMI/VGA inputs or log in remotely.

5. Connect the host computer to the same network that the sensors are on via a cable that is plugged into an Ethernet port that is not a DHCP server.

6. Discover the IP address of the host computer, referring to Figure 6:

• On the menu bar of the Ubuntu desktop, click the Network Manager menu, and select the Connection Information item.

• Write down the host computer’s IPv4 IP address as listed in your Connection Information window because you will be asked for it later.

• Click the Close button.

Figure 6. Network Manager Reveals Host Computer’s IP Address


3. Acquiring the QORTEX DTC Software After the hardware choices have been implemented and connected to reside on the same Ethernet subnet, the next steps are to remove the old software (if necessary), download the latest software, and install downloaded software through the Quanergy Download Center.

For Quanergy-supplied host computers QSPU, QPU-L7, and QPU Mini (Options 1, 3, and 4 in Table 1), the QORTEX DTC server software is already pre-installed at the factory. However, follow the procedures in the following subsections to download relevant documents or to upgrade to a more recent version of the QORTEX DTC server.

For user-supplied host computers and virtual machines (Options 2 and 5 in Table 1), you need to acquire the QORTEX DTC server and client applications, as well as relevant documents, so follow the procedures in the following subsections.

Download New Debian Package and Documents

Download the QORTEX DTC server and/or client Debian (*.deb) packages and various documents, as follows:

1. In an Internet browser, navigate to the Quanergy Download Center (http://downloads.quanergy.com), and click the QORTEX DTC icon at the top of the page (not shown), or scroll to the QORTEX DTC section (Figure 7).

2. Click the End User Software License Terms link, read it, return to the Quanergy Download Center, and check the I agree to the...Terms box.

3. Click the User Guide link, download it from the page hosting it, and return to the Quanergy Download Center to do the same for whichever Quick Start Cards describe your system. For example, if you have a QSPU, then download the QORTEX DTC Quick Start Card, QSPU Quick Start Card, and Acknowledgments.

4. Click the QORTEX DTC Readme link (now clickable) to open the installation instructions/links.

5. Navigate to http://downloads.quanergy.com/deb-qortex/ to open the Index page listing current versions of the QORTEX DTC software.

6. Click each Debian bundle that you need, and download it to the Downloads folder (or wherever you prefer).


Figure 7. Quanergy Download Center

downloads.quanergy.com

Client Server platforms QPU Mini Server only


Move New Debian Package to Destination Computer

If the package(s) will be used on a different computer (such as an air-gapped computer) than the one you downloaded to, take these extra steps:

1. Search the current computer for the package(s) you need to move (where 1.2.xx is the current release version), and note the filepath for them:

qortex-client-1.2.xx-Linux-bundle.deb ###bundle for client

qortex-server-1.2.xx-Linux-bundle.deb ###bundle for most server platforms

qortex-server-1.2.xx-arm64-bundle.deb ###bundle for QPU Mini server platform only

2. Transfer the package(s) to an external USB or hard drive.

3. Connect that drive to the destination computer, and transfer the relevant package to a filepath location comparable to where the Debian had been placed during the original download.

Install New Debian Packages

NOTE: If this installation is to replace old software or to freshly reinstall current software, refer to the “Remove Previous Software” section on page 98.

Now that the software is in its final destination, install it as follows:

1. Open a new terminal window (Ctrl+Alt+T) on your host computer.

2. Execute the following command to install the QORTEX DTC server and/or client from the downloaded Debian package(s). (1.2.xx is the current release version.)

$ cd ~/Downloads ###Or wherever you downloaded it

Execute the following command(s) to install only the package(s) you need:

$ sudo dpkg -i qortex-client-1.2.xx-Linux-bundle.deb ###Bundle for client

$ sudo dpkg -i qortex-server-1.2.xx-Linux-bundle.deb ###Bundle for most server platforms

$ sudo dpkg -i qortex-server-1.2.xx-arm64-bundle.deb ###Bundle for QPU Mini server only

All programs and libraries have been placed where they are needed. You won’t be able to use them until you activate the license, as discussed in the “Managing the QORTEX DTC License” section starting on page 29.


4. Managing the QORTEX DTC License The QORTEX DTC server (not the client) needs a valid license tied to its host machine and to a version of the server software before the application is permitted to run.

Tiers. There are two tiers of QORTEX DTC licenses:

• Premium, which performs detection, tracking, and classification of humans, with PTZ camera control. Premium also allows access to plug-ins for Milestone and Genetec Video Management Systems (VMS).

• Essentials, which performs detection, tracking, and classification of humans.

Sensors. Each license is approved for use with a specified number of sensors. This number is based on the user’s purchase history.

Duration. There are two types of licenses:

• Annual or development kit licenses expire based on the issue date, that is the date the license was created and sent to you.

• Perpetual licenses never expire for a particular version of the software. These licenses are available only for the Premium license tier.

Tasks. The server includes a License Manager (command-line interface utility) through which to manage your licenses while daemon service continues. Managing the licenses involves several tasks:

• License Activation (page 32) • License Refresh (page 33) • License Deactivation (page 33)

Credentials. Before you can activate a license, you must have received an email from your support representative containing a License ID and Activation Password. If you were expecting to receive these credentials but did not, contact your support representative to ask for them.

Offline. The simplest way to accomplish these three tasks is through the Internet. However, if Internet access is not available on the QORTEX DTC server’s air-gapped host machine, you can employ an Internet-connected third machine to retrieve a file that will enable you to manage the license on the air-gapped host machine. This process is explained in the “Manage the License of an Air-Gapped Computer” section that starts on page 37.


Learn about the License Portal

After the software is downloaded and installed, the next major step is to acquire and activate the QORTEX DTC server license, which is necessary for servers on both the Quanergy-supplied QSPU, QPU-L7, and QPU Mini (Options 1, 3, and 4 in Table 1), as well as user-supplied host computers and virtual machines (Options 2 and 5 in Table 1).

The steps to accomplish this are described in the next few subsections through the use of the SoftwareKey Customer License Portal, as shown in Figure 8. This License Portal provides an organized place to access software, retrieve license keys, manage licenses, update contact information, and find support contact information.

Figure 8. SoftwareKey Customer License Portal

These items appear, but are not used.


Use the License Portal

Your support representative will create an account for you and email these items to you:

• Link and credentials necessary for logging in to the License Portal (Figure 8). • License ID and Activation Password necessary for using the License Manager,

which is discussed in the “Managing the QORTEX DTC License” section on page 29.

Use the emailed information to log in to the License Portal, as follows:

1. On an Internet-connected host computer (or a third computer not hosting server or client), use the link supplied in the email to navigate to the License Portal. The link is https://license.quanergyworks.com/solo/customers/Default.aspx.

2. Log in to the License Portal using the credentials supplied in the email.

3. Click the Downloads button (Figure 8) if you want to check on your list of licenses.

4. From the Downloads page that appears (Figure 9), click a Downloads button to navigate to the Quanergy Download Center website (Figure 7) where you can upgrade Debian (*.deb) packages or download user documents and license agreements.

Figure 9. SoftwareKey Customer License Portal Downloads Page


Activate a License

If you are ready to begin using QORTEX DTC, activate the license credentials that were emailed to you from your support representative, as follows:

1. On the QORTEX DTC server’s host computer, open a terminal window (or ssh) and log in. (You may need to supply the username and password for the host machine.)

2. Execute the following command: $ sudo ./Qortex-Server --license activate

3. Respond to each prompt, and press Enter, as follows: Do you want to process your request over the internet? (y/n) [type y] Please enter your License ID: [type 8-digit license number, e.g., 12345678] Please enter your Activation Password: [type 8-digit alphanum combination, e.g., A1B2C3D4] Please enter your installation name (optional): [type site name, e.g., MyLab-2]

4. After you press the Enter key for the last question, this message returns to confirm that the license is activated: Qortex-Server license has been successfully activated.

5. Start the server’s daemon service as instructed in the “Launching the QORTEX DTC Software” section on page 39.

Figure 10. License Activate at the Command Line


Refresh a License

As long as the QORTEX DTC server is connected to the Internet, the software refreshes the license every day automatically. But you might want to deliberately refresh the license if you did any of the following:

• Activated a license, but never saw the confirmation message (Figure 10). • Renewed an annual or development kit license. • Upgraded to a Premium license. • Increased the sensor allowance.

Refresh the license as follows:


2. Check the status of the server’s daemon service; if it is running, stop the service. Refer to the “QORTEX DTC Server Stop, Start, and Status” section on page 43.

3. Execute the refresh command (Figure 11): $ sudo ./Qortex-Server --license refresh

4. Respond to the prompt, and press the Enter key, as follows: Do you want to process your request over the internet? (y/n) [type y]

5. This message returns to confirm that the license is activated: Qortex-Server license was successfully refreshed.

6. Start the server’s daemon service as instructed in the “QORTEX DTC Server Stop, Start, and Status” section on page 43.

Figure 11. License Refresh at the Command Line


Deactivate a License

Deactivating a license allows you to transfer the license from one QORTEX DTC server host machine to another.

NOTE: Even while deactivated, an annual or development kit license continues its expiration countdown without pausing.

Deactivate the license as follows:



3. Execute the deactivate command (Figure 12): $ sudo ./Qortex-Server --license deactivate

4. Respond to the prompt, and press Enter, as follows: Do you want to process your request over the internet? (y/n) [type y]

5. After you press the Enter key, the License Manager deactivates the license.

6. This message returns to confirm that the process was successful: Qortex-Server license has been successfully deactivated.

7. When you are ready to reactivate the license, follow the “Activate a License” instructions on page 32.


Figure 12. License Deactivate at the Command Line


Renew a License

It is the user’s responsibility to make sure the annual or development kit license is renewed or paid in a timely manner by contacting your support representative and supplying a new Purchase Order. It’s best to prevent the license from expiring. Expiration forces the QORTEX DTC server to shut down, which forces the QORTEX DTC client software to also stop functioning.

QORTEX DTC helps you realize when it’s time to renew by displaying the following warning notifications in the QORTEX DTC client:

First Expiration Warning

A warning appears (when the client restarts) for 9 days before the deadline: Qortex license is going to expire in [day count] day(s). Please update the license before expiration.

To keep the service running smoothly, when the license is updated as confirmed through the License Portal, the QORTEX DTC server auto-updates its end and continues running without any additional steps by you.

Final Expiration Warning

A warning appears only once to indicate that the license has expired, then terminates the QORTEX DTC application: The license has a problem. Exiting...

• Check the license report to confirm the reason that QORTEX DTC terminated, as discussed in the following “Check a License” section (page 36).

• If the license lapsed, as indicated in the return, renew it through your support representative, then activate the license as explained in the “Activate a License” section (page 32) or “Manage the License of an Air-Gapped Computer” section (page 37).


Check a License

You can check the status of your Quanergy licenses at any time by looking at the License Portal Downloads page (Figure 9). You may also get a more complete report at the command line, as follows:



3. Execute the version command, then check the return: $ sudo ./Qortex-Server --version

An invalid license returns a report with the server version, similar to Figure 13 (top). A valid license returns a report with the server version, similar to Figure 13 (bottom).


Figure 13. Invalid (top) and Valid (bottom) License, Server Version at the Command Line


Manage the License of an Air-Gapped Computer

If the server’s host computer is air-gapped, that is, with no Internet access, you need to use an offline process for managing the licenses. The offline license management process may require three separate computers, depending on whether the server and client are on the same computer (per Option 5 in Table 1):

• QORTEX DTC server’s air-gapped host computer • QORTEX DTC client’s host computer • Internet-connected computer



3. Execute the following command, typing the final verb you prefer: $ sudo ./Qortex-Server --license [activate|refresh|deactivate]

4. Respond to each prompt, and press Enter, as follows: Do you want to process your request over the internet? (y/n) [type n] To proceed without an internet connection, you need a response.xml file

Do you already have a response file? (y/n) [type n] No worries! We will walk you through obtaining your response.xml file.

For this, you'll first need to generate a request.xml file.

Please enter your License ID: [type 8-digit license number, e.g., 12345678] Please enter your Activation Password: [type 8-digit alphanum combination, e.g., A1B2C3D4] Please enter your installation name (optional): [type site name, e.g., MyLab-2] Wrote License Request to request file at:

/home/user/quanergy/qguard/license/request.xml

5. Move the request.xml file to the Internet-connected computer.

6. In a browser, navigate to this page of the SoftwareKey Customer License Portal: https://license.quanergyworks.com/solo/customers/ManualRequest.aspx (Figure 14).

7. In the Upload Request File area, click the Choose File button.

8. In the file browser that appears, select the request.xml file.

9. In the License Portal’s Upload Request File area, click the Submit button.

10. After your credentials are validated, a response.xml file will be generated by the license server and presented to you.


Figure 14. SoftwareKey Customer License Portal Manual Request

11. Download the response.xml file.

12. Move the response.xml file to your target host computer in this filepath: ~/quanergy/qguard/license/response.xml.

13. Process your response.xml file, and conduct whichever license activation, refresh, or deactivation you wish, as follows: $ sudo ./Qortex-Server --license [activate|deactivate|refresh] [Type preferred verb] Respond to each prompt, and press Enter, as follows: Do you want to process your request over the internet? (y/n) [Type n] To proceed without an internet connection, you need a response.xml file Do you already have a response file? (y/n) [Type y] Default path to the response.xml file is: /home/user/quanergy/qguard/license/response.xml If you wish to use a different path, enter the absolute path to the response.xml file; otherwise just press enter: [Press the Enter key.]

14. This message returns to confirm that the process was successful: The license was successfully [activated|deactivated|refreshed].



5. Launching the QORTEX DTC Software Now that the hardware is installed on the same Ethernet subnet, and the QORTEX DTC software is installed and licenses are activated, the QORTEX DTC software must be launched, status-checked, and customized.

Launch the QORTEX DTC Server

For the Quanergy-supplied host computers (Options 1, 3, and 4 in Table 1), the QORTEX DTC daemon service starts as soon as the computer is powered on. However, if you updated the server software, or for the user-supplied host computer (Options 2 or 5 in Table 1), launch the QORTEX DTC server daemon service as follows.

NOTE: Whenever you’re prompted, type the password for your host computer.

1. Open a new terminal window on your host computer, and execute the following command:

$ sudo reboot

The server daemon starts automatically.

2. Refer to the “QORTEX DTC Server Stop, Start, and Status” section on page 43.


Install and Start the QORTEX DTC Client

For the user-supplied host computer (Option 5 in Table 1) or virtual machine, install the QORTEX DTC client software as follows.


1. Open a new terminal window on your host computer, and execute these commands:

$ /opt/quanergy/qguard-client/Qortex-Client

The QORTEX DTC client starts, and the interface appears as shown in Figure 17 on page 43.

2. In the small dialog box (Figure 15) that also appears the first time you start the client:

• If the server and client are on separate host computers, type the QORTEX DTC server host computer’s IPv4 address (which you noted previously in the procedure that starts on page 25).

• If the server and client are on the same host computer, you can instead type the loopback address, which is always 127.0.0.1.

Figure 15. Server IPv4 Address Request


Configure the Client via global_settings.ini File

As long as the client knows the server’s IP address, the client can run according to default settings. You have the option to make those parameter values explicit or to fine-tune them through a text editor, as follows. Parameter values printed in brown (Figure 16) are editable.

1. On the client’s host computer, use a text editor to open the automatically created global_settings.ini file (in the ~/quanergy/qguard home directory) and update it:

• The qguard_server_ip parameter with the QORTEX DTC server host computer’s IPv4 address (or loopback address) is essential for client to run. It is the only parameter specified in the file by default.

• Objects, Zones, States, and Object Point Clouds are published in protobuf format by default, but if you want to specify a different format:

– Copy the publish_* section from Figure 16; paste it in the [INTERCOM] section.

– Type the preferred data-publication format for each publish_* parameter: none (default): for any category of data you don’t want published. protobuf: recommended, most efficiently published in binary data blocks. json and xml: human readable formats, not available for Object Point Clouds.

• If you plan to record data:

– Copy the [RECORDER] section from Figure 16; paste it at the end of the file.

– The dataset_directory parameter assigns ~/quanergy/qguard/datasets to be the default storage location for all new dataset recordings. If you prefer a different storage location, replace the value of default by typing the filepath to the preferred location, such as to a high-capacity external hard drive.

• If you plan to use a camera and prefer to use non-default values:

– Copy the first [PTRACK] section from Figure 16; paste it at the end of the file.

– The min_movement_before_display parameter specifies how far a trackable has to move before its track displays and potentially triggers the camera. The default value is 1 meter, and the allowable range is 0 to 200.

• If you want to specify the opacity of event zones (not exclusion zones):

– Copy the next [PTRACK] section from Figure 16; paste it at the end of the file.

– The user_defined_zone_opacity parameter is 0.2 by default, and the allowable range is 0 (completely transparent so only the zone border shows) to 1 (completely opaque so nothing within can be seen).

2. Save and close the global_settings.ini file.


[INTERCOM] qguard_server_ip = X.X.X.X ; IP address is required to connect to server’s computer ;;; Optional Settings: ;;; if you want your server to send out Objects, Zones, States, or Point Clouds publish_objects = none ; Options: none (don't publish objects)| protobuf | json | xml publish_zones = none ; Options: none | protobuf | json | xml publish_object_clouds = none ; Options: none | protobuf publish_states = none ; Options: none | protobuf | json | xml object_publisher_port = 17171 zone_publisher_port = 17172 object_clouds_publisher_port = 17173 state_publisher_port = 17178 [RECORDER] dataset_directory = default ; Assigns default filepath, or edit for another location [PTRACK] min_movement_before_display = 1.0 ; Distance a trackable must move before before its track displays and potentially triggers the camera; range is 0 to 200 meters. [PTRACK] user_defined_zone_opacity = 0.2 ; Opacity of event zones; range 0 transparent to 1 opaque

Figure 16. global_settings.ini File: Edit the Parameter Values (Defaults Values Shown)


6. Controlling QORTEX DTC Operation The QORTEX DTC server and client have very different ways of stopping and starting.

QORTEX DTC Server Stop, Start, and Status

Once daemon service is active, the server runs persistently (and restarts automatically as necessary), so you should never need to manually start or stop it. The procedures in this user guide assume the server is running. The client can connect and disconnect freely, while the server continues publishing data. But if you want to stop or start the service, here are the commands you can execute from a terminal window to control server operation.

Check Service Status: $ sudo systemctl status qortex-server.service

• If the daemon is running (the server is operational), you’ll see this return: qortex-server.service ... active (running) since <Date> Process: <number>

• If the daemon is not running (the server is not operational), you’ll see this return: qortex-server.service ... inactive (dead)

Start/Stop Daemon Service: $ sudo systemctl [start|stop] qortex-server.service

• Returns nothing if the command is successful.

QORTEX DTC Client Stop and Start

It is likely that you will need to stop and start the QORTEX DTC client with some frequency. The various ways to do so are explained in this section.

Stop the Client

There are various ways to stop the client:

1. When the client interface window is active, you can either:

• Select the Exit item from the File menu (Table 7 on page 45). • Select Ctrl+Q as a keyboard shortcut. • Select the red Stop button in the top left corner of the window.

2. If the terminal that launched the client is active, press Ctrl+C to cancel the process.

Start the Client

To start the client, execute the following command from a terminal window:

$ /opt/quanergy/qguard-client/Qortex-Client


7. Using the QORTEX DTC Client Interface When the client first starts, the Quanergy Qortex Client window appears as shown in Figure 17. The client interface consists of five areas, which are discussed in this section and called out in Figure 17.

Figure 17. Client Window on Startup

Menu Bar Mode Controls Display Area Sensor Axes TRACKING Box Viewing Controls


Menu Bar

The menu bar (Figure 18) offers some specific controls for the client. Each menu is briefly described and illustrated in Table 7.

Figure 18. Menu Bar

Table 7. Menu Bar Items

Name Image Click Item Result

File

Exit Save Settings

Quits the QORTEX DTC client application. Takes current settings and synchronizes with the server.

Tools

Set Floor Cutoff

Apply Alignment Reset Server IP

Save Background As Default Remove Default Background

Opens a Floor Cutoff window (see Image column): Type/select distance in meters from the floor to the world Origin.7 Click OK to ignore all points returned from the defined floor and below. Opens a file browser. Navigate to and select the calibration.ini file (Figure 46). Click Open to edit the file and align sensors according to the Q-View calibration. Type the IP address in the pop-up window (see Image column) to identify and select the server. After learning the location’s background to ignore it (page 55, 94), this command saves it as default. Deletes the background file that was saved in the locations folder.

7 In keeping with the mathematical Cartesian coordinate system, where the Origin is the point where X, Y, Z axes meet (0,0,0). For QORTEX DTC, the world Origin can be wherever you prefer within the given location, such as a central point among multiple sensors or the Origin of the primary sensor. Refer to Appendix 3.


Name Image Click Item Result

Camera 8

See Table 10 on page 83.

Draw Camera Draw Camera Targets Draw Camera FOV Draw Occlusion Rays Camera Following Enabled Reset Cameras

Draws yellow dot representing camera’s location. Draws yellow line from camera to tracking target. Draws yellow bounds of camera FOV around target. Draws blue rays from camera to the nearest edge of any occlusions. Enables all camera functionality. Resets the cameras to a neutral position.

Controls

Next Frame Move… Rotate… Zoom… Go To Top View Go To Side View

In Playback mode, advances one step to next frame. Enables fine movements of the point cloud. (Or press and hold the arrow keys on the keyboard.) Enables fine rotations of the point cloud. (Or press Shift and hold the arrow keys on the keyboard.) Enables fine zooming of the point cloud. (Or press Meta and hold the Up/Down arrow keys.) Resets point cloud to top-down perspective. Resets point cloud to side-facing perspective.

Help

About About Qt

States version, disclaimers, licensing information. States version, disclaimers, licensing information.

8 Only Premium license holders see this Camera menu, which enables them to work with PTZ cameras. Essentials license holders do not see this Camera menu because PTZ camera functionality is disabled.


Mode Controls

Below the menu bar are the mode controls where you can engage the Live , Playback , and Record modes (Figure 17).

Clicking the button enables that mode: the icon becomes a brighter blue, the name of the mode appears, and a blue line underscores it, but the other two modes become disabled (gray). Only one mode can be enabled at a time.

NOTE: When a mode is enabled and actively playing/recording, you cannot switch modes until after you stop the current activity.

• Live mode (Figure 19) allows you to select a sensor by “location” in order to render real-time data in the display area. Refer to the “Visualizing the Raw Data” section’s “Via Live Mode” subsection on page 58.

Figure 19. Live Mode

• Playback mode (Figure 20) allows you to select and replay a recording (“dataset”) that was saved previously on the server’s host computer in Quanergy’s proprietary QLog format. Refer to the “Visualizing the Raw Data” section’s “Via Playback Mode” subsection on page 60. Also allows you to download a ZIP file of the recording. Refer to “Share/Download Recorded Data” on page 63.

Figure 20. Playback Mode

• Record mode (Figure 21) allows you to select a sensor’s “location” and type a meaningful name for the data that will be recorded from there. Refer to “Preserving the Raw Data via Record Mode” on page 61.

Figure 21. Record Mode


Viewing Controls

To the far right of the mode controls are the viewing controls (Figure 17), which offer a quick way to control what appears in the display area. Each button reveals its name when the cursor hovers over it. When a button is active (selected), it becomes more blue. Refer to the descriptions in Table 8.

Table 8. Viewing Controls Affect What Is Displayed

Name Viewing Control Result When Toggled ON Example

Refresh View Visible and selectable only in Live mode. Removes existing tracks, updates QORTEX DTC with any settings changes, and relearns the existing background of the viewed area.

Background “learning” is discussed in the “Via Live Mode” section starting on page 58.

Top View Snaps to the two-dimensional birds-eye-view as though looking straight down on the top of the sensor.

2D top view is shown in Figure 23 left.

Side View Snaps to the two-dimensional worms-eye-view as though looking straight into the side of the sensor.

2D side view is shown in Figure 23 right.

Grid Toggles the display of a background grid’s concentric circles emanating from the sensor.

Grid lines are on in many of these images, such as Figure 22, but too dim to see easily in this user guide.

Tracking Labels

Toggles the display of the labels of all objects that have been detected and are being tracked.

Labels are shown next to the bounding boxes of every moving object in Figure 22.

Tracking Paths

Toggles the display of the paths of all moving objects.

Paths appear in Figure 22 as wobbly lines indicating where an object has been.

Untracked Points

Toggles the display of the raw point cloud static background in an aqua gradient.

Points of the straight walls and a curved structure are shown in Figure 22.


Figure 22. Client Viewing Controls Affect 3D Display

Figure 23. Client Resets to 2D Top View (left) or to 2D Side View (right)

Display Area

The display area (Figure 17) shows data collected by the sensor and generated by the software, depending on how you configured the mode controls and viewing controls.

Configuration Choices

As a result of your configuration choices, the display area may reflect real-time or recorded activity in a two-dimensional or three-dimensional perspective, and the grid, labels, paths (tracks), and points may be toggled on or off. In addition, event zones and exclusion zones may be defined, as discussed in the “Tracking Box” section discussed on page 51 and shown in Figure 17.

Tracking Path Tracking Labels Untracked Points


3D Controls

To adjust the overall view of the display area, you may also apply 3D controls via mouse and keyboard to fine-tune the display perspective as you prefer:

• To spin the display around the Z-axis (discussed in Appendix 3), hold down the left mouse button and drag left or right along a horizontal line. (Diagonal dragging is fine, too, but yields results that are not as neatly explained.)

• To adjust the perspective from birds-eye-view (above the sensor) to worms-eye-view (at the floor), hold down the left mouse button and drag up or down along a vertical line. (Diagonal dragging is fine, too, but yields results that are not as neatly explained.)

• To zoom in and out from the center of the display, rotate the mouse wheel.

• To reposition the point cloud within the visible area, take either of these actions:

– Press the keyboard Shift button and the left mouse button, then drag the mouse until the area of interest is where you want it to be.

– Press the mouse wheel, then drag the mouse until the area of interest is where you want it to be.

Object Types

QORTEX DTC classifies and tracks three types of active objects based on size and velocity: Human (low speed, human size), Unidentified (low speed, larger size), and Ignored (overly large). The client visualizes these active objects as shown in Figure 24 and described below:

• Human: a green object within a transparent yellow bounding box. • Unidentified: a larger gray object within a transparent gray bounding box. • Ignored (not shown): a huge gray object within a transparent gray bounding box.

Figure 24. Visualizes Human and Unidentified Objects

Unidentified Human


Tracking Box

Object tracking is enabled/disabled through the TRACKING box (Figure 18):

• Click its gray (disabled) toggle button so that it turns blue (enabled) .

When enabled, the TRACKING box lists all active objects as they are being tracked (monitored) over time.

• Click the button beneath the TRACKING box to refresh and restart the tracking activity.

NOTE: Do not use the button while recording, or unexpected and undesired results may occur.

When disabled, objects are not monitored, and therefore not listed in the TRACKING box.

Tracked objects that move into one of the pre-defined ZONES:

• May trigger an alert if one has been defined in one of the EVENT ZONES. • May be ignored while they are in one of the EXCLUSION ZONES.

These special zones are defined through the controls (EVENT ZONES and EXCLUSION ZONES) below the TRACKING box, and are discussed in detail in the “Working with Special Zones” section starting on page 65.


8. Handling Locations A sensor’s location must be set up and selected in order to visualize (Live mode) or record (Record mode) real-time data. Each location is associated with a single sensor or set of sensors.

The client computer’s qguard home directory ~/quanergy/qguard must include a locations directory where each specific location folder (with its related settings.ini file) is stored. The directory is set up when you “Create a New Location,” as follows.

Create a New Location

This procedure applies to a single sensor only. If you have multiple sensors installed at the target location, get started with this quick-start procedure, then adjust it as instructed in the “Accomplishing Multi-LiDAR Fusion” section starting on page 88.

Create a new location as follows:

NOTE: If you have not yet installed the Q-View application on the client computer, install it as instructed in the Q-View User Guide (https://quanergy.desk.com/customer/portal/articles/2717074).

1. Open the Q-View application, and from the Dashboard tab, view the displayed information of the sensor that is in the location that interests you. (A location is a specific surveillance area monitored by one or more sensors.) The tile of the sensor reveals the sensor’s IP address and QPxxxxxx number, where xxxxxx is the last six digits of the MAC address, as shown in Figure 25, with the leading zeros dropped.

Figure 25. Q-View Sensor Tile

2. Only one application can use the sensor at a time. If the sensor tile is in a green state as shown in Figure 25, that means you connected to it, so make sure you disconnect from it before using QORTEX DTC with that sensor. (It is not necessary to connect to a sensor in Q-View to see its information.)

Labels All Points Paths

IP address MAC address reveals sensor number is QP635


3. In the QORTEX DTC application, click the Live button, turning it from gray (disabled) to blue (enabled).

4. From the Choose a location drop-down menu that appears, choose the New location item. The Adding New Location dialog window appears, as shown in Figure 26.

Figure 26. Creating New Location

5. In the dialog window that appears (Figure 26), provide the following information:

• Location Name. Type a string of letters/numerals, such as FrontDoor, with no spaces.

• Sensor IP Address. Type the IP address on the Q-View tile (e.g., 10.1.11.212).

• Sensor Name. Type any string of letters or numerals, such as QP635 or SensorFront. (The Q-View tile’s name for the sensor is irrelevant.)

• Settings Template. From the drop-down menu, select one of the items, including Default, People Indoor, People Outdoor Long Range, or People Outdoor Short Range.

• Floor Cutoff. Type the distance in meters, such as 2.00, as measured up the Z axis from the floor to the world Origin. (This value is written into the location settings.ini file and supersedes whatever value was given in the Tools menu à Set Floor Cutoff item.)9

9 The world Origin is wherever you prefer in the location, such as a central point among sensors or the Origin of the primary sensor. Refer to Appendix 3.


6. Click the OK button to apply the changes. (Refer to Figure 27.) As a result:

• The first time you do this, a ~/quanergy/qguard/locations directory is created.

• Each time you do this, a folder that bears the location name (e.g., Inner-Office) is added within the locations directory.

• The newly created folder (e.g., Inner-Office) contains a settings.ini file that auto-populates with the particular details you supplied in the dialog window.

• Going forward, any automatically generated log files or error messages associated with this location appear in this folder.

Figure 27. Locations Directory Containing settings.ini File (Example)


Learn a Location’s Background

For each location, the QORTEX DTC client needs to learn its environment in order to know what stationary background is safe to ignore. The client can learn the environment at any time. However, the learning is optimized when the background is determined during the quietest times, allowing the client to more clearly determine what is ignorable background versus what is a human that is stationary but might move. You have choices for when and how QORTEX DTC learns a background:

1. If you don’t need a default background (perhaps because the location is visually quiet), you can allow QORTEX DTC to learn a fresh background whenever it normally would, which is described in the “Via Live Mode” section on page 58 and the “Via Playback Mode” section on page 60. There is no special action to take. However, you can always relearn the background whenever you prefer, as follows:

• From the viewing controls icons (top right corner of the client interface), select the first icon, which is the Refresh View button, to remove existing tracks, update any settings changes, and relearn the background. Refer to Table 8 on page 48 saved default background file from its Locations folder.

• Another method for relearning the environment in Live mode is discussed in the “Planned Client Disconnect” section on page 94.

2. If you want to save an optimized default background (perhaps because the background in your location doesn’t change much or is visually noisy), you can prompt QORTEX DTC to learn and save one to use instead of learning a fresh background each time. To save an optimal background, do the following:

• From the Tools menu (top left corner of the client interface), select the Save Background As Default item. When starting Live mode play or Record mode play, a notification reminds you that an existing background is being used.

3. If you want to remove a default background:

• From the Tools menu (top left corner of the client interface), select the Remove Default Background item. This action deletes the saved default background file from its Locations folder and returns you to the original scenario where QORTEX DTC learns a fresh background when needed.


4. If a sensor is missing during the background learning phase, performance can suffer if the sensor becomes connected after the background is learned, then starts publishing:

• If the software is still in a background-learning mode when a new sensor becomes available, the background is automatically relearned.

• Depending on the parameters in the settings.ini file, if a sensor connects after the background has been learned, the server will either relearn the background automatically (when relearn_background_by_new_sensor is set to true, which is default) or send a message asking the user to perform background learning again (when set to false). Data from the sensor is ignored until the background is relearned. If this is a recurring issue, the user can increase the initial delay threshold while sensors are coming up to speed before starting the background learning. (The default setting, multi_sensor_background_learning_threshold, is 20 seconds by default.)

Rename or Delete a Location

NOTE: Do not adjust the locations folder itself, but only make changes to what is inside that folder.

To clean up the name of a location, or delete obsolete or irrelevant locations:

1. From the QORTEX DTC client’s menu bar, open the File menu and select the Exit item to quit the QORTEX DTC client.

2. Open the ~/quanergy/qguard/locations directory.

3. Search through that directory to find the folders that have the location names (e.g., FrontDoor) that you want to change or delete.

4. Rename or delete the folder with the location name you don’t want.

5. Restart the client as instructed in “Install and Start the QORTEX DTC Client” section on page 40.

6. Click the Live button and check the Choose a location drop-down menu (Figure 26) to make sure the list has updated accordingly.

NOTE: If you delete the settings.ini file in a specific location folder, that location will no longer appear in the QORTEX DTC drop-down menu of locations.


Update a Location

NOTE: Do not adjust the locations folder itself, but only make changes to what is inside that folder.

To update a location, such as if one or more sensors and/or cameras have been removed (or need to be removed because of the licensing issue described in “Settings File Error” on page 96), revise its settings.ini file, as follows:

1. From the QORTEX DTC client’s menu bar, open the File menu and select the Exit item to quit the QORTEX DTC client.

2. Optional: If you have a particular scenario in mind, also check the templates directory at ~/quanergy/qguard/location_settings_examples to see example parameters for optimizing for the current location-specific settings.ini file.

3. Navigate to the ~/quanergy/qguard/locations directory and search it to find the folder with the location name (e.g., FrontDoor) that you want to update.

4. Within that location’s folder, find and open the settings.ini file.

5. Make the changes you need to, such as omitting a sensor or camera section, then save the file.

6. Restart the client as instructed in the “Install and Start the QORTEX DTC Client” section on page 40.

7. Click the Live button and check the Choose a location drop-down menu (Figure 26) to make sure the location still appears as expected.


9. Visualizing the Raw Data The client enables visualization of the server’s data in Live or Playback modes, as discussed in the next two subsections. Refer to Figure 28.

NOTE: When a mode is enabled and actively engaged, the other modes are not clickable. You cannot switch modes until after you stop the current activity.

Figure 28. Visualization of Raw Data

Via Live Mode

Live mode is for the real-time visualization of objects, tracking, and raw point clouds. To visualize in Live mode, refer to Figure 28, Figure 29, and Figure 30 while following these steps:

1. Click the Live button, turning it from gray (disabled) to blue (enabled).

2. Select a location to visualize in real-time, as follows:

Secondary Sensor Modes Primary Sensor Drop-Down Menu Mode-Specific Buttons Display Area Tracking Box


• From the Choose a location drop-down menu, select a relevant location. Every location in the menu has a matching folder in ~/quanergy/qguard/locations, which stores at least a settings.ini file, as well as any log files or error messages that have been automatically generated. And each location is associated with a primary sensor, whose XYZ axes are shown and labeled in the display area.

• To create a new location that will show up in the Choose a location drop-down menu, refer to the “Handling Locations” instructions on page 29.

3. To the right of the drop-down menu, click the Play button (Figure 29). Only sensors and any previously defined event zones and exclusion zones appear in the display area.

• Allow up to 30 seconds for the sensor to spin up.

– As the sensor wakes up, a Stop Load button with a circling spinner replaces the Play button.

– When loading is complete and current location data appears in the display area, a Pause button replaces the Stop Load button, and a Connected indicator appears to the right of the Choose a location drop-down menu.

• Allow up to 10 seconds for the software to “learn” the room and its objects. Learning is best achieved in a space that has as few people or objects moving around as possible.

Figure 29. Live Mode: Play à Stop Load à Pause à Connected

4. To pause visualization, click the Pause button. The client freezes the visualization, but the server keeps handling the data invisibly in the background.

5. To resume visualization after pausing, click the Play button. The client resets the view and immediately displays data starting with the current moment, with no need to relearn the area.

6. To stop visualization, hover over the Connected indicator until it changes to a Disconnect from Location button), then click it (Figure 30).

• The client freezes the current visualization in the display area. • The server stops learning, detecting, tracking, and classifying; enters an idle mode. • The Play button replaces the Pause button. • The other modes (through Playback and Record buttons) become selectable.

7. If you select the Play button again, the location learning and displaying starts anew.


Figure 30. Live Mode: Disconnect and Pause

Via Playback Mode

Playback mode is for the visualization (or download, discussed on page 63) of previously recorded objects, tracking information, and raw point cloud data, collectively called a “dataset.” Because each recorded dataset is segmented into timestamped “QLogs,” there may be multiple timestamped subdirectories to choose from.

• To record a dataset, refer to the “Preserving the Raw Data via Record Mode” section on page 61.

• To visualize a dataset that has already been recorded, refer to Figure 28 and Figure 31, while following these steps:

1. Click the Playback button, turning it from gray (disabled) to blue (enabled).

2. From the Choose a dataset drop-down menu, select from the alphabetically sorted list of datasets that were previously recorded and saved on the server’s host computer in the QLog format. A Download button (refer to page 63), Play button, and time counter appear.

3. To visualize the selected dataset, click the Play button:

• The recorded dataset appears in the display area. • The client “learns” the area, displaying a looping progress indicator until complete. • The time counter counts up from 00.00.00.000 until reaching the end of the recording. • A Pause button replaces the Play button.

4. To pause visualization during playback, click the Pause button:

• The client freezes at the current frame and stops incrementing the time counter. • The Play , Next Frame , and Replay from Start buttons replace the Pause button. • The other modes (through Live and Record buttons) become selectable.

Figure 31. Playback Mode: Play à Pause à Play/Step/Replay


10. Preserving the Raw Data via Record Mode The client enables the recording of the server’s real-time data when in Record mode.

NOTE: When a mode is enabled and actively engaged, the other modes are not clickable. You cannot switch modes until after you stop the current activity.

Record mode allows you to preserve the dataset from a particular time and location in order to visualize it again (“Via Playback Mode,” page 60) in the future. The datasets are saved in Quanergy’s proprietary QLog format, which is also discussed in the Q-View User Guide at https://quanergy.desk.com/customer/portal/articles/2717074. This capability enables the following flexibility:

• Other applications including Q-View can play back the QORTEX DTC recordings. • Q-View can export the Q-Logs to other formats, including PCD and LAS. • QORTEX DTC can play back recordings produced by Q-View and other applications.

Depending on the values of the parameters for storage location and recording duration (discussed in the “Configure the Client via global_settings.ini File” section starting on page 41), QORTEX DTC allows you to:

• Record as long as you prefer, because the datasets are automatically split and timestamped for full manageability and recoverability.

• Manage where recorded datasets are stored, whether that’s the default location ~/quanergy/qguard/datasets or an external hard drive (recommended).

NOTE: Make sure the hard drive has sufficient capacity. Recordings can quickly consume huge amounts of memory, so we recommend investing in an external hard drive.


Record Data

To preserve the raw data via Record mode, refer to Figure 32 and follow these steps:

1. Click the Record button, turning it from gray (disabled) to blue (enabled).

2. From the Choose a location drop-down menu, select a relevant location. Every location in the menu has a matching folder in ~/quanergy/qguard/locations, which stores at least a settings.ini file, as well as any log files and error messages that have been automatically generated. And each location is associated with a primary sensor, whose XYZ axes are shown and labeled in the display area.

3. In the Enter dataset name field that appears to the right of the Choose a location menu, type a valid and unique name for the dataset that will be recorded. As soon as you begin typing the name (e.g., Parking Lot), the Start Record button becomes enabled (red).

4. Click the Start Record button, which immediately becomes an Abort Record spinner until data visualization begins and it is replaced by a Stop Record button.

Tracking is disabled by default as the recommended state. But if you enable tracking (as discussed on page 51) while in Record mode, and begin recording, do not click the button beneath the TRACKING BOX, or unexpected and undesired results may occur.

5. Each recording is saved to the specified filepath (as discussed on page 41), with a new directory under name you just typed in the Enter dataset name field. Depending on the length of the recording, that new directory (e.g., Parking Lot) will contain multiple timestamped subdirectories (e.g., Parking_Lot_YYYY-MM-DD_HH-MM-SS).

6. Click the Stop Record button to stop recording the data.

• The recording is automatically saved on the server’s host computer. • The other modes (through Live and Playback buttons) become selectable.

Figure 32. Record Mode: Start Record à Spinner à Stop Record

Visualize Recorded Data

Visualize the recorded data through the Choose a dataset menu in Playback mode. Refer to the detailed explanation on page 60.


Share/Download Recorded Data

In Playback mode, you have the option of preserving a recording in a format that you can share with your support representative if you need any analysis and help, as follows:

1. Click the Playback button, turning it from gray (disabled) to blue (enabled).

2. From the Choose a dataset drop-down menu (Figure 31 top), select the dataset you want to share from the alphabetically sorted list of datasets that were previously recorded and saved on the server’s host computer in the QLog format.

3. QORTEX DTC can download smaller datasets of 15 GB or less to your local machine. Although a larger dataset will produce an error, you are still able to retrieve it by logging into the server’s host computer and copying it directly.

4. Click the Download button that appears to the right of the Choose a dataset drop-down menu. (If compression activity is underway, an Abort Download button to the right of the Compressing Dataset message allows you to abort, as shown in Figure 33.)

Figure 33. Playback Mode: Compress (or Cancel) Download

5. While the server compresses the entire recording into a ZIP file (an archival format that supports lossless data compression), the client shows progress bars that simulate the compression effort. This can take a while. Table 9 has sample data to provide an idea of relative times, frames, and sizes.

6. As soon as the compression is done, the server downloads a copy of the zipped dataset to the client’s ~/quanergy/qguard/datasets directory. A pop-up window reports, “Download completed.” Click the OK button.

7. Now you can email it to your customer support representative.

Table 9. Statistics of Example Recordings

Length of Recording (seconds)

Time to Compress (seconds)

ZIP File Size (MB)

60 3 55 120 6 110 180 9 160

Abort Download Button


11. Adjusting the Data Display You can control what appears in the display area and TRACKING box. Refer to Figure 28 above, as well as the description of the QORTEX DTC interface starting on page 44. Make adjustments, as follows:

1. To pay particular attention to a specific zone within a location, create an EVENT ZONES filter as discussed in the “Working with Special Zones” section starting on page 65.

2. To disable the display of points and tracks in a specific area within a location, such as a place that is legitimately busy but poses no threat and therefore no interest, create an EXCLUSION ZONES filter as discussed in the “Working with Special Zones” section starting on page 65.

3. To disable the display of points on the floor, use the Tools menu to create a “Floor Cutoff” filter as discussed in Table 7 on page 45. Resetting the Floor Cutoff value will trigger a new learning phase if Live or Playback modes are active.

4. To zoom in or adjust the view in the display area, use the “3D Controls” as discussed on page 50, and the Controls menu shown on page 45.

5. To regain situational awareness if the view becomes disorienting, click the Top View button, which snaps the display back into its familiar top-down perspective, as discussed in Table 8 on page 48.

6. To enable or disable the display of the background Grid , Tracking Labels , Tracking Paths , and/or raw Untracked Points , toggle the viewing control buttons, as discussed in Table 8 on page 48.

7. To restart the tracking activity in the TRACKING box, click the button beneath it.


12. Working with Special Zones A site’s monitored location is probably not uniformly important. Secured sites typically have areas of minimal importance as well as areas of maximal importance. This section reveals ways to treat each of those geospatial areas with appropriate consideration.

• Event zones are special surveillance areas of heightened interest and critical importance, such as near dangerous materials, valuable resources, or sensitive equipment. For such zones, you can specify automated actions for the software to take to target suspicious activities before any problems occur. This could include highlighting tracked objects or turning things (lights, alarms, and so on) on and off through an HTTP GET network command.

• Exclusion zones are areas of zero interest where you don’t want to waste any bandwidth monitoring the moving objects within it or visualizing their points, tracks, or labels. Consider creating such “dead zones” when the area poses no threat but is visually noisy with flapping flags or trees and vegetation, for example.

At any time except when the system is recording, you can enable, define, and adjust the configuration of these special areas through the EVENT ZONES and EXCLUSION ZONES dialog boxes in the lower right corner of the QORTEX DTC screen, as shown in Figure 28.

This user guide uses the ZONES interface as an example to explain both EVENT ZONES and EXCLUSION ZONES dialog options because the user interface is functionally identical (and stylistically similar), except that there are a few extra options for EVENT ZONES.

Enable and Disable Zones

To enable or disable the zone surveillance area dialog boxes, click the toggle button below the TRACKING box:

• When enabled, the gray button becomes a blue button, and configuration options are made available. Any previously defined zones are revealed in the dialog box and activated. Those zones are visualized in the display area unless its blue button was toggled to gray.

• When disabled, the blue button becomes a gray button. Zones and configuration options are temporarily hidden, deactivated, and not visualized in the display area.


Draw a Zone

To create a special zone, draw a polygon around the space as follows, referring to Figure 34:

1. In the enabled dialog area, click the plus (+) button.

2. A pop-up window with instructions appears in the display area.

3. In the display area, draw a polygon that surrounds the zone of interest, as follows:

• Single-click a starting point.

• Move the cursor, and click a second point.

• Continue to move and click until the polygon is a satisfactory shape.

• Double-click the final point to finish the polygon. (The polygon accepts more click-points until the OK button is clicked in the next step.)

• By default, the bottom of a zone is at floor cutoff unless you change that by specifying a value in the Min Z field. Min Z is the minimum height of the zone along the Z axis, which is discussed in Appendix 3. If the area of interest is above the floor (such as the top of a wall that a person might try to climb over or the upper part of a tree where branches sway the most), then type the distance in meters above the floor where the zone begins.

NOTE: In the settings.ini file, the zmax parameter establishes the Max Z (zone maximum height), which is set by default at the number representing infinity (1.7976931348623157e+308). Even if the user changes the zmax value to something smaller such as 20 meters, the change has no effect.

4. In the pop-up window, click OK to apply the polygon and dismiss the window.

• Or click the Redo button to delete and redraw the polygon. • Or click the Cancel button to delete the polygon and dismiss the window.

5. The client renders the applied polygon as a 3D shape (polyhedron), yellow for EVENT ZONES and pink for EXCLUSION ZONES. The shapes are translucent to allow the user to see the object being tracked inside the box. If the polygons are flat (Figure 23), adjust the perspective view (Figure 22) by manipulating the 3D Controls described on page 50 and the Controls menu on page 45. Click the Side View button to see zone heights.


Figure 34. Newly Drawn Polygon Zone

Zone Names


Name a Zone

You can give the zone a meaningful name. This label (whether the default name such as Zone 0 or a user-defined name such as Merchandise) appears in the display area next to its polygon, in the upper left corner of Figure 34. Follow these steps and refer to Figure 35:

1. Click the new polygon’s display arrow to show Rename and Delete in the Properties tab. 2. Click the Rename button. 3. In the Rename pop-up window, type the new name. 4. Click the OK button to apply the change and dismiss the window. 5. Click the blue APPLY ZONE CHANGES button.

Figure 35. Special Zone Rename Feature


Hide/Show a Zone

Depending on whether the visualization is in a top-down, side, or perspective view, a 2D polygon or 3D polyhedron encloses the zone. The zone is hidden or shown in the display area, controlled by a simple toggle button. Follow these steps to hide or show, and refer to Figure 36:

1. Each specific zone can be hidden or shown:

• Toggle a specific zone’s eye button to “open” so that its bounding box is shown in the display area.

• Toggle a specific zone’s eye button to “shut” and gray so that its bounding box is not visible in the display area, even though the zone is still actively functional.

2. The bounding boxes of an entire zone category can be hidden or shown at once:

• Toggle the EVENT ZONES’ or EXCLUSION ZONES’ eye button to “open” so that all bounding boxes of that zone type are visible.

• Toggle the EVENT ZONES’ or EXCLUSION ZONES’ eye button to “shut” so that all bounding boxes of that zone type are hidden even though they remain actively functional.

Figure 36. Hide/Show Zone


Adjust the Zone Distance Above the Floor

When you created a zone, as discussed in the “Draw a Zone” section on page 66, you may have set a Min Z vertical distance from the floor cutoff, above which the zone would extend to a default ten-meter height above the floor cutoff. (Z axis is discussed in Appendix 3.)

Setting Min Z can be useful if you want to track a person climbing over a fence, but ignore a person standing next to that fence, for example, or to exclude tree branches. Add or update the Min Z dimension for an existing zone, as follows, referring to Figure 37:

1. Click the Side View button to visualize the relative zone heights within the scene.

2. In the Min Z field type the distance in meters above the floor where the zone begins its vertical height.

3. Click the blue APPLY ZONE CHANGES button.

Figure 37. Zone's Relative Height above Min Z Distance

Floor cutoff

Min Z


Define an Event (For Event Zones Only) EVENT ZONES have a few more options (which are not available for EXCLUSION ZONES), including the ability to specify an event that will happen when a triggering action occurs, that is, when an object’s track moves into or out of this defined zone. Define an example event as follows, referring to Figure 38:

1. Toggle the display arrow for the zone you want to define.

2. Select its PROPERTIES tab if it isn’t already selected.

3. Click the Classification drop-down menu, and select the Event item.

4. From the Entry Action’s drop-down menu (Figure 38 left), select one of these items to enable the described effect:

• None: an object entering the zone triggers no actions.

• Network Action: command any Internet-controlled device or Internet of Things (IoT) device by clicking the Command button, typing a HTTP GET command in the pop-up window, and selecting the OK button. For example, this HTTP GET command turns a light switch on when an object enters: http://<network-switch-ip>/outlet?<number>=ON

• Highlight: that zone’s name banner is highlighted yellow when up to three objects, or red when more than three objects, move into the zone (Figure 39).

• Fixed Follow, Zone Follow, or High Priority: for these camera-related actions, see the “In a Zone Within a Location” procedure starting on page 84. (Never select Fixed Follow when multiple cameras are in use.)

• Record: Raw data records starting when an object enters the zone and ending when all objects have exited the zone. The recording saves on the server’s host computer.

5. From the Exit Action’s drop-down menu (Figure 38 middle), select one of these items to enable the described effect:

• None: an object exiting the zone continues to be treated as defined by the Entry Action, if any action was specified.

• Network Action: click the Command button, then type an HTTP GET command in the pop-up window, and select the OK button. In this example, upon exit, a light will switch off: http://<network-switch-ip>/outlet?<number>=OFF

• Stop Following: has an effect only if the camera is activated, as discussed in the “Use the Camera to Draw Attention” section starting on page 80.

6. Click the blue APPLY ZONE CHANGES button above the zone definition box to activate the changes. (The button dims.)

7. If your event zone definition is incomplete (such as if you did not add a command for a Network Action), a red or orange exclamation icon appears beside that zone’s toggle button, as shown in Figure 38 (right), along with a tool tip explaining the issue.

8. Select the zone’s Tracking tab (Figure 38 right). If any objects move through this zone, their tracking ID labels will be captured here (as well as in the primary TRACKING box) for you to investigate if you wish.


9. During a zone event, the zone data will be published to a TCP port for processing by third party applications, as discussed in Appendix 1 starting on page 99.

Figure 38. Event Zone Only: Entry Action (left), Exit Action (middle), Tracking (right)

Figure 39. Event Zone Only: Entry Action to Highlight


Delete a Zone

Delete a defined zone that you no longer want, as follows, referring to Figure 38:

1. Toggle the display arrow for the zone you want to delete.

2. Select its Properties tab if it isn’t already selected.

3. Click the Delete button. All traces of that zone disappear immediately and permanently from the display area and the dialog box.

Figure 40. Zone Deletion


13. Enabling and Using Cameras

NOTE: PTZ camera functionality is disabled for users who have activated a QORTEX DTC Essentials license. Only Premium license holders may work with PTZ cameras.

This section provides instructions for setting up a camera, viewing its output, and using it to accomplish specific tasks. A LiDAR sensor can help aid the use of cameras by giving information to:

• Draw attention to an area of interest. • Track and zoom to specific objects that are being observed in the general

surveilled area or special EVENT ZONES. • Lock to the track of one specific object, and stay with it until it is lost.

Learn about Supported Cameras

Quanergy supports Pan-Tilt-Zoom10 (PTZ) cameras that are compliant with the global standards set by the Open Network Video Interface Forum (ONVIF), Profile S (for “streaming video”). Such compliance ensures the effective interoperability of security products operating under the Internet Protocol (IP).

The following cameras have been tested with QORTEX DTC:

• AXIS Q6155-E PTZ Network Camera — Completely functional.

• HikVision DS-2DF8336IV-AEL IP Dome Camera — Only the velocity control mode works properly; in position control mode, this camera ignores the speed parameter and stops between position commands.

• FLIR Systems PT-Series (PT-625E) Thermal Camera — In position control, this camera also ignores the speed parameter but does not stop between position commands. Position control mode or velocity control mode are therefore both viable options, depending on whether fast or smooth tracking is a higher priority.

10 Pan is a sideways rotation to scan horizontally. Tilt is an up/down movement to scan vertically. Zoom is an in/out magnification of the observed frame.


Set Up the Camera

It is outside the scope of this user guide to explain exactly how to set up your camera, which is affected by the model’s capabilities, specific environment, and intended usage.

Appendix 2 (page 111) lists some ONVIF commands and their responses.

The general steps involved in setting up any QORTEX DTC-compliant camera are:

1. Understand. Check the camera’s datasheet or published specifications to understand its particular abilities, limitations, and requirements.

2. Define. In the web settings, according to camera instructions, define an ONVIF user.

3. Mount. Securely mount the camera according to the camera’s installation instructions. Some general, common sense mounting tips include placing the camera in a permanent, static location where:

• The camera will not be moved or bumped. • Both camera and LiDAR sensors share common lines of sight. • The camera and LiDAR sensors don’t block each other’s view. • No other static objects block the camera’s view.

4. Network. Connect the camera to the same subnet that the server’s host computer’s Ethernet is on.

5. Stream. Follow the camera’s instructions for assigning an IP address, accessing the video stream through a web browser, and performing any other setup procedures.

6. View. Place the QORTEX DTC client window next to the web browser displaying the camera output for maximum situational awareness and interactivity.

7. Routine. Follow all of the camera’s safety, cleaning, and maintenance instructions.


Customize the Camera Values

Cameras (and LiDAR sensors) are associated with a particular location, and their parameter values are assigned and adjusted through the location-specific settings.ini file. Update the file as follows:

1. If no location has been created for the area in which the camera is installed, refer to the “Handling Locations” instructions on page 52 to set one up.

2. Open the related locations folder in ~/quanergy/qguard/locations, where the settings.ini file is stored.

3. Open that settings.ini file in your preferred text editor.

4. Each camera needs its own section, which must begin with a [Camerax] heading. Copy and paste as many of those sections as there are cameras participating in that location.

5. Edit the camera parameter values printed in brown in Figure 41, or any other values you wish to adjust, starting with these essential values:

• Increment the number of each [Camerax] section, starting with zero.

• For the ip, password, and username parameters, type what you previously assigned in the “Set Up the Camera” section on page 75.

NOTE: Axis cameras and others that connect through Internet Protocol (ip), may disregard the port parameter. Cameras that connect through a serial port can provide the port address (/dev/ttyUSB0) and disregard the ip parameter.

• For the name parameter, type a unique nickname that makes sense to you, such as the camera type and number or location: Axis3, LobbyHikVision, or FlirSouth.

• For the offset... parameters, measure the distance from the primary LiDAR sensor’s Origin to the camera, then edit those values to adjust the position and orientation of the virtual camera as it appears in the display area relative to the primary LiDAR sensor:

– The offset_angle_degrees stays at zero if the camera (when it is in neutral position) and the LiDAR sensor look in the same direction. Adjust this estimated angular offset only if they point in different directions.

– For the offset_x_meters, measure to the right (positive) or left (negative). – For the offset_y_meters, measure in front of (positive) or behind (negative). – For the offset_z_meters, measure above (positive) or below (negative).

• For the seconds_between_commands parameter, the time in seconds must be > 0.1.

• For the type parameter, type Onvif to allow QORTEX DTC to control the camera.


• For the use_position_control parameter, type true or false:

– use_position_control=true to use the AbsoluteMove speed command, which includes a speed parameter. However, the speed parameter is ignored by some cameras (such as HikVision), causing them to make full speed moves even when a very small tracking adjustment is required, which can result in jerky movements.

– use_position_control=false to use the ContinuousMove speed command. It results in smooth motion but is limited based on the camera TCP command bandwidth and latency, and is thus slower in order to achieve stable motion.

6. You probably will not need the following parameters, but we include explanations here in case you need to fine tune the performance.

• For these parameters:

– pan_gain (how fast to command pan) – tilt_gain (how fast to command tilt) – zoom_gain (how fast to command zoom)

Use the following values:

– 1 is default. – Greater than 1 for faster than default. – Less than 1 for slower than default. – A negative number to reverse the velocity direction but should never be

required since the limits can be reversed to take care of that.

• For these parameters:

– zoom_target_width_pad (pads width of the target the camera zooms into) – zoom_target_height_pad (pads height of the target the camera zooms into)

Use the following values:

– 1.2 is default, and it is easiest if both padding parameters are the same value. – Greater than 1.2 if the image is zoomed in too much. – Less than 1.2 if the image is zoomed out too much. – Padding parameters must be greater than 0.

• Some ONVIF cameras do not supply information that is necessary for QORTEX DTC operation, so you may need to add the following parameters and values manually. These additions override any values from the camera itself, so leave them out at first and check the ~/quanergy/qguard/ptrack.log file to see if any errors resulted:

– lower_physical_tilt_limit=-90 (or 90) degree angle. – upper_physical_tilt_limit=90 (or -90) degree angle. – lower_physical_pan_limit=-180 (or 180) degree angle. – upper_physical_pan_limit=180 (or -180) degree angle.


7. There are several new parameters introduced in QORTEX DTC version 1.2, which give greater control over when and how the camera relinquishes control:

• For the control_timeout parameter, use a number value to determine how long in seconds until QORTEX stops commanding the camera to look at the last known trackable position once the trackable has disappeared and no new target is chosen:

– 1 is default. – 0 to 100 is the acceptable range.

• For the max_zone_following_distance parameter, use a number value to determine how far away in meters a zone’s closest point can be from a camera for it to be able to trigger. Refer to “Camera Track-Following Logic” on page 86.

NOTE: Cameras behave in a more intuitive way if they all ENABLE (e.g., -1 or any value less than zero), or all DISABLE (e.g., 0 or greater value) this parameter, but do not mix and match.

– -1 is default. (Any number less than zero has the identical effect.) – 0 requires the camera to be inside a zone in order to follow a trackable that

enters it. – The acceptable range of minimum and maximum values greater than zero

depends on the camera’s specifications and focal range. However, multiple cameras work better together when this parameter is set to a high value, such as 200.

• For the only_command_position_if_changed parameter, use a true or false value:

– Use true (default) to allow an uncapped number of commands to be sent to cameras.

– Use false to prevent an excessive number of commands from being sent to cameras by sending new position commands only if the position change exceeds min_delta_pan and min_delta_tilt thresholds of a specified number of degrees (values of 0 to 180 are acceptable, but 0 to 5 is practical).

• For the reset_on_timeout parameter, use a true or false value:

– Use true (default) to reset the camera to the home position after control_timeout seconds.

– Use false to leave the camera as is without commanding anything new after control_timeout seconds.

• For the retain_control parameter, use a true or false value:

– Use false (default) to stop sending commands to the camera on timeout. – Use true to continue sending commands to the camera on timeout.

8. Refer to “Appendix 2: ONVIF Camera Commands” starting on page 111 for other camera commands and options.

9. Save and close the settings.ini file.


[Camera0] camera_plane_pitch=0 camera_plane_roll=0 control_timeout=1 counter_clockwise_rotation=false ip=192.168.1.37 max_zone_following_distance=–1 min_delta_pan=0.0 min_delta_tilt=0.0 min_delta_zoom=10 min_delta_zoom_percentage=0.01 min_delta_zoom_threshold_offset=0 name=OnvifSouth offset_angle_degrees=20 offset_x_meters=—4.88 offset_y_meters=0 offset_z_meters=0.10 only_command_position_if_changed=false pan_gain=0.5 password=9999 port= unused reset_on_timeout=true reset_x=0 reset_y=0 reset_z=0 retain_control=false seconds_between_commands=0.2 tilt_gain=0.5 type=Onvif use_position_control=true username=admin zoom_gain=1 zoom_scale=50 zoom_target_height_pad=1.2 zoom_target_width_pad=1.2

[Camera1] camera_plane_pitch=0 camera_plane_roll=0 control_timeout=1 counter_clockwise_rotation=false ip=192.168.1.77 max_zone_following_distance=–1 min_delta_pan=0.02 min_delta_tilt=0.03 min_delta_zoom=1 min_delta_zoom_percentage=0.0 min_delta_zoom_threshold_offset=0 name=OnvifEast offset_angle_degrees=–70 offset_x_meters=58 offset_y_meters=32.4 offset_z_meters=4 only_command_position_if_changed=false pan_gain=2 password=9999again port= unused reset_on_timeout=true reset_x=30 reset_y=–70 reset_z=–3 retain_control=false seconds_between_commands=0.2 tilt_gain=2 type=Onvif use_position_control=true username=admin zoom_gain=5 zoom_scale=10 zoom_target_height_pad=3.5 zoom_target_width_pad=3.5

Figure 41. settings.ini Example File for ONVIF Cameras

NOTE: Although the max_zone_following_distance is -1 by default, when multiple cameras are in use, better performance is achieved by setting this parameter to a high value, such as 200.


Use the Camera to Draw Attention

The purpose of the camera is to draw attention to a specific area of interest. You can accomplish this either in a general way for a location or in a specific zone. Both of these approaches are explained in the next two sections.

In a Location

You can use a camera to draw attention to dynamic changes to the area in view, as follows:

1. Turn on the camera and wait for it to perform a power-up sequence.

2. Start the QORTEX DTC client if it is not already started.

3. Follow the procedure in the “Via Live Mode” section on page 58, where you will choose the location where the camera is mounted and activate the LiDAR sensor’s real-time visualization.

4. Make sure the camera points to the primary LiDAR sensor of that location, which is the camera’s neutral position.

5. From the client menu bar, click the Camera menu, and:

• Select the Reset Cameras item to make sure the camera starts from a neutral position.

• Select the Camera Following Enabled item so that it is checked. When this is toggled on (default is on), the Camera begins following tracked objects automatically. (If a second object enters a zone defined for camera tracking, and if there is a second Camera, it will begin following the new track while the first Camera continues following the original track.)

6. To monitor what is happening in the location, select any or all Camera menu items described in Table 10, and control the camera-to-object behavior manually as follows:

• For a specific object of interest or concern, click the object’s track11 where it appears in the main TRACKING box (Figure 43 left). The camera immediately locks on that object and pans/tilts/zooms to stay with it until it is lost, ignoring all other objects. If the alignment and offsets are accurate, the camera will:

– Keep the object (typically head to knees) centered in the camera frame. – Zoom in to enlarge the object’s image as it moves away from the camera. – Zoom out to keep the entire object in frame as the object moves closer.

11 An equivalent method for selecting an object to follow is to click directly on its bounding box.


• Notice when the locked-in camera abandons interest in the tracked object and resumes a neutral position. This happens if the track is lost in any of these ways:

– The object is immobile for at least 5 minutes (default time). – The object goes past the LiDAR sensor’s maximum range of detection. – The object is occluded (blocked) from view, such as by walking through a

door and behind a wall.

• Interrupt the camera’s tracking in either of these ways:

– Click the current object’s track where it appears in the main TRACKING box. (Track-clicking is an on/off toggle switch.) The camera will abandon interest and resume a neutral position.

– Click a new object’s track where it appears in the main TRACKING box (or a zone Tracking box). The camera immediately points to and locks on the new object.

– Click any object’s track that is not in a zone.

7. Adjust the occlusion switch rate in the global_settings.ini file, if necessary. It is easier to notice occlusions when the Draw occlusion rays item is enabled (described in Table 10). When the visual line-of-sight is blocked and...

• ...multiple cameras are available, QORTEX DTC tries to hand off to another camera. • ...there are no other cameras, the camera finds the closest track and locks on to it.

To control the occlusion switch rate (how fast QORTEX DTC jumps to a new track, which can become excessive with only one camera), add the code shown in Figure 42 to the global_settings.ini file, which is discussed in the “Configure the Client via global_settings.ini File” section on page 41, and amend the brown value as preferred.

[camera_processor] occlusion_history_frames = 160 ; prevents track switching for 160 frames

Figure 42. global_settings.ini File: Add an Occlusion Switch Delay


Figure 43. Tracking Box: Main Location (top), Zone within a Location (bottom)

Figure 44. Camera Tracking in a Zone with All Features Enabled

When a camera is following a track, a small yellow triangle appears next to that track.


Table 10. Camera Menu Items Affect What Is Displayed

Menu Item Result When Toggled ON What Is Displayed

Draw Camera Displays the camera as a yellow dot labeled with its type.

Draw Camera Targets Displays a yellow line drawn from each camera to its tracking target.

Draw Camera FOV Displays a yellow polygon boundary around the target representing the camera’s field of view.

Draw Occlusion Rays Draws blue rays from the camera to the edge of occlusions. This points out where the view is blocked by objects, structures, or walls. The example image reveals no occlusions between the camera and the tracked object.


In a Zone Within a Location

If the location is busy and cluttered with tracks, you can specify a smaller zone for the camera to target within that location (Figure 44), and define some behaviors that control the camera, as follows. Refer to Figure 38.

1. Follow the steps in the “In a Location” section above.

2. Below the TRACKING box, click the EVENT ZONES eye button, if necessary, so it is open . Previously defined event zones are now listed in the dialog box and shown in the display area.

3. If you prefer to create a new zone, follow the steps in the “Draw a Zone” section on page 66 and the “Name a Zone” on page 68.

4. Plan a zone event that dictates the preferred camera behavior when a triggering action occurs, that is, when an object’s track moves into or out of the defined zone. General ideas and steps for zone events are discussed on page 71, and a typical example for camera tracking is provided in the remaining steps of this procedure.

5. Toggle the display arrow for the zone you want to define.

6. Select the zone’s PROPERTIES tab if it isn’t already selected.

7. Click the Classification drop-down menu, and select the Event item.

8. Under the Entry Action’s drop-down menu (Figure 38 left), select one of these items to enable its described effect:

• Fixed Follow: a single camera starts following a track until the object disappears. A new object entering the zone does not override this following.

Never select Fixed Follow when multiple cameras are in use, or unexpected and undesired tracking behaviors may occur.

• Zone Follow: objects entering are tagged, and cameras attempt to follow them. The choice of which track to follow is outlined in the “Camera Track-Following Logic” section on page 86.

• High Priority Follow: similar to Zone Follow, but a special tag prioritizes between tracks in the same zone. This is useful for an off-limits area not open to everyone. Once someone enters that zone, they are tagged as high priority while in that zone. Recommended usage is to a have a large regular zone overlapping a smaller high priority zone so that a person entering the outer zone gets tracked, then upon entering the inner zone gets tagged with increased priority.

NOTE: The Entry Action may be overridden according to the “Camera Track-Following Logic” discussed on page 86 and shown in Figure 45.


9. Under the Exit Action’s drop-down menu (Figure 38 middle), select one of these items to enable its described effect:

• None: No particular effect is specified when the trackable leaves the zone. The camera simply returns to the neutral position until a new object enters the zone.

• Network Action: The camera behaves according to None behavior above, and the user-defined HTTP GET command is also accomplished.

• Stop Following: The camera returns to the neutral position when the trackable exits the zone. However, if there are other tracks in the zone, the camera aims at the next object.

10. Click the blue APPLY ZONE CHANGES button to activate the changes.

11. Select the zone’s TRACKING tab (Figure 38 right) to view the tracking ID of any objects that move through this zone. (Tracks appear in the main TRACKING box as well).


Camera Track-Following Logic

Assuming that a location may have an abundance of tracks, the software prioritizes which track a camera must follow. The logic for camera track-following varies based on the value assigned to the max_zone_following_distance parameter, which specifies the maximum distance a zone can be from a camera and still be able to trigger the camera, relative to the point of the zone closest to the camera. This parameter is specified in the settings.ini file, as discussed on page 78. Refer to Figure 41 on page 79 for an example of that file.

Anything entering a zone defined as Zone Follow or High Priority Follow, or whose track is manually clicked, gets tagged for evaluation and stays tagged even after leaving a zone that triggered the tagging. Every frame is evaluated to determine which of those trackables to track. The evaluation sequence is shown in Figure 45.

Figure 45. Camera Track-Following Evaluation Sequence


Switching Camera-Sensor Affiliation

The IP addresses of cameras used in QORTEX DTC are written into the location-based settings.ini file. If a different QORTEX DTC server (e.g., Server 2) wants to use that location and its camera (and the sensors at that location), you need to break the affiliation with the currently associated QORTEX DTC server (e.g., Server 1). Accomplish this as follows:

1. In the client GUI associated with Server 1, during Live visualization of the current location, select the Disconnect from Location button (Figure 30 on page 60).

2. Take one of these actions:

• From the Choose a location drop-down menu, select a different location that does not include the camera currently in use, then wait at least a minute for the camera to forget tracks that it may have been following and return to the neutral position.

• From the client’s menu bar, open the File menu and select the Exit item to quit QORTEX DTC.

3. The client GUI associated with Server 2 is now free to connect to that camera by defining or updating a location that includes it, as discussed in the “Customize the Camera Values” section on page 76.


14. Accomplishing Multi-LiDAR Fusion The QORTEX DTC solution also enables the monitoring of a location through the fused vision of multiple M8 LiDAR sensors. Multi-LiDAR Fusion is Quanergy's proprietary technique of combining multiple LiDAR point clouds into a single spatially aligned, time-synced 4D point cloud to aid in unique object detection, identification, and tracking through a complex environment and around corners. This section explains how to align the overlapping vision of multiple sensors.

Share the Data to Enable Fusion

For Multi-LiDAR Fusion to occur, the Q-View application must have previously saved a calibration.ini file (Figure 46) that includes only the data for aligning the particular sensors being used in the current location. Note that Q-View calibrates pairs of sensors (such as QP1324 to QP136F in this example), but saves that information as well as the inverse configuration (that is, QP136F to QP1324 in this example). To enable a fused view, follow the instructions in the subsections below.

Figure 46. Q-View calibration.ini File Example

Alignment data for QP1324 to QP136F Inverse alignment data for QP136F to QP1324

QP136F QP1324 QP136F


Create a New calibration.ini File

Make a fresh calibration, as follows:

1. Because Q-View simply adds to any existing calibration.ini file it already produced, first quit Q-View, then delete, move, or rename old Q-View calibration.ini and transform_alignment.xml12 files located in ~/quanergy/ to get them out of the way and start fresh. Then restart Q-View.

2. Use the Q-View application to calibrate pairs of sensors that are active in the shared location, as explained in the Q-View User Guide, which is downloadable from https://quanergy.desk.com/customer/portal/articles/2717074.

3. Q-View outputs a new calibration.ini file (Figure 46), and saves it in the existing ~/quanergy/ folder.

Create a New settings.ini File

Start with a fresh location, as follows:

1. On the computer hosting the QORTEX DTC client, open a terminal window, and execute the following commands:

$ cd ~/quanergy/qguard/locations

$ mkdir fusedLoc && cd fusedLoc

$ touch settings.ini

2. Use a text editor to open the settings.ini file that was just placed in the newly created fusedLoc folder.

3. The file is blank, so copy the text from Figure 47, and paste it into the file.

4. Update the items printed in brown in Figure 47, including the floor_cutoff dimension in meters. (This value as specified in this location settings.ini file supersedes whatever value was given in the Tools menu à Set Floor Cutoff item.)

5. Each sensor needs its own [sensor_name] section, so copy and paste as many of those sections as there are sensors participating in the fused view, then name them so that each section name begins with sensor.

6. Open the calibration.ini file created in the previous subsection to retrieve the information necessary to update each [sensor_name]’s specific number by its QP designation (such as QP136F) and by its IP address (such as 10.1.11.204).

12 QORTEX DTC 1.x does not use Q-View’s transform_alignment.xml file; it is used by QORTEX DTC 2.x for multi-LiDAR fusion.


7. Make sure that the number of sensor definitions ([sensor_name] sections) is exactly the same as the number of sensors referenced in the calibration file, and that each sensor defined matches its respective IP address in the calibration file.

8. Close the calibration.ini file.

9. Save and close the settings.ini file.

[POINT_CLOUD] floor_cutoff_meters=1.6 ; Distance from floor to the world Origin

[SETTINGS]

version=14 ; Leave as is

[sensor_name1] ; [sensor_name] section defines each sensor used in this location data_filename=QP136F.qXX ; Names recording by last 6 digits of sensor serial#, +increment hz=10 ; Rotation speed of the sensor so leave at 10hz

ipAddress=10.1.11.204 ; IP address of the sensor as discovered in Q-View application

minimum_distance=1 ; Where detection begins so leave this at 1 meter

model=q_m8 ; Defines the sensor model in use and only M8 (q_m8) is supported name=QP136F ; Client labels sensor by last 6 digits of its serial#

[sensor_name2] ; A second section for a second sensor in multi-LiDAR system

data_filename=QP1364.data hz=10

ipAddress=10.1.11.155

minimum_distance=1

model=q_m8 name=QP1364

Figure 47. settings.ini File: Edit Sensor Data

Update the calibration.ini File

Enable the fused view, as follows:

1. In the QORTEX DTC client, select Live or Playback mode, then select the sensors’ location from the drop-down menu.

2. Open the Tools menu and select the Apply alignment item.

3. In the browser that appears, navigate to the calibration.ini file location: ~/quanergy/calibration.ini

4. Select the calibration.ini file, and click the Open button.


5. QORTEX DTC then ingests and copies the calibration information into the settings.ini file, as shown in Figure 48.

6. The alignment data in the updated settings.ini file is then applied to the current sensors, enabling a fused view, as shown in Figure 52.

Figure 48. Moves Alignment Data from calibration.ini into settings.ini File


See the Visual Storyboard of Fusion

To give a visual sense of how a single scene is rendered according to data collected by sensors, the following sequence depicts the same top-down scene to show the single sensor view (Figure 49 and Figure 50), the multi-sensor unfused view (not recommended) (Figure 51), and the Multi-LiDAR Fusion fused view (Figure 52).

Figure 49. Scene by Single Sensor A in Position X

Each image (Figure 49 and Figure 50) reveals a single sensor collecting data from two different positions in the same room. The sensors are identified by their label and X, Y, Z axes. The shape of the room is identical, but when you compare the same points in the two figures (identified as 1, 2, 3, and 4), notice that Figure 50 is rotated 180° clockwise.

Figure 50. Scene by Single Sensor B in Position Y


Figure 51 shows the scene in an unfused view, where the view of one sensor (Figure 49) is simply superimposed on the view of the other sensor (Figure 50). The two sensors are occupying the same Origin (0,0) in the X, Y, Z coordinate system but have kept their 180° offset orientation. Look closely and notice that there is only one sensor label, which is fuzzy because the QP742 and QP73A labels are superimposed on each other. Obviously, the unfused view is confusing and unhelpful — not recommended.

Figure 51. Unfused View of Scene by Dual Sensors A & B

When the sensors’ views are “fused” through the application of calibration data, the view is determined by whichever sensor is selected to be the “primary” sensor, as shown in Figure 52, and the “secondary” sensor’s view is adjusted to match it. In this example, the secondary view was rotated 180° counter-clockwise. Now, the secondary sensor’s label appears distinctly and separately, but its X, Y, Z axes are not shown because it shares the primary sensor’s axes and coordinate system.

Figure 52. Fused View of Scene by Primary Sensor A and Secondary Sensor B


15. Disconnecting The server’s host computer is designed to run persistently through a Linux daemon service, a non-interactive background program. Even if the server exits unexpectedly, it will immediately restart its processes. The client is able to freely connect to and disconnect from the server at any time, while the server continues publishing surveillance data.

Unplanned Server Disconnect

If a process on the server side exits unexpectedly:

• The client displays a message, “The connection to the Qortex Server has been lost.” • The user clicks the OK button, and the message disappears. • Meanwhile, the server automatically restarts the software. • If the client was in the middle of visualizing a location, the user reconnects to that

location, and the client relearns that environment. • Be patient, as the reconnection process may take as long as a minute.

Planned Client Disconnect

In Live mode, the QORTEX DTC client can learn an environment at any time, but it performs optimally when the learning takes place in a quiet location where it can clearly determine what is a human that is stationary but might move, and what is background to safely ignore. Therefore, if the security implementation will occur over a long period of time in a visually noisy place such as an airport, determine when might be the best time for QORTEX DTC to learn the environment, such as when the fewest people are on the premises.

If the client must learn during a busy time, consider this follow-up plan:

1. In Live mode, let the client operate as necessary.

2. When the environment is calmer, hover over the Connected indicator until it changes to a Disconnect from Location button), then click it. See Figure 53.

The client disconnects from the server and freezes the current visualization, and the Pause button is replaced by the Play button.

3. After a few seconds, click the Play button.

4. Allow the client to relearn the environment and resume visualization.

Figure 53. Live Mode: Disconnect from Server


16. Troubleshooting Most problems have simple solutions that can be resolved as explained below.

Library Errors

While running the QORTEX DTC server, if your computer is missing some libraries, you may encounter an error.

1. If you encounter this error:

./Qortex-Server: error while loading shared libraries: libicui18n.so.52:

cannot open shared object file: No such file or directory

Execute the following command in a terminal window to install libicu52:

$ sudo apt-get install libicu52

2. If you encounter this error:

./Qortex-Server: error while loading shared libraries: libGL.so.1:

cannot open shared object file: No such file or directory

Execute the following command in a terminal window to install libgl1-mesa-dev:

$ sudo apt-get install libgl1-mesa-dev

Quanergy Folder

The QORTEX DTC server automatically creates a ~/quanergy/ folder only the very first time it starts up. If the folder somehow gets deleted and does not exist, all attempts to select a location or save settings will return errors. To remedy such a situation, restore the missing folder on the computer hosting the QORTEX DTC server, as follows:

1. Open a terminal window, and execute the following command:

$ sudo userdel quanergy

2. Reinstall the QORTEX DTC server according to the instructions in the “Install New Debian Packages” section on page 28.


Licensing

The license management process may trigger some errors, as explained below.

Activation Error 5008

After logging in to the QORTEX DTC server and activating the license key, as discussed in the “Managing the Qortex DTC License” section starting on page 29, you should see the return: Status: Activated

But if you provide a wrong License ID or Activation Password, you will see this return: Error 5008: Invalid Activation Data

This means that the License ID and/or Activation Password were not validated by the License Portal’s server. Make sure you have a valid License ID and Activation Password and are typing them correctly for activation. Refer to page “Activate a License” on page 32.

Deactivation Error 9015

After deactivating a license as discussed on page 33, if you or someone tries again to deactivate a previously deactivated license, you will see this return: Return Code = 9015 ERROR_INVALID_ARGUMENTS

Simply ignore the error because it does not change the fact that QORTEX DTC is already not functional. When you are ready to reactivate the license and resume QORTEX DTC activity, follow the “Refresh a License” on page 33.

Settings File Error

Whenever a user selects a location (Live mode) or dataset (Playback mode), the QORTEX DTC server checks the relevant settings.ini file against the current license. The server stops play and displays an error when one or more of these conditions is true:

• For a Premium or Essentials license, the number of sensor configuration sections in the settings.ini file is more than the number of sensors permitted by the license.

• For an Essentials license, the settings.ini file includes sections configuring one or more cameras, but camera control is not permitted by the license.

If you encounter an error like this, try again after employing these remedies:

• Revise the settings.ini file to meet the terms of the license, as explained in the “Update a Location” section on page 57.

• Refresh the license, as explained in the “Refresh a License” section on page 33.

• Contact your support representative, as explained in the “Any Other Issue” section on page 98.


Server Crash

The QORTEX DTC application is resilient by design. If the QORTEX DTC server crashes, the client will detect it and notify you. The server is designed to run persistently, so it will restart its service automatically. If it fails to restart for some reason, notify your support representative. Meanwhile, restart the service as follows:

1. If necessary, connect user accessories (keyboard, mouse, monitor) to the USB/HDMI inputs of the server’s host computer. (You can disconnect them later.)

2. Log in to the server’s host computer. (For QSPU, QPU-L7, and QPU Mini, the default is username user, password letmein).

3. Open a terminal window.

4. Check status of the service by executing this command: $ sudo systemctl status qortex-server.service

5. If a process number is not given, restart the service by executing this command: $ sudo systemctl start qortex-server.service

6. Check the status again (and confirm that the return includes a process number): $ sudo systemctl status qortex-server.service

Client Crash

If the QORTEX DTC client crashes, just restart it again, as explained in the “Install and Start the QORTEX DTC Client” section on page 40. The client will remember everything that has been done, so you can pick up where you left off.

Sensor Health

The QORTEX DTC API publishes a State List that includes the same sensor data that you can access without disconnecting the sensor(s) from QORTEX DTC. The Q-View and M8 Sensor Settings Management (webserver) applications provide the same sensor data, but it may be inconvenient to stop QORTEX DTC monitoring in order to connect the sensors to those applications. Refer to the “State List” section on page 104. Refer to the “Troubleshooting” section of the M8 Sensor User Guide (https://quanergy.desk.com/customer/portal/articles/2687038), which explains the Error codes.

Some issues are addressed automatically by the QORTEX DTC software. For example, if a sensor refuses to connect after three failed attempts to connect, QORTEX DTC reboots the sensor. If rebooting does not help, an error message is issued.


Version Discovery

If you need to discover the current version of the QORTEX DTC server, open a terminal window, and execute the following command:

$ sudo dpkg -l qortex-server-bundle

Remove Previous Software

If you need to remove old software in order to install a new version or reinstall the same version:

• For the user-supplied host computer (Options 2 or 5 in Table 1) or virtual machine, remove the previous server and/or client software, as follows.

• For the Quanergy-supplied host computer (Options 1, 3, and 4 in Table 1) or virtual machine, remove the previous server software, as follows.


1. Open a new terminal window (Ctrl+Alt+T) on your host computer.

2. Execute the following commands to remove the old software.

$ sudo systemctl stop qortex-server.service $ sudo dpkg -r <package-name>

Any Other Issue

Contact your support representative to create an automatic support ticket, and get the specific help you need. Provide the sensor’s serial number if appropriate.

• If you purchased your hardware and software from Quanergy, send email to [email protected] with your feedback, question, or concern.

• If you purchased your hardware and software from a value added reseller (VAR) or system integrator (SI), contact them for support.


Appendix 1: API for Port Monitoring The QORTEX DTC server publishes the following streams of data output from its processing action in a serialized format on the Ethernet network:

• Object List • Zone List • Object Point Cloud • State List

The QORTEX DTC client consumes and visualizes these streams of published data, but any number of potential third party host infrastructure applications may subscribe to it for surveillance or visualization purposes.

NOTE: TCP ports 17175 to 17177 are used for communications between QORTEX DTC client and server.

Outputs to Consume

The output data is available in three different formats Protobuf, JSON, and XML. Protobuf is recommended for most efficient use of bandwidth, and it delivers binary packages, while JSON and XML are in human-readable serial format. This appendix provides examples of each output in each available format.

Object List

The Object List output has the following characteristics:

• Available: On TCP port 17171.

• Purpose: An existing security system may wish to subscribe to this data stream in order to gain detailed information on humans in the vicinity, including their long-range movements.

• Publishes: Specific data about each detected moving object (with representations of each trackable object), including:

– Unique track ID (64-bit length). – Classification (human, unidentified, ignored). – 3D position (X, Y, Z) in meters. – Size (height, width, depth) in meters. – Velocity (X, Y, Z) in meters/second.

• Format: User selects Protobuf (preferred, Figure 54 top), JSON (Figure 54 left), or XML (Figure 54 right).


Figure 54. Object List in Protobuf (top), JSON (left), and XML (right)

Output Format

Output Example

Output Example


Zone List

When event zones and their events have been configured through the QORTEX DTC client application as discussed in this QORTEX DTC 1.x User Guide starting on page 65, the Zone List output has the following characteristics:


• Purpose: An existing security system may wish to subscribe to this data stream in order to gain detailed information on humans breaching pre-defined event zones, including their long-range movements, and to determine the handling of potential threats, such as to turn on a visual camera or sound an alarm (HTTP GET command).

• Publishes at a regular frequency of 10 Hz:

– Specific data to detect if an object’s track enters or exits a defined zone. – Optionally defined data related to alerting the host environment. – Zone objects (if used). – Polygon shape and coordinates. – List of object IDs inside a zone. (These match IDs in the Object List).

• Format: User selects Protobuf (preferred, Figure 55), JSON (Figure 56 left), or XML (Figure 56 right).

Figure 55. Zone List in Protobuf

Output Format


Figure 56. Zone List in JSON (left) and XML (right)

Output Example

Output Example


Object Point Cloud

The Object Point Cloud output has the following characteristics:

• Available: On TCP port 17173. • Purpose: A special application may subscribe to this data stream in order to

perform deep processing or advanced classification on the actual LiDAR data. • Publishes: Specific object’s point cloud (a structure of 3D points in space). • Format: Only Protobuf format (Figure 57) can handle the potentially large datasets.

Figure 57. Object Point Cloud in Protobuf

Output Format


State List

The State List output indicates the sensor’s health status during Live or Playback modes. This output has the following characteristics:


• Purpose: Administrators may subscribe to this data stream in order to monitor and resolve a Missing sensor's issue quickly, or to check a Connected sensor’s health.

• Publishes: During data collection or recording, reports a specific sensor’s current:

state of connection:

– Connected. The sensor is connected and sending point cloud information to the QORTEX DTC server. If the sensor loses its connection, it is automatically re-connected to QORTEX DTC.

– Missing. The sensor’s point cloud is missing, which could indicate a sensor malfunction or other network congestion issue.

state of health:13

– Temperature – Frame rate – NMEA status – Triggered error states14

• Error: If background learning is not successful because of empty frames, the state list publishes an error with the following message: server_state_error=Error: Empty lidar frame received while learning background.

• Format: User selects Protobuf (preferred, Figure 58), JSON, or XML.

13 For M8 LiDAR sensor Rev D5 and up, or Rev D4 with a patch updating Base firmware to 7.03. 14 Refer to M8 Sensor User Guide, “Troubleshooting” section (https://quanergy.desk.com/customer/portal/articles/2687038).


Figure 58. State List in Protobuf

Output Format


Server Ports to Monitor

Quanergy encourages the use of third party applications that directly consume the server’s outputs, which can be reappropriated in innovative ways. Figure 59 shows the M8 sensors, identified by IP address in the settings.ini file, connected to the server’s host computer. The external applications can monitor specific TCP ports on the server and access the data published there directly.

Figure 59. External Applications Access Output on Server’s Host Computer

As practical aids in that effort, Quanergy has created a port-monitoring tool (page 107) and identified a publication-confirmation utility (page 109) to implement as you wish.

Quanergy’s QORTEX DTC Application Programming Interface (API) is an Ethernet interface available on the local network where the server is running. This API delivers the data you want to see to the TCP port and in the Protobuf, JSON, or XML format that you specify in the global_settings.ini file (Figure 16), which is discussed in this Qortex DTC 1.x User Guide on page 41. In summary:

• Port 17171 publishes Object List in Protobuf, JSON, or XML (page 99). • Port 17172 publishes Zone List data in Protobuf, JSON, or XML (page 101). • Port 17173 publishes Object Point Cloud data only in Protobuf (page 103). • Port 17178 publishes State List data in Protobuf, JSON, or XML (page 104).

Host Computer

:17171 — Object List :17172 — Zone List :17173 — Object Point Cloud :17178 — State List

— Pipeline Data — Websockets (controls)


Port-Monitoring Tool

As an example to use or adapt, Quanergy offers a port-monitoring tool called the qortex_listener (Listener).

In this tool, the Listener’s main routine — where the code starts executing — exhibits the process flow; it is shown in Figure 60 in case you prefer to create, for example, your own human alert system using the Object List data. In brief, the Listener simply uses standard sockets to connect to a port on the server’s host computer and process messages that are published there.

/* Start here - THESE ARE JUST CODE SNIPS. PLEASE SEE SOURCE APPLICATION. */

int main(int argc, char **argv)

/* socket: create the socket */

sockfd = socket(AF_INET, SOCK_STREAM, 0); /* Get the server's Internet address:port, then connect our socket to the port */

connect(sockfd, (struct sockaddr *) &serveraddr, sizeof(serveraddr))

/* Wait for messages and process them */

processMessage( sockfd );

/* Every message is preceded by a 4 byte message length, including JSON & XML */

int bytecount = recv( theSocket, messageBuffer, 4, 0 );

/* Process the 'protobuf' message, then wait for next */

if (qobjarr.ParseFromArray( messageBuffer, bytecount )) {

/* If the format is 'protobuf' use the built-in parser to display the data */

std::cout << "Parsed QObjects: " << qobjarr.object_size() << " " << qobjarr.DebugString();

}

else {

/* If the data is serial text data, just output the text */

std::cout << "Parsed text object: " << messageBuffer << std::endl;

}

Figure 60. Port-Listening Tool qortex_listener Main Routine


Request

To request the source code for study or implementation, email [email protected] with the subject Request qortex_listener.

Requirements

There are a few requirements before you can use the Listener.

1. Make sure you have the following set up:

• CMake >2.8.1 • Boost >1.52 • Protocol Buffers v3.5.0 Development Library

(https://github.com/google/protobuf/releases/tag/v3.5.0)

2. To install the new Protobuf 3.5.0 library, open a terminal window, and execute the following commands:

$ ./configure

$ sudo make

$ sudo make install

3. Access the source_code/build, and execute the following command to refresh the system environment:

$ sudo ldconfig

Build

To actually build the tool, use the make file (included in the source code) on a machine with a C++ compiler.

1. Clone the repository into a directory.

2. Build the application in that directory by executing the following commands:

$ mkdir build && cd build

$ cmake ..

$ make

The tool will run on any PC, operating system, or any other node on the network as proof that any third party can get the data that is output from QORTEX DTC.


Execute

Start the Listener as follows, providing the IP address and port number of the server’s host computer (Figure 16), and specifying the type of content you expect:

$ ./qortex_listener [--host ip] [--port port_number] [-t output_type]

If these parameters are not provided, then by default the Listener tries to connect to localhost (127.0.0.1) on port 17171, where the Object List is output.

When the command is executed, the Listener establishes a TCP socket connection and monitors the specified TCP port to directly consume the live (real-time) data and print it to the terminal window in whichever format is specified in the global_settings.ini file.

Use the following executable commands, with the variable (user-specified server’s host computer IP address) in brown:

For detected objects: $ ./qortex_listener -h x.x.x.x -p 17171 -t qobject For defined zones: $ ./qortex_listener -h x.x.x.x -p 17172 -t qzone For the current sensor status: $ ./qortex_listener -h x.x.x.x -p 17178 -t qstate For the point cloud: $ ./qortex_listener -h x.x.x.x -p 17173 -t pointcloud

Stop

Execute the usual Ctrl+C command to terminate the Listener.

Publication-Confirmation Utility

The netcat utility has a similar function as the Listener in bypassing the client to verify that the server is publishing serial streams. However, it only works for human readable formats (JSON and XML), not for binary (Protobuf). Use PuTTY for Windows®.

Use the netcat utility as follows:

1. Open a terminal window.

2. To monitor the TCP port where serial data is being published, edit this netcat (nc) command to include the IP address of the server’s host computer (refer to Figure 16) and the desired port number, then execute it:

$ nc x.x.x.x 1717x

If serial data is being published on that port, it prints directly to the terminal window.

3. After data starts flowing (and assuming the zones and objects are active), you can execute the usual Ctrl+C command to terminate the process.


Command Alternatives to Client GUI

Users who prefer to communicate with the QORTEX DTC server via the API may execute terminal commands to accomplish the same essential functions related to handling backgrounds as are enabled through the client GUI. The following subsections provide the API-equivalent commands.

NOTE: These API commands are only available when the QORTEX DTC application is operating in Live mode.

Background Save

In a terminal window, execute the following command to learn the background and save it as the default background, where xxx is the location name (without any spaces), such as Inner-Office. If the execution overwrites a previously saved default background, the server outputs a message in the log file.

$ ./Qortex-Server --location xxx --background save --mode live

Background Load

In a terminal window, execute the following command to load the default background if one has been saved. If one does not already exist, the server outputs a message in the log file, learns the background, and uses it.

$ ./Qortex-Server --location xxx --background load --mode live

Background Learn

In a terminal window, execute the following command to learn (and use) the background even though a default background may already have been saved before.

$ ./Qortex-Server --location xxx --background learn --mode live

Help

In a terminal window, execute the following command to return a quick, comprehensive list of command-line parameters.

$ ./Qortex-Server -h


Appendix 2: ONVIF Camera Commands

NOTE: PTZ camera functionality is disabled for users who have activated a QORTEX DTC Essentials license. Only Premium license holders may work with PTZ cameras.

QORTEX DTC is a client of ONVIF services and supports Web Services Security (WSS) digest authentication. The commands and parameters included in this appendix are supported by ONVIF cameras for the best PTZ camera control. Refer to your ONVIF camera's user guide for more information about how to use these commands.

In order for these commands to work, you may need to add and specify parameters in the location-specific settings.ini file, as discussed in the “Customize the Camera Values” section starting on page 76. Each command’s expected return is listed below.

PTZ Service Commands AbsoluteMove — Camera should support the input speed parameter, but some cameras ignore it. If the speed parameter is ignored, you can:

• Continue anyway, but the camera tracking may be choppy because it does full speed moves even when a very small tracking adjustment is required.

• Use ContinuousMove instead, which limits the available speed response based on the camera bandwidth, resulting in a smoother but slower response.

ContinuousMove — Is not used if use_position_control=true in the settings.ini file.

GetStatus — Camera returns pan, tilt, and zoom in mapped space (usually -1 to 1).

GetConfigurations — Returns at least one configuration, and QORTEX DTC uses the first one. The camera fills in the configuration token.

GetConfigurationOptions — The camera fills in the following: • AbsolutePanTiltPositionSpace (in mapped spaced). QORTEX DTC assumes this is

the first space. XRange min/max, YRange min/max. • AbsolutePanTiltPositionSpace (in angle space). If this is not provided, it needs to

be set in the settings.ini file. QORTEX DTC cannot control the camera without it and will print an error to the log. XRange min/max, YRange min/max.

• AbsoluteZoomPositionSpace. XRange min/max.

Device Service Commands GetSystemDateAndTime — The camera returns UTCDateTime. SetSystemDataAndTime — The camera accepts manual UTC time.

Media Service Commands GetProfiles — Returns at least one profile, and QORTEX DTC uses the first one. The camera fills in the profile token.


Appendix 3: Cartesian Coordinate System To properly configure the QORTEX DTC, you need a basic mathematical understanding of the Cartesian coordinate system for defining 3D locations in space. A quick way to remember the correct orientation of the axes defining the coordinate system is by the right-hand rule, which is shown in Figure 61 (left):

• The index finger points forward for the positive X axis. • The middle finger points to the side for positive Y axis. • The thumb points up for the positive Z axis. • The Origin point (0, 0, 0) is on the palm.

Every object being profiled must share the same frame of reference, that is, the same X axis, Y axis, Z axis, and Origin so that a 3D description in meters (X, Y, Z) expresses precisely one location, such as (3.2, 1.9, -1.8).

In the M8 LiDAR sensor’s coordinate system, as shown in Figure 61 (right):

• The front area of the sensor points toward positive X. The sensor cable in the back points toward negative X.

• Through the center of the center, perpendicular to the X axis, the right side points toward positive Y. The left side points toward negative Y.

• The top flat face of the sensor points toward positive Z. The bottom face of the mounting base points toward negative Z.

• For each sensor, the three axes converge internally at the point of Origin (0, 0, 0).

Figure 61. Coordinate System: Right-Hand Rule, M8 Sensor


Index

3 3D

controls ............................................................................ 50 definition .......................................................................112

4 4D point cloud ....................................................................... 88

A accessories .................................................... 16, 18, 25, 50, 97 adjust display ........................................................................ 64 air-gapped host ...............................................................29, 37 alarm ...................................................................... 11, 65, 101 API ................................................................................ 99, 106 architecture ............................................................................ 12 area of interest .................................................... 13, 50, 74, 80

B background ................................................ 13, 45, 55, 94, 110

C calibrate multiple sensors ...............................................11, 88 calibration.ini file ..................................................... 13, 45, 88 camera ................................................................................... 46

attention .......................................................................... 80 commands .....................................................................111 mount .............................................................................. 75 network ............................................................................ 75 parameter values .................................................... 76, 111 sensor affiliation .............................................................. 87 stream .............................................................................. 75 track .................................................. 46, 71, 78, 80, 84, 86 view .................................................................................. 75 zone ................................................................................. 84

classify objects ....................................................................... 14 client

crash ................................................................................. 97 disconnect ........................................................................ 94 download Debian............................................................. 26 host computer .................................................................. 17 interface ........................................................................... 44 launch .............................................................................. 40 operate ............................................................................. 43

package name ................................................................. 27 purpose ........................................................................... 14 remove old ...................................................................... 98

contact ...................................................................................... 2 coordinate system ............................................................... 112 copyrights ................................................................................ 2 crash, system ........................................................................ 97

D daemon service ......................................................... 39, 43, 94 dataset .................................................................................. 60

compression .................................................................... 63 directory .......................................................................... 63 download ........................................................................ 63

documents ...................................................................... 15, 26

E error

library .............................................................................. 95 license ............................................................................. 96 messages .................................. 54, 59, 62, 77, 94, 97, 104

Essentials license .............................................. 29, 74, 96, 111 event zones ....................................................... 65, 80, 84, 101 exclusion zones ..................................................................... 65

F features ................................................................................. 11 file

calibration.ini ...................................................... 13, 45, 88 global_settings.ini ............................................ 41, 81, 106 response.xml ................................................................... 37 settings.ini................................ 13, 52, 54, 57, 76, 89, 111

Floor Cutoff ............................................ 45, 53, 64, 66, 70, 89 folder, Quanergy ................................................................... 95 fused view ....................................................................... 88, 92

G global_settings.ini file ............................................ 41, 81, 106

H hard drive, external ......................................................... 17, 61 headless .......................................................................... 16, 18 highlight ......................................................................... 65, 71 home directory ...................................................................... 52


host computer .................................................................17, 25 HTTP GET ........................................................... 11, 65, 71, 101

I IP address .................... 25, 40, 41, 45, 52, 53, 75, 87, 89, 106 ISO certified ............................................................................. 2

J JSON ................................................................................14, 99

K keyboard controls .................................................................. 50

L Legacy Systems ...................................................................... 11 library error ............................................................................ 95 license

activation .......................................................................... 32 credentials .................................................................29, 31 deactivation ..................................................................... 34 duration ........................................................................... 29 errors ................................................................................ 96 essentials ......................................................................... 29 expiration ...................................................................34, 35 number of sensors ........................................................... 29 offline management ........................................................ 37 payment ........................................................................... 35 portal ................................................................... 30, 35, 37 premium .......................................................................... 29 refresh .............................................................................. 33 renew ............................................................................... 35 report .........................................................................31, 36 transfer ............................................................................. 34 update .............................................................................. 35

Linux ...................................................................................... 18 Listener ................................................................................107 live mode ............................................................................... 58 location

background ...................................................................... 55 camera ............................................................................. 76 creation ............................................................................ 52 deletion ............................................................................ 56 folder ..........................................................................45, 54 rename ............................................................................. 56 update .............................................................................. 57

log files ..................................................................... 54, 62, 77

M measure objects .................................................................... 14

memory ................................................................................ 61 mouse controls ..................................................................... 50 Multi-LiDAR Fusion ................................................... 11, 88, 92 multiple sensors ................................................................... 88

N netcat utility ........................................................................ 109 network ..................................................................... 12, 13, 25 Network Action ...................................................................... 71

O Object List ......................................................... 11, 14, 99, 106 Object Point Cloud ......................................... 14, 99, 103, 106 ONVIF ...................................................................... See camera Origin ............................................................................ 45, 112 outputs .................................................................... 14, 99, 106

P password

Quanergy-supplied computer ......................................... 97 to activate a license ................................................... 31, 32

PC host computer ............................................... 18, 24, 26, 30 peripherals ............................................................................ 18 persistence ...................................................................... 11, 13 playback mode...................................................................... 60 port-monitoring tool ........................................................... 107 ports, TCP ................................................................ 72, 99–110 power ........................................................................ 12, 23, 25 Premium license ............................................... 29, 74, 96, 111 Protobuf .................................................................... 14, 41, 99 ptrack.log .............................................................................. 77 PTZ........................................................................... See camera publication confirmation .................................................... 109 published data ...................................................................... 99 purpose, Qortex DTC ............................................................. 11 PuTTY utility......................................................................... 109

Q qguard_protobuf_listener ................................................. 107 QLog .......................................................................... 60, 61, 63 QPU Mini ...................... 15, 17, 18, 23, 24, 26, 27, 28, 30, 97 QPU-L7 ............................................. 15, 17, 18, 21, 26, 30, 97 QSPU ................................................ 15, 17, 18, 19, 26, 30, 97 Qt license .............................................................................. 46 Quanergy folder, restoring ................................................... 95 Q-View ............................................................................. 52, 61


R range of detection ...........................................................11, 17 recommendation .................................... 12, 13, 16, 17, 18, 61 record

formats ............................................................................. 61 memory ............................................................................ 16 mode ................................................................................ 61 storage location ............................................................... 41

reset tracking ...................................................................51, 62 response.xml file ................................................................... 37 return pulses ......................................................................... 13 right-hand rule ....................................................................112

S sensor

connection .....................................................................104 health .............................................................................104 IP address ......................................................................... 52 location ............................................................................ 52 MAC address .................................................................... 52 serial number ................................................................... 52

server crash ................................................................................. 97 disconnect ........................................................................ 94 download Debian............................................................. 26 host computer .................................................................. 17 launch .............................................................................. 39 license .............................................................................. 29 outputs .............................................................. 14, 99, 106 package name .................................................................. 27 persistent ......................................................................... 94 purpose ............................................................................ 13 remove old ....................................................................... 98

settings template................................................................... 53 settings.ini file ............................... 13, 52, 54, 57, 76, 89, 111 shut down .............................................................................. 35 social media......................................................................... 2, 3 State List ...................................................14, 97, 99, 104, 106 subscribe to data streams ................................................14, 99 support representative ........ 2, 29, 30, 32, 35, 63, 96, 98, 108

T TCP ports ................................................................. 72, 99–110 template, settings.................................................................. 53

third party processing ....................................... 12, 72, 99, 106 timestamp ....................................................................... 60, 61 tracking .................................................. 11, 14, 51, 62, 65, 86

U Ubuntu ............................................................................ 18, 25 user documents .................................................................... 15 username, Quanergy-supplied computer ............................ 97 utility

netcat ............................................................................. 109 PuTTY ............................................................................. 109

V version ..........................................................13, 26, 36, 46, 98 Video Management System (VMS) ........................... 11, 12, 29 viewing controls .............................................................. 48, 50 virtual machine ................................................... 17, 18, 26, 30 vision overlap ........................................................................ 88 visualization

adjustment ...................................................................... 64 live mode ........................................................................ 58 playback mode ................................................................ 60 recorded .......................................................................... 61

W weather ........................................................................... 11, 12 WSS ..................................................................................... 111

X X, Y, Z axes .......................................................................... 112 XML ................................................................................. 14, 99

Z ZIP file ................................................................................... 63 zone

deleting ........................................................................... 73 displaying ........................................................................ 69 drawing ........................................................................... 66 event defining ................................................................. 71 height .............................................................................. 70 naming ............................................................................ 68 of interest ........................................................................ 14 recording ......................................................................... 71

Zone List output ....................................... 14, 72, 99, 101, 106

Quanergy Systems, Inc. 482 Mercury Drive Sunnyvale, CA 94085-4706 http://quanergy.com

For purchases made directly from Quanergy: contact [email protected].

For purchases made from a third party such as a value-added reseller or system integrator: contact them for support.

Specifications are subject to change without notice.

The Quanergy logo is a trademark of Quanergy Systems, Inc. All other trademarks or registered trademarks are the property of their respective owners.