Qimera Command

Overview

qimera-command is a utility that exposes a simplified subset of Qimera's processing abilities via a command line interface for the purposes of scripting. While the full, graphical version of Qimera will always provide a richer processing experience, scripting parts of their processing workflow may make sense for organisations with very formalised and/or repetitive procedures. In most cases, qimera-command will be used to automate the preparation of a project to do as much of the busy work as possible before a human operator takes over processing, inspection and cleaning in the graphical Qimera interface.

qimera-commandprovides a subset of Qimera's features. While this feature set will likely grow in later releases, not all of Qimera's abilities are capable of being exposed in qimera-command. There are two ways to invoke qimera-command to execute jobs: Single command mode or configuration mode.

In single command mode, a single processing job will be executed and more complex processing workflows can then be built up by executing several jobs in series via a sequence of qimera-command commands.

In configuration mode, a JSON configuration is provided to qimera-command and each job specified will be executed, with shared parameters available such as the project.

Note that qimera-command was designed with scripting in mind, not to be a interactive command line interface for human operators. As a result, its command syntax can feel quite verbose and very particular. This is intentional as qimera-command wants to be 100% sure it understands what it is being told to do and avoids guessing or assuming user intention.

As it is a command line utility, qimera-command has no desktop or start menu shortcut. To launch it, open a terminal, navigate to the {{bin}} directory of your Qimera installation and run qimera-command.exe or ./qimera-command depending on the conventions of your operating system. Users can also add this path to their environment variables and then run the commands from any directory. Then they can navigate to the project folder and not have to pass the --project folder argument for most jobs. For the remainder of this document we will use Windows syntax.

qimera-command aims to be largely self documenting via its command line help. To begin, run qimera-command.exe --help. In addition to explaining some general command line flags, this will list all the job types that can be passed to the --job flag. To learn about the behaviour and input to a particular job, run qimera-command.exe --job=<job-name> --help. Each job type takes a specific set of flags, although many flags are common to multiple jobs.

Flags must be introduced with a double hyphen (dash). For flags that take a value, that value may be specified using an equal sign (--flag=somevalue) or a space (--flag somevalue). The order of flags on the command line is typically not important. Some jobs can also take a list of position arguments at the end of the command line, which are not introduced by flags. Special characters (spaces, new lines, asterisks, etc.) must be properly quoted or escaped according to the rules of your shell or scripting language. For example: --project-folder="E:\My Projects\Initial Survey" --file=My\ File\ with\ Spaces.txt --note="***Uncorrected Values***"

While running the given job, qimera-command may print relevant information to the command line. When the job is finished successfully, qimera-command will complete with an exit code of 0. All other exit codes indicate a failure of some kind, with an explanatory message printed to the command line.

qimera-command requires a qimera-command add-on with your Qimera or Qimera Offshore license to use.

Running in Single Command Mode

In single command mode, the --job flag is used to denote which job to run

CODE

# EXAMPLE - Running a generic job-name with a project-folder and other-arguments.
"C:\Path\To\bin\qimera-command.exe" --job job-name ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
--other-arguments

Running in Configuration Mode

In configuration mode, the --config flag is used to specify a path to a JSON file that contains a list of jobs to be run along with arguments. Instead of being command line arguments, instead these arguments become members of the job objects.

CODE

# EXAMPLE - Running a config of multiple jobs in a JSON file
"C:\Path\To\bin\qimera-command.exe" ^
--config="C:\\Path\\To\\config.json"

CODE

# EXAMPLE - JSON Config to run a collection of jobs that will create a project, add all the files in a specific folder, and create a dynamic grid

{
  "project-folder": "C:\\Users\\username\\QPS-Data\\Projects\\test",
  "jobs": [
    {
      "job": "create-project",
      "epsg-code": 32610
    },
    {
      "job": "add-raw-sonar-files-db",
      "folder-path": "C:\\Users\\username\\Documents\\sonarfiles"
    },
    "auto-process",
    {
      "job": "create-dynamic-grid",
      "name": "Dynamic Grid",
      "cell-size": 0.25
    }
  ]
}

