Command line

Introduction

Qinertia features a powerful Command Line Interface (CLI) to easily integrate Qinertia GNSS/INS post processing with third party software. Power users can also use Qinertia CLI to automate processing tasks, batch process logs and optimize their overall processing workflow.

Qinertia CLI is a pure command line application with no GUI at all. It runs quietly and never asks the user to interact with it. It has been designed for computer to computer interaction but can also be easily used by human beings.

Qinertia CLI is available on Windows, Linux and Mac OS X platforms and is a standard feature for all Qinertia licenses. However, a specific OEM integrator license and agreement is required if you would like to resell or package Qinertia in your software. Please contact your sales representative for more information.

CLI Concepts

Qinertia CLI relies heavily on JSON files to describe jobs to do but also to get status and feedback. JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is both human and computer friendly. You can find more information at https://www.json.org/

To use Qinertia CLI you have to prepare a processing job using a JSON file and then launch this job using the dedicated Qinertia CLI application. All the steps are then executed automatically such as importing data, downloading base stations, processing the mission and exporting the results. During this process, Qinertia CLI returns progress and status information using JSON lines format through the pipe.

Finally, when Qinertia CLI has done the processing, several processing reports in JSON or PDF format can bee generated to provide an extensive feedback on how the processing went.

Qinertia CLI application

The Qinertia CLI application is shipped with standard Qinertia installation package so power users can write complex scripts to automate processing with Qinertia. On Windows, if you have used the default installation path, you should find the binary at:

C:\Program Files\SBG Systems\Qinertia\bin\qinertia-cli.exe

CLI options

You can display a full help that lists all available options by simply typing:

qinertia-cli.exe --help-all

You should get the following output:

Usage: qinertia-cli [OPTIONS] SUBCOMMAND

Options:
  -h,--help                             Print this help message and exit
  --help-all                            Expand all help
  -v,--version                          Display program version information and exit

Subcommands:
process
  Process a project using settings defined in the specified json process file.
  Options:
    -u,--user <username>                  Username
    -p,--password <password>              Password
    --license <license>                   License key or path to an offline license file
    --status-output <name>                A pipe name, stdout or stderr
    --process-file <file> REQUIRED        Path to a command line process file
    --output <directory>                  Path to a directory where exports should be stored
    --input <directory>                   Path to a directory where input files files should be taken from
    --project <directory>                 Path to a directory where project should be saved
    --logs <file>                         Write session logs into <file>
    --overwrite-output                    Overwrite existing outputs

host-id
  Prints licensing host id.

login
  Authenticates with user/pass, caching the auth token.
  Options:
    -u,--user <username> REQUIRED         Username
    -p,--password <password>              Password

logout
  Logout any connected user. Clear cached auth tokens.

Exit Codes

The Qinertia CLI application only implement two exit codes. The exit code should be checked by the calling application or script to easily know if a processing has succeeded or failed. Please find below a short description for each exit code.

Exit Code	Description
0	The processing has been done completely and all steps such as exports or report generation has been executed. You should however, still check the generated processing report to validate data quality.
-1	The processing has failed at some point. More details have been reported over the console and/or in the log files. No processing report has been generated.

OEM Packaging

The Qinertia CLI application is available for Windows, Linux and Mac OS X platforms. You can easily ship Qinertia CLI with your application to integrate a professional GNSS/INS post processing solution within an automated and complex workflow.

You can either rely on the Qinertia installer using the quiet mode or manually copy the Qinertia directory into your own installation package.

Please feel free to contact SBG Systems support@sbg-systems.com team.

OEM Licensing

The standard Qinertia license lets end users access Qinertia CLI to create automated processing scripts. However, OEM integrators need a specific Qinertia license to be authorized to resell and package Qinertia CLI. Please contact SBG Systems sales@sbg-systems.com team for more information.

License & Authentication

Before you can process a log, Qinertia has to make sure you have a valid license. Qinertia CLI supports both online and offline licenses. However, please keep in mind that a specific license is needed to use Qinertia CLI.

Online mode

