Skip to main content

Access & Basic Usage

Access and Usage​

Note: rakaia is currently in the beta development stage, and may be subject to breaking changes with each minor and patch release. Please email mwatson@lunenfeld.ca to request access to the rakaia source code, which is required for installation.

rakaia can be installed locally without an environment or container, but this is not recommended for dependency management:

# cd rakaia
pip install -r requirements.txt
pip install .

With conda​

conda is the recommended installation manager for rakaia. To install conda locally, visit this link and select the relevant operating system.

Once conda is installed:

conda create --name rakaia python=3.9
conda activate rakaia
# cd rakaia
pip install -r requirements.txt
pip install .

Updating local installations​

From source, rakaia can be updated locally using the following commands. Note that this method requires access to the source code repository. Please contact mwatson@lunenfeld.ca to request repository acces privileges. 

# navigate to the directory where you cloned rakaia from github
cd rakaia
git switch main
git pull --all
pip install .

Running rakaia​

The ClI options and help screen for running rakaia can be viewed using:

rakaia -h

After installation, rakaia can be run through conda or simply executed using the rakaia command:

conda activate rakaia
rakaia

The user should then navigate to http://127.0.0.1:5000/ or http://0.0.0.0:5000/ to access rakaia.

The current version of rakaia can also be checked on the command line with the following:

rakaia -v

Custom Ports​

Users are able to specify a different port for rakaia web session (the default port remains 5000). Suggested alternative ports are 8050 and 8080. The port can be specified in the CLI with:

rakaia -p 8050

The local URL will then take the form of http://127.0.0.1:{port} such as http://127.0.0.1:8050/

Local file dialog​

Users may also have the option to install and use a local file dialog rendered with wxPython on local runs. This can be instantiated with the -l CLI option when running rakaia (by default, this feature is not included):

rakaia -l

IMPORTANT: Due to the limitations of wxPython on multi-threaded systems as well as compatibility problems on different OS options, this feature is not likely to work properly on macOS.

In order to use this feature, users should make sure to install wxPython from the proper download page

Other options​

By default, rakaia will run in threaded mode. To disable using a multi-threaded application instance, add -dt as a command line option (not recommended):

rakaia -dt

rakaia also uses bootstrap-style load screens to indicate that data are being imported or changed (i.e. on an ROI change). To disable the load screens for data manipulation, use the -dl CLI option:

rakaia -dl

rakaia supports custom default colour swatches that are input by the user. An example using 14 custom colours:

rakaia -sc "#25262b,#868e96,#fa5252,#e64980,#be4bdb,#7950f2,#4c6ef5,#228be6,#15aabf,#12b886,#40c057,#82c91e,#fab005,#fd7e14"

custom color swatches will replace the default color bars used for channel recoloring.

Basic authentication​

rakaia uses basic authentication upon a new session. The credentials are as follows:

  • username: rakaia_user
  • password: rakaia-1

Note that the basic authentication credentials are likely to change as beta releases update.

Docker​

rakaia can be run using Docker with the following commands (requires an installation of Docker):

cd rakaia
docker build -t rakaia .
# use -d to run detached in the background
docker run -d -p 5000:5000 rakaia:latest rakaia -pr

Local file destinations can be mounted for direct access to local filepaths in the containerized environment, such as :

docker run -p 5000:5000 -v /home/:/home/ rakaia:latest rakaia -pr

Navigate to the local address http://0.0.0.0:5000/ or http://127.0.0.1:5000/

Note: rakaia shuld be run in production mode in a Docker container. For more information, visit the Performance section of the documentation.

For developers​

rakaia can be run in editable mode with either configuration shown below, which permits source code changes to be applied to the application on the fly:

pip install -e .
rakaia

Installing an editable version through pip is also required to run unit tests:

pytest --headless --cov rakaia

Conversely, without app installation:

python rakaia/wsgi.py

Developers should note that running the application in the default mode will also for debugging and source code updates. These features are disabled when using production mode with -pr.

Performance​

Array casting​

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 instead by invoking the CLI option --array-type (from v0.11.0 onwards):

rakaia -at int

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.