Jobs

Below is a list of jobs and their arguments, with examples formatted for command line usage. When using these for JSON configs, the arguments instead become objects.

Create Project

This job creates an empty project.

BASH

# EXAMPLE - Create a new project called "test" in EPSG 32630
"C:\Path\To\bin\qimera-command.exe" --job create-project ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
--epsg-code 32630

create-project	Arguments
--project-folder <path>	The project folder to create. Must not exist.
--survey-type <text>	Optional argument to set the survey type. Pass in quotations if contains spaces.
--description <text>	Optional argument to set the description of the project. Pass in quotations if contains spaces.
--epsg-code <number>	The EPSG code specifying the projected project coordinate system.
--wkt-file <file-path>	The path to a file containing WKT (text file with wkt extension, Qinsy Database, or QPD) specifying the projected project coordinate system.

Add Raw Sonar Files DB

This job adds ".db" raw sonar files to a Qimera project.

BASH

# EXAMPLE - Add 3 specific DB files to the "test" project in EPSG 32630
"C:\Path\To\bin\qimera-command.exe" --job add-raw-sonar-files-db ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
"C:\Users\username\Downloads\datasets\Brest-Wrecks\20130614_0801_em2040C_wreck_300 - 0001.db" ^
"C:\Users\username\Downloads\datasets\Brest-Wrecks\20130614_0807_em2040C_wreck_300 - 0001.db" ^
"C:\Users\username\Downloads\datasets\Brest-Wrecks\20130614_0809_em2040C_wreck_300 - 0001.db" ^
--print-progress

add-raw-sonar-files-db	Arguments
--project-folder <path>	The project folder.
--folder-path <path>	A folder containing the files you wish to add to the project.
--print-progress	Print job progress to the command line.
Arguments: Files	To specify the files to add to the project you can use the --folder-path flag or you can pass a series of single file paths to raw files as positional arguments.

Add Raw Sonar Files All

This job adds ".all" raw sonar files to a Qimera project.

BASH

# EXAMPLE: Add 3 specific ".all" files to the "test" project in EPSG 32630. Delay processing these files until explicitly instructed to process them.  
"C:\Path\To\bin\qimera-command.exe" --job add-raw-sonar-files-all ^
--epsg-code 32630 ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
--delay-convert-to-qpd ^
"C:\Users\username\Downloads\datasets\Panopee-Brest-Wrecks\0001_20150324_161631_Panopee.all" ^
"C:\Users\username\Downloads\datasets\Panopee-Brest-Wrecks\0002_20150324_161913_Panopee.all" ^
"C:\Users\username\Downloads\datasets\Panopee-Brest-Wrecks\0003_20150324_162143_Panopee.all" ^
--print-progress

add-raw-sonar-files-all	Arguments
--project-folder <path>	The project folder.
--folder-path <path>	A folder containing the files you wish to add to the project.
--epsg-code <number>	The input epsg code for the file(s) you wish to import.
--delay-convert-to-qpd	An optional argument to delay the conversion from raw file to QPD. By default all imported files are converted directly to QPD. If delay is selected the auto-process job can be run to convert outstanding files at a later time.
--wkt-file <path>	The input wkt for the file(s) you wish to import.
--print-progress	Print job progress to the command line.
Arguments: Files	To specify the files to add to the project you can use the --folder-path flag or you can pass a series of single file paths to raw files as positional arguments.

Add Raw Sonar Files KMALL

This job adds ".kmall" raw sonar files to a Qimera project.

BASH