This is the recommended way to use Qinertia CLI, you have to provide your credentials username and password and optionally the license id to use.

To do so, you can either provide in each command line call your credentials and optionally the license id to use as shown in the example below:

qinertia-cli process --user jdupont@gmail.com --password tintin --license XFG5D8Z46A --process-file demoUav.json

Or you can enter your credentials only once and let Qinertia cache the authentication information. You can then omit the login in subsequent calls until you explicitly logout:

qinertia-cli login --user jdupont@gmail.com --password tintin

You can logout at any moment by typing the following command:

qinertia-cli logout

Offline mode

In this case, you simply have to provide the license file path each time you call Qinertia CLI. This is done using thee --license option as shown in the example below:

qinertia-cli process --license C:\\MyApplication\myQinertiaLicense.lic --process-file demoUav.json

You can also easily request your computer host-id using the command line by typing the following command:

qinertia-cli host-id

You should get a code such as 01ab392d239567 that identifies your computer hardware. The host id is required if you would like to generate an offline license in https://license.sbg-systems.com management platform.

Please read the How to use Qinertia offline page to learn how to generate an offline license file for a specific host id.

Processing a mission

Qinertia CLI needs a JSON processing file that describes the whole processing job. Please read the Process file documentation to learn how to write this file.

Options

The command process is used to execute a processing job. This command offers several options to ease the integration as describe below:

Option	Optional	Description
--user		Qinertia user name credentials used to check for license validity. See license and authentication
--password		Qinertia user password credentials used to check for license validity. See license and authentication
--license		Optionally specify a license id to use, this is only relevant if you have more than one valid Qinertia license. See license and authentication
--process-file		Path to the JSON Process file that describe the job to execute.
--input		You can define a base path to use for all input files that use a relative path. The input files are data you import for example.
--output		You can define a base path to use for all output files that use a relative path. This option will affect exported data as well as published processing reports.
--status-output		Enable JSON lines status output information over either the `stdout` or `stderr` pipe. The calling process can monitor in real time Qinertia CLI progress and status. Please see Status output for more details.
--project		You can provide a path where Qinertia CLI can create and store a standard Qinertia project. This project can then be opened using Qinertia GUI to review the data and for troubleshooting. If this option is not provided, Qinertia CLI do the processing and only store exported data and reports. All temporary data is deleted and no Qinertia GUI project is created.
--logs		You can provide a file to store Qinertia CLI application logs.
--overwrite-output		If specified, Qinertia CLI is allowed to overwrite any existing file with no warning or request. If not specified, Qinertia CLI will never overwrite an existing file and rather stop the processing.

Example

The following command line process a log and monitor the progress using JSON line output on stdout. All the input files, using a relative path in the JSON Process file, are read from /home/qinertia/data folder. All output files such as exported data and generated PDF processing reports are stored in /home/qinertia/results folder. The Qinertia CLI application log files are stored in the /var/log/qinertia directory. Finally, no user credentials are provided as the application has been already granted using the login command.

./qinertia-cli process --license GH3XFV4MPO --process-file /home/qinertia/job/jobProcess.json --input /home/qinertia/data --output /home/qinertia/results --status-output stdout --logs /var/logs/qinertia

If everything went well, you should get the following output:

