Skip to main content

Command line options

rakaia can be executed easily from the command line using the following executable once installed:

rakaia

This will enable a local session to be run from http://127.0.0.1:5000/ or http://0.0.0.0:5000/ with the default session parameters. However, rakaia offers a host of customizable runtime configurations that can be enabled, disabled, or changed through the CLI. These options are shown below:

  • -v, --version: Show the current rakaia version then exit.

  • -h, --help: Show the help output and exit.

  • -a, --auto-open: Automatically open the browser when the application is called. Default: False

  • -l, --use-local-dialog: Enable a local file dialog with wxPython to browse and read local files. Default: False

  • -p PORT, --port PORT: Set the port for rakaia on local runs. Default: 5000. Other options to consider are 8050, 8080. Setting a custom port will change the local URL to take the form of http://127.0.0.1:{port} such as http://127.0.0.1:8050/

  • -pr, --production-mode: Enable production mode. This will generate a production-level WSGI server,and will switch the application out of debug mode. Default: not enabled. Production mode invokes a server from waitress that is intended to support concurrent users on public deployments. Because of the server configuration, debugging mode (i.e. viewing the application errors/exceptions in the console) is not available. Should be used if the user is experiencing performance issues (lag, timeouts), as removing debugging mode should in theory reduce memory consumption for the interpreter.

  • -dt, --disable-threading: Disable threading. By default, threading is enabled. Threading will enable the application to take advantage of multiprocessing on local machines to improve application speed.

  • -dl, --disable-loading: Disable loading on data import and data switching. By default, loading is enabled. rakaia uses dash bootstrap loading for certain inputs to indicate when data are being loaded or manipulated, such as on data import or when large images are being created. The load screens generally help to indicate to users when certain processes have finished, and when the user can proceed with the next input. Disabling load screens will make the application feel smoother for datasets of any size, but it will be more difficult to assess what the application is doing at any specific moment.

  • -dp, --disable-persistence: Disable saving persistent session variable values in the browser. By default, persistence is enabled. Certain input components in the application layout use browser local persistence, where the value is saved in the browser and used in subsequent sessions. This includes certain inputs for canvas appearance such as scalebar and legend parameters. Disabling persistence will result in all components using their default values.

  • -dc, --disable-cache-overwriting: Disable cache overwriting for server side stores. By default, rakaia will overwrite Serverside objects on each callback invocation to save disk space. However, overwriting should be disabled for concurrent sessions that host multiple users, such as containerized or public instances. More information about serverside transformations can be found here

  • -sc SWATCHES, --swatch-colors SWATCHES: Set custom RGB codes for the swatches. rakaia uses default colour swatches with 7 pre-assigned colours that represent the most basic RGB blends, which can be easily selected for channel recolouring:

In certain instances, users may wish to use a custom blend of input swatches to make colour selection more consistent and rapid. The swatches can be secified using a string wrapped in quotations of the form #FF0000,#00FF00,#0000FF,#00FAFF,#FF00FF,#FFFF00,#FFFFFF. The swatches should be in HEX string form.

  • -at {float,int}, --array-type {float,int}: Set the preferred numpy array type for storing arrays in session. Options are float for np.float32, or int for np.uint16. Float arrays will have more precision and may be required for array values between 0 and 1, but uint arrays will likely consume less memory. Default is float

By default, rakaia will store imported data as 32 byte float arrays. Information on numpy dtypes can be found here. To reduce memory consumption and the amount of temporary disk storage required, users can choose to have arrays stored as 16 byte unsigned integers.

In many instances, using integer array types will save up to 50% of the disk space required for storing the same array in float32 format.

This option will work well for the majority of user cases, as arrays are always converted into integers when recoloured and blended in the canvas. However, there are two specific use cases where storing the arrays as float are beneficial or necessary:

  • When the channel array has values between 0 and 1: these values will automatically be converted to 0 or 1 with integer casting, so any decimal precision will be lost for this channel.
  • When the array channel has a maximum value over 65535: Unsigned 16 byte integers in numpy have a maximum positive range of 65535, so any array values that are greater will be clipped to this value

For the use cases above, users are advised to use the default array storage type.

  • -cs --cache-storage: Set the output path for the temporary session caches. Default is the temp directory generated by tempfile. rakaia uses temporary data caches for serverside data transformations to make computations and image manipulation fast and responsive. The temporary caches are stored in the specific cache storage path.