# EXAMPLE: Add 1 specific ".kmall" file to the "test" project in EPSG 32630. Process them immediately upon importing.
"C:\Path\To\bin\qimera-command.exe" --job add-raw-sonar-files-kmall ^
--epsg-code 32630 ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
"C:\Users\username\Downloads\datasets\0384_20250125_152045_SD-3003-0005-304.kmall" ^
--print-progress

add-raw-sonar-files-kmall	Arguments
--project-folder <path>	The project folder.
--folder-path <path>	A folder containing the files you wish to add to the project.
--epsg-code <number>	The input epsg code for the file(s) you wish to import.
--delay-convert-to-qpd	An optional argument to delay the conversion from raw file to QPD. By default all imported files are converted directly to QPD. If delay is selected the auto-process job can be run to convert outstanding files at a later time.
--wkt-file <path>	The input wkt for the file(s) you wish to import.
--print-progress	Print job progress to the command line.
Arguments: Files	To specify the files to add to the project you can use the --folder-path flag or you can pass a series of single file paths to raw files as positional arguments.

Add Raw Sonar Files S7K

This job adds ".s7k" raw sonar files to a Qimera project.

BASH

# EXAMPLE: Add all ".s7k" files from a specified directory to the "test" project in EPSG 32630.
"C:\Path\To\bin\qimera-command.exe" --job add-raw-sonar-files-s7k ^
--epsg-code 32630 ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
--folder-path "C:\Users\username\QPS-Data\sample-s7k-data" ^
--vessel-name "new-vessel" ^
--print-progress

add-raw-sonar-files-s7k	Arguments
--project-folder <path>	The project folder.
--folder-path <path>	A folder containing the files you wish to add to the project.
--epsg-code <number>	The input epsg code for the file(s) you wish to import.
--wkt-file <path>	The input wkt for the file(s) you wish to import.
--vessel-name <name>	Name for the vessel the imported .s7k(s) will be associated with. Creates a new vessel if the name does not match an existing vessel in the specified project.
--print-progress	Print job progress to the command line.
Arguments: Files	To specify the files to add to the project you can use the --folder-path flag or you can pass a series of single file paths to raw files as positional arguments.

Create Dynamic Grid

This job creates a dynamic grid using all raw sonar files loaded in the provided project.

BASH

# EXAMPLE: Grid all the lines in the "test" project and name the grid "Dynamic_Grid_3". Use the default cell-size.
"C:\Path\To\bin\qimera-command.exe" --job create-dynamic-grid ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
--name "Dynamic_Grid_3" ^
--print-progress

create-dynamic-grid	Arguments
--project-folder <path>	The project folder.
--name <text>	The name of the dynamic grid you would like to create.
--cell-size <number>	Optional argument that lets you choose the cell size of the dynamic grid in the project's survey units.
--cube-config <text>	Optional argument that lets you specify the configuration to use when creating a CUBE grid. Config Options: Default Deep Shallow Custom NOAA_0.5m NOAA_1m NOAA_2m NOAA_4m NOAA_8m NOAA_16m NOAA_32m
--print-progress	Print job progress to the command line.

Append to Grid

For each dynamic grid in the provided project this job appends all raw sonar files that are not already contained in that dynamic grid.

BASH

# EXAMPLE: 
"C:\Path\To\bin\qimera-command.exe" --job append-to-grid ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
--print-progress

append-to-grid	Arguments
--project-folder <path>	The project folder.

Remove from Grid

Remove the specified source files from the specified grid.

BASH

# EXAMPLE: Remove two source files from a grid
"C:\Path\To\bin\qimera-command.exe" --job remove-from-grid ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
--grid-name "mygrid" ^
"C:\Users\username\Downloads\datasets\Panopee-Brest-Wrecks\0001_20150324_161631_Panopee.all" ^
"C:\Users\username\Downloads\datasets\Panopee-Brest-Wrecks\0002_20150324_161913_Panopee.all"

remove-from-grid	Arguments
--project-folder <path>	The project folder.
--grid-name <grid-name>	The grid to remove source files from. If omitted, source files will be removed from all grids.
Arguments: Files	List of source files to remove from the grid as positional arguments.