{"category":"licensing","type":"info","payload":{"message":"Fetching available licenses ..."}}
{"category":"licensing","type":"info","payload":{"message":"Fetching license GH3XFV4MPO ..."}}
{"category":"creation","type":"import","payload":{"progress":0}}
{"category":"creation","type":"import","payload":{"progress":14}}
{"category":"creation","type":"import","payload":{"progress":22}}
{"category":"creation","type":"import","payload":{"progress":29}}
{"category":"creation","type":"import","payload":{"progress":40}}
{"category":"creation","type":"import","payload":{"progress":50}}
{"category":"creation","type":"import","payload":{"progress":61}}
{"category":"creation","type":"import","payload":{"progress":71}}
{"category":"creation","type":"import","payload":{"progress":78}}
{"category":"creation","type":"import","payload":{"progress":87}}
{"category":"creation","type":"import","payload":{"progress":90}}
{"category":"creation","type":"import","payload":{"progress":90}}
{"category":"creation","type":"import","payload":{"progress":93}}
{"category":"creation","type":"import","payload":{"progress":97}}
{"category":"creation","type":"import","payload":{"progress":100}}
{"category":"creation","type":"import","payload":{"progress":100}}
{"category":"creation","type":"info","payload":{"message":"Downloading global GNSS resources ..."}}
{"category":"baseStation","type":"info","payload":{"message":"Importing local base stations ..."}}
{"category":"processing","type":"preprocess","payload":{"progress":0}}
{"category":"processing","type":"preprocess","payload":{"progress":0}}
{"category":"processing","type":"preprocess","payload":{"progress":0}}
{"category":"processing","type":"preprocess","payload":{"progress":5}}
{"category":"processing","type":"preprocess","payload":{"progress":5}}
{"category":"processing","type":"preprocess","payload":{"progress":11}}
{"category":"processing","type":"preprocess","payload":{"progress":17}}
{"category":"processing","type":"preprocess","payload":{"progress":17}}
{"category":"processing","type":"preprocess","payload":{"progress":23}}
{"category":"processing","type":"preprocess","payload":{"progress":23}}
{"category":"processing","type":"preprocess","payload":{"progress":28}}
{"category":"processing","type":"preprocess","payload":{"progress":28}}
{"category":"processing","type":"preprocess","payload":{"progress":31}}
{"category":"processing","type":"preprocess","payload":{"progress":31}}
{"category":"processing","type":"preprocess","payload":{"progress":35}}
{"category":"processing","type":"preprocess","payload":{"progress":35}}
{"category":"processing","type":"preprocess","payload":{"progress":39}}
{"category":"processing","type":"preprocess","payload":{"progress":39}}
{"category":"processing","type":"preprocess","payload":{"progress":43}}
{"category":"processing","type":"preprocess","payload":{"progress":46}}
{"category":"processing","type":"preprocess","payload":{"progress":50}}
{"category":"processing","type":"preprocess","payload":{"progress":53}}
{"category":"processing","type":"preprocess","payload":{"progress":58}}
{"category":"processing","type":"preprocess","payload":{"progress":62}}
{"category":"processing","type":"preprocess","payload":{"progress":64}}
{"category":"processing","type":"preprocess","payload":{"progress":67}}
{"category":"processing","type":"preprocess","payload":{"progress":71}}
{"category":"processing","type":"preprocess","payload":{"progress":75}}
{"category":"processing","type":"preprocess","payload":{"progress":79}}
{"category":"processing","type":"preprocess","payload":{"progress":85}}
{"category":"processing","type":"preprocess","payload":{"progress":89}}
{"category":"processing","type":"preprocess","payload":{"progress":93}}
{"category":"processing","type":"preprocess","payload":{"progress":93}}
{"category":"processing","type":"preprocess","payload":{"progress":93}}
{"category":"processing","type":"preprocess","payload":{"progress":100}}
{"category":"processing","type":"preprocess","payload":{"progress":100}}
{"category":"processing","type":"process","payload":{"backward":{"currentPass":1,"numPass":3,"passProgress":0,"progress":0},"forward":{"currentPass":1,"numPass":3,"passProgress":2,"progress":0}}}
{"category":"processing","type":"process","payload":{"backward":{"currentPass":1,"numPass":3,"passProgress":3,"progress":1},"forward":{"currentPass":1,"numPass":3,"passProgress":2,"progress":0}}}
{"category":"processing","type":"process","payload":{"backward":{"currentPass":1,"numPass":3,"passProgress":3,"progress":1},"forward":{"currentPass":1,"numPass":3,"passProgress":6,"progress":2}}}
.....

JSON Process File Path

The --process-file option is not affected by the --input option and if you provide a relative path, it will be from the calling process working directory.

Example Projects

You can find Qinertia CLI example projects on a dedicated GitHub repository. Please make sure to select the right demo package version according to the Qinertia CLI version you are running.

Downlpad Example Projects

Download PDF