Command Line Interface#

It is possible to operate Geona Hyperspectral in command line mode, however, you will first need to generate a configuration file. Use the dashboard to configure all the settings using the Processing page of the UI and click the Export Configuration button to save the configuration to file. This configuration file will be saved to a folder named configs in the workspace directory mounted inside your container - make a note of the configuration file name as this needs to be passed to the container when it starts.

There are two modes to run processing in a non-interactive mode:

Single-run container#

This mode creates a single instance of the Geona Hyperspectral container passing in the name of a pre-existing configuration file. The container will use the configuration settings to process the data, handle the outputs as defined in the configuration, before exiting. The license will be released back to the license server before the container exits.

To start the container in command line mode, we set an environment variable called geona_config. We do not need to pass the path of the config file as the software expects to find the specified file in the configs directory within the working directory. In this example, we have a configuration file named geona_hyperspectral_config_fenix1k_2022-05-06-114704.ini:

docker run --rm -e geona_config=geona_hyperspectral_config_fenix1k_2022-05-06-114704.ini -v /opt/geona/data:/opt/geona/data -p 5000:5000 --name geona-hyperspectral -t registry.digitalocean.com/geona/hyperspectral:latest

This command will launch the container, locate and load the specified configuration, and start processing the data as specified in the config file. The user interface is still available so you can check the status of the processing as it happens via the Job Status Viewer (available on the UI Dashboard), or you can check the job status log file located in the job folder within the workspace directory; it will be named status_<job_ID>.json; e.g. for job with an ID of 621, the status file would be workspace/621/status_621.json.

Persistent container#

This mode uses a single instance of the Geona Hyperspectral container, but rather than running one configuration file and then exiting (as above in the single-run container), this method will allow you to process multiple configurations using the same container instance.

To use this method, we construct a POST request which is submitted to the container using cURL or wget. This request needs to specify either the name of an existing configuration file which already resides in the configs directory, or a configuration file is included with the request.

In both of these scenarios we assume that you are running the curl/wget command on the same machine as the container. If this is not the case, replace 127.0.0.1 with the IP address or hostname of the machine running the container.

Use an existing configuration file#

The endpoint for the request is http://127.0.0.1:5000/processor. We need to define the request method as POST, declared as -x POST, and a form field to specify which configuration file to use using -F "geona_config=<config_filename>". For a configuration file which already exists called geona_hyperspectral_config_fenix_2022-06-10-123725.ini an example curl request would be as follows:

curl -X POST -F "geona_config=geona_hyperspectral_config_fenix_2022-06-10-123725.ini" http://127.0.0.1:5000/processor

Upload a local configuration file#

This request is as before, the only change is that we specify the local file to upload, which is prefixed with @, e.g.:

curl -X POST -F "geona_config=@/path/to/local/configuration_file.ini" http://127.0.0.1:5000/processor

Command response#

In both cases - either the single-run container or a persistent container - a JSON object will be returned with the following format:

{
    "job_id": "621",
    "log_file": "/opt/geona/data/logs/2022-06-13-134723_geona_hyperspectral.log",
    "message": "Job submitted for processing; check status file for details",
    "result": "success",
    "status_file_url": "http://127.0.0.1/status_log/621"
}

Command Line Interface

Contents