Remove from Project

Remove the specified files from the project

BASH

# EXAMPLE: Remove two files from a project
"C:\Path\To\bin\qimera-command.exe" --job remove-from-project ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
"C:\Users\username\Downloads\datasets\Panopee-Brest-Wrecks\0001_20150324_161631_Panopee.all" ^
"C:\Users\username\Downloads\datasets\Panopee-Brest-Wrecks\0002_20150324_161913_Panopee.all"

remove-from-project	Arguments
--project-folder <path>	The project folder.
Arguments: Files	List of files to remove from the project as positional arguments.

Auto Process

Will process all the data present in the project folder

BASH

# EXAMPLE: Process all the lines in the "test" project
"C:\Path\To\bin\qimera-command.exe" --job auto-process ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
--print-progress

auto-process	Arguments
--project-folder <path>	The project folder
--print-progress	Print job progress to the command line.

Configure Grid

Configure the Specified Grid

BASH

# EXAMPLE: Change the colormap and colormap range of a grid
"C:\Path\To\bin\qimera-command.exe" --job configure-grid ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
--grid-name "mygrid" ^
--colormap-filename "relief.cmap" ^
--lower-bound "-45.5" ^
--upper-bound "-35.5"

configure-grid	Arguments
--project-folder <path>	The project folder.
--grid <grid-name>	The grid to edit.
--colormap-filename <cmap-filename>	Colormap file name, including extension (from user or system colormap directories, listed using list-colormaps job).
--colormap-filepath <cmap-filepath>	Path to valid Colormap file.
--lower-bound <lower-bound>	Colormap range lower bound (Positive Up). Requires accompanying upper-bound.
--upper-bound <upper-bound>	Colormap range upper bound (Positive Up). Requires accompanying lower-bound.

Run Filter Profile

This job runs the specified filter on all/specific raw sonar files in the provided project.

Note: when -h is used it will provide a overview of “User defined” filters present

BASH

# EXAMPLE: Apply the "Strong Spline" filter on 3 specific lines in the "test" project
"C:\Path\To\qimera-command.exe" --job run-filter-profile ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
--filter "Strong Spline" ^
"0001_20150324_161631_Panopee.all" ^
"0002_20150324_161913_Panopee.all" ^
"0003_20150324_162143_Panopee.all"

run-filter-profile	Arguments
--project-folder <path>	The project folder.
--filter <filter-name>	The name of the filter to run. Must be one of the following. Filter names containing spaces must be quoted.
--print-progress	Print job progress to the command line.
Arguments: Source File Names	Starting with Qimera v2.7.4, `Qimera-Command` can apply filters on specific lines of the project. The list of files must be specified as a space-separated string. Note: positional argument. So no need to add any flags. Just add the list of source file names to the end of the command

Export Grid ASCII XYZ

Export the data into an ASCII XYZ file

BASH

# EXAMPLE: Export 2 sections of "Dynamic_Grid_1" each constrained to the SD-polygons "poly1" and "poly2". Export to a custom directory
"C:\Path\To\bin\qimera-command.exe" --job export-grid-ascii ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
--export-folder "C:\Users\username\Downloads\GridExports\" ^
--depth-layer "shallow" ^
--z-precision 4 ^
--column-separator "\t" ^
--bounds "poly1" ^
--bounds "poly2" ^
"Dynamic_Grid_1"

export-grid-ascii	Arguments
--project-folder <path>	The project folder.
--bounds	Optional argument. The names of SD objects for settings bounds. Multiple bounds can be specified by inputting the `--bounds` option multiple times.
--export-folder <Export/>	The folder to write the export to. This defaults to the project export folder.
--depth-layer <average>	The depth layer. (Shallow, Average, Deep or Cube)
--z-precision <2>	The decimal precision for Z values.
--column-separator <,>	The character to be used as a column-separator.
Arguments: grid-names	The list of the grid file names. Note: positional argument. So no need to add any flags. Just add the list of grid names to the end of the command

