# Signals Image Artist Command Line Interface (CLI)

This tool enables users to upload and download data to the Signals Image Artist server.
This is the official documentation for the CLI tool.

## Installation

### Gemma-client Windows version

Gemma-client Windows version works as a stand-alone program which needs no installation.
It can just be copied to any directory from where it will be used.

When upgrading SImA to version 1.2 Gemma-clients from earlier SImA versions must be
uninstalled first (in their case a separate installer was provided).

Gemma-client can also be used from a centralized location (which is available for all
users).

First copy `gemma-client.exe` to the directory from where it should be used (e.g.
`C:\gemma-client`). Then for the upload, you can run

```sh
C:\gemma-client\gemma-client.exe upload --hostname admin 61fa3faf-ea06-4340-9d87-688eea2c5aaa "Harmony IDX/TIF" path\to\the\datasets < sima-hostname > --username
```

Here are instructions how to add gemma-client to the system path (after that you can use
it directly from any directory):

1. Open start menu,
2. Type Edit environment variables
3. Open the option Edit the system environment variables
4. Click Environment variables... button
5. There you see two boxes, in System Variables box find path variable
6. Click Edit
7. a window pops up, click New
8. Type the Directory path of your .exe or batch file ( Directory means exclude the file
   name from path)
9. Click Ok on all open windows and restart your system.
10. Verify gemma-client version by running `gemma-client --version`

### Python package (can be used from Linux and Mac)

The tool requires [Python](http://www.python.org) to run. Please download and install
Python >= 3.10 for your operating system.

After downloading the tool itself, chose one of the methods below for installation:

1. Globally

   Simply run:

   ```bash
   $ pip install gemma-client-1.2.4.tar.gz
   ```

   After this, the tool will be available as `gemma-client`.

2. Isolated environment (recommended)

   This uses Python's built-in
   [virtual environment](https://docs.python.org/3/library/venv.html#module-venv) to
   contain changes to your system to a local directoy not requiering superuser
   privileges and enabling a clean and easy uninstall of the tool.

   1. Navigate to a convenient location where your user is able to create a new
      directory.
   2. To create and activate a virtualenv run:
      ```bash
      $ python3 -m venv --prompt gemma-client-1.2 venv
      $ source venv/bin/activate
      ```
   3. To install the client run:
      ```bash
      $ pip install gemma-client-1.2.4.tar.gz
      ```

   The tool will be available as `gemma-client` in your virtualenv. Please note that
   `gemma-client` will **only** be accessible after the virtualenv has been activated.

   General virtualenv usage:

   1. To _exit_ the virtualenv, run:

      ```bash
      $ deactivate
      ```

   2. To enter it again, run:

      ```bash
      $ source venv/bin/activate
      ```

#### Uninstalling the python package

1. Globally

   ```bash
   $ pip uninstall gemma-client
   ```

2. Isolated environment

   Do either of the following.

   1. Delete the complete virtualenv named `venv` in _Installation 2.iii_ above.

   2. Uninstall from virtualenv:

   ```bash
   $ source venv/bin/activate
   $ pip uninstall gemma-client
   ```

## General Usage

The client has several subcommands with individual options.

```bash
$ gemma-client --help
```

This returns more information about the tool and a list of subcommands.

```text
Usage: gemma-client [OPTIONS] COMMAND [ARGS]...

  Client to handle datasets for Signals Image Artist.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  configuration  Display configuration stored in file
  configure      Save configuration parameters to file
  datatypes      Show list of supported datatypes
  download       Download dataset from the server
  find           Find datasets in given path
  register       Registers a dataset located in the given S3 path to the
                 server
  upload         Upload datasets to the server
```

The usage information of each subcommand can be accessed in the same way:

```bash
$ gemma-client < subcommand > --help
```

## Authentication

Authentication is done in the normal case by using `--username` argument which takes
SImA username as a parameter. Gemma-Client will prompt for the password.

There's also `--password` parameter which should be used carefully (it's not safe and it
leaves clear text passwords e.g. to console history)

## Example Workflow

In this example, the client is first configured, then a dataset is uploaded.

```bash
$ gemma-client configuration
Configuration file not found.
$ gemma-client configure --hostname sima.hostname.net
2023-05-31T08:18:43.848212Z - http_client - (MainThread) - INFO - Sending GET request to url https://sima.hostname.net:443/datastore/datatypes
Saving configuration to file...
Configuration saved.

$ gemma-client configuration
[GEMMA]
rest_api_port = 443
file_api_port = 9000
server_hostname = sima.hostname.net
socks_proxy =
datatypes = [OMITTED]

$ gemma-client register --hostname 192.168.1.112 --no-verify --no-warnings --username admin 61fa3faf-ea06-4340-9d87-688eea2c5aaa "Harmony IDX/TIF" s3://sima-ext-bucket/dataset-path
Password:
2023-05-31T08:12:46.901068Z - http_client - (MainThread) - INFO - Sending GET request to url https://192.168.1.112:443/datastore/datatypes
2023-05-31T08:12:46.912862Z - backend - (MainThread) - INFO - Data ownership: username=admin, user_id=05321c3b-ad74-4783-92ce-327b9872b944
2023-05-31T08:12:46.912981Z - backend - (MainThread) - INFO - Finding datasets of type Harmony IDX/TIF from s3://sima-ext-bucket/dataset-path, this might take a while...
2023-05-31T08:12:46.913049Z - http_client - (MainThread) - INFO - Sending GET request to url https://192.168.1.112:443/datastore/get_subdir_urls?url=s3%3A%2F%2Fsima-ext-bucket%2Fnew_data_2%2FGEM-946&dataset_type=Harmony IDX/TIF
2023-05-31T08:12:51.670521Z - http_client - (MainThread) - INFO - get_subdir_urls: [['s3://sima-ext-bucket/dataset-path/P017-ESC Colonies/P017-ESC Colonies_Measurement 1', ''], ['s3://sima-ext-bucket/dataset-path/P017-ESC Colonies/P017-ESC Colonies_Measurement 2', '']]
2023-05-31T08:12:51.670933Z - http_client - (MainThread) - INFO - Sending GET request to url https://192.168.1.112:443/datastore/token?screen_id=61fa3faf-ea06-4340-9d87-688eea2c5aaa
2023-05-31T08:12:52.164397Z - backend - (MainThread) - INFO - Registering external dataset s3://sima-ext-bucket/dataset-path/P017-ESC Colonies/P017-ESC Colonies_Measurement 1/
2023-05-31T08:12:52.164577Z - http_client - (MainThread) - INFO - Sending PUT request to url https://192.168.1.112:443/datastore/datasets/f0194f3c-ff8a-11ed-a966-0242ac130005/status/upload
2023-05-31T08:12:52.194941Z - http_client - (MainThread) - INFO - Sending GET request to url https://192.168.1.112:443/datastore/token?screen_id=61fa3faf-ea06-4340-9d87-688eea2c5aaa
2023-05-31T08:12:52.611287Z - backend - (MainThread) - INFO - Registering external dataset s3://sima-ext-bucket/dataset-path/P017-ESC Colonies/P017-ESC Colonies_Measurement 2/
2023-05-31T08:12:52.611398Z - http_client - (MainThread) - INFO - Sending PUT request to url https://192.168.1.112:443/datastore/datasets/f065aea4-ff8a-11ed-a212-0242ac130005/status/upload
```