Export Lines to NOAA CSV

Export the data into a NOAA CSV file, all the data present will be exported in a single csv file.

BASH

# EXAMPLE: Export all data from the "test" project to the project's "Export\" directory as NOAA CSV
"C:\Path\To\bin\qimera-command.exe" --job export-noaa-csv ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
--output-filename "brest-wrecks.csv"

export-noaa-csv	Arguments
--project-folder <path>	The project folder.
--output-filename <filename>	The name of the exported NOAA csv file.

Export Grid GeoTIFF

Export specified grid to a GeoTIFF file.

BASH

# EXAMPLE: Export a grid to a GeoTIFF file
"C:\Path\To\bin\qimera-command.exe" --job export-geotiff ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
--grid-name "mygrid" ^
--export-filename "new_geotiff.tif" ^
--depth-layer "shallow" ^
--export-world-file

export-geotiff	Arguments
--project-folder <path>	The project folder.
--grid-name <string>	Name of grid to export.
--export-filename <string>	Name for resulting exported GeoTIFF file, saved to project “Export” folder (exclusive with export-filepath).
--export-filepath <path>	File path to resulting exported GeoTIFF file (exclusive with export-filename).
--depth-layer <average>	The depth layer. (Shallow, Average, Deep or Cube).
--export-world-file	Export the TIFF world file?
--origin <lower-left>	Origin of the GeoTIFF world file. (lower-left or upper-left).

Export Grid Floating Point GeoTIFF

Export specified grid to a Floating Point GeoTIFF file.

BASH

# EXAMPLE: Export a grid to a Floating Point GeoTIFF file
"C:\Path\To\bin\qimera-command.exe" --job export-grid-floating-point-geotiff ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
--grid-name "mygrid" ^
--export-filename "new_geotiff.tif" ^
--depth-layer "shallow" ^
--no-data-value "NAN"

export-floating-point-geotiff	Arguments
--project-folder <path>	The project folder.
--grid-name <string>	Name of grid to export.
--export-filename <string>	Name for resulting exported ASCII GeoTIFF file, saved to project “Export” folder (exclusive with export-filepath).
--export-filepath <path>	File path to resulting exported ASCII GeoTIFF file (exclusive with export-filename).
--depth-layer <average>	The depth layer. (Shallow, Average, Deep or Cube).
--no-data-value <no-data-value>	The No Data value for missing data (NaN or a custom number).

Generate Grid Uncertainty Layers

Create THU and TVU scalars for a given grid.

BASH

# EXAMPLE: 
"C:\Path\To\bin\qimera-command.exe" --job generate-thu-tvu-layers ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
--grid-name "Dynamic_Grid_1"

generate-thu-tvu-layers	Arguments
--project-folder <path>	The project folder.
--grid-name	The name of the dynamic grid.

Export Grid to BAG

This job exports a BAG file for a dynamic grid

POWERSHELL

# EXAMPLE: Export the "Dynamic_Grid_1" as bag. 
"C:\Path\To\bin\qimera-command.exe" --job export-bag ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
--grid-name "Dynamic_Grid_1" ^
--version 15 ^
--output "compute-tvu" ^
--xml-date ^
--bag-xml-metadata "C:\Users\username\QPS-Data\Projects\test\Export\Bag_Config.xml" ^
--compression 3 ^
--depth-layer "shallow"

export-bag	Arguments
--project-folder <path>	The project folder.
--grid-name <grid-name>	The dynamic grid to export.
--version <15>	Choose to export to a version 14 or 15 file.
--output <compute-tvu>	stddev, attached-scalar, cube-uncertainty, compute-slope-corrected-uncertainty, compute-tvu, loaded-scalar
--scalar-path <path>	Set this to the path of the scalar file if uncertainty is set to loaded-scalar.
--date <2024-08-09>	Directly specify a date for the export. Use the format: yyyy-MM-dd
--xml-date	Use the date in the bag-metadata-xml file.
--compression <0>	Compression value for the BAG file. Select a number between 0 and 5.
--bag-xml-metadata <filename>	The BAG XML metadata file. These files can be generated here: Export to BAG Surface Wizard
--depth-layer <average>	The depth layer of the grid to be exported. (Shallow, Average, Deep or Cube)

Export GSF

This job exports GSF files from the sonar files.

BASH

# EXAMPLE: Export 3 specific lines. Export each system separately. Do not flag filtered-soundings as manually-editted. 
# Export to a custom folder and use the vessel-name, file-name, and system-name for each output file. 
"C:\Path\To\bin\qimera-command.exe" --job export-gsf ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^
--export-folder "C:\Users\username\Downloads\GridExports\" ^
--filename-pattern "%v\%f\%s" ^
--replace-whitespace ^
--export-systems-individually ^
--do-not-flag-filtered-as-manual-edits ^
"0001_20150324_161631_Panopee.all" ^
"0002_20150324_161913_Panopee.all" ^
"0003_20150324_162143_Panopee.all"

export-gsf	Arguments
--project-folder <path>	The project folder.
--export-folder <path>	The folder to export the GSF files to.
--filename-pattern <%v\%f>	The pattern of the exported filenames. %f: Source file name. %v: vessel name. %s: system name
--replace-whitespace	Replace whitespace with underscores in the exported filename
--export-systems-individually	Export each system to their own file.
--specific-system <1>	Export a specific system by index.
--exclude-user-additional-soundings	Exclude user additional soundings in the GSF export.
--exclude-raw-backscatter-imagery	Exclude raw backscatter imagery in the GSF export.
--do-not-flag-filtered-as-manual-edits	Do not flag filtered soundings as manual edits in the GSF export.
--flag-all-interpolated-soundings-as-accepted	Flag all interpolated soundings as accepted in the GSF export.
Arguments: Source file names	The list of source file names to export. Note: positional argument. So no need to add any flags. Just add the list of source file names to the end of the command

List Colormaps

List user and system colormaps.

BASH

# EXAMPLE: List all user and system colormaps
"C:\Path\To\bin\qimera-command.exe" --job list-colormaps

Note: This job requires no arguments.

List Source Files

List Source Files in Project.

BASH

# EXAMPLE: List all source files in a project
"C:\Path\To\bin\qimera-command.exe" --job list-source-files ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^

list-source-files	Arguments
--project-folder <path>	The project folder.

List Grids

List Static and Dynamic Grids in a project.

BASH

# EXAMPLE: List all grids in a project
"C:\Path\To\bin\qimera-command.exe" --job list-grids ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^

list-grids	Arguments
--project-folder <path>	The project folder.

List SD Objects

List all SD Objects in a project.

BASH

# EXAMPLE: List all SD Objects in a project
"C:\Path\To\bin\qimera-command.exe" --job list-sd-objects ^
--project-folder "C:\Users\username\QPS-Data\Projects\test" ^

list-sd-objects	Arguments
--project-folder <path>	The project folder.

List Systems

This job will list the systems in the project

BASH

# EXAMPLE: 
"C:\Path\To\bin\qimera-command.exe" --job list-systems ^
--project-folder "C:\Users\username\QPS-Data\Projects\test"

list-systems	Arguments
--project-folder <path>	The project folder.

List Vessels

List all Vessels in a project.

BASH

# EXAMPLE: List all Vessels in a project 
"C:\Path\To\bin\qimera-command.exe" --job list-vessels ^
--project-folder "C:\Users\username\QPS-Data\Projects\test"

list-vessels	Arguments
--project-folder <path>	The project folder.