Converts images into a KNOSSOS-readable format.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


A Python application that converts images into a KNOSSOS-readable format.


You can choose one of the following two installation methods:

1. Automatic installers

We have published installers for Windows and Linux here. They include all needed dependencies and install everything into one directory. You can just download and run them, they will guide you through the installation.

2. Installation with conda

If you are on Linux or Windows and have the conda package manager (included in the Anaconda and Miniconda Python 3.6 distributions), you can install knossos_cuber into your default environment by running

conda config --add channels mdraw
conda install knossos_cuber

If this doesn't work due to Python version conflicts or you just want to have a clean dedicated environment for knossos_cuber, you can install it into a new dedicated conda env by running

conda config --add channels mdraw
conda create -n knossos_cuber knossos_cuber

Optionally run source activate knossos_cuber (or conda activate knossos_cuber if you use the fish shell) to activate the environment and ensure all knossos_cuber executables are on your PATH.

3. Installation with pip

You can install knossos_cuber directly from Github by running

pip3 install

This should provide the executables knossos_cuber and knossos_cuber_gui on your PATH.

Note: If you need to use a Python version older than 3.5, pyqt5 has to be separately installed using your operating system's package manager (apt, brew, etc.).

4. Running directly from the code directory

knossos_cuber depends on the following Python packages:

  • numpy
  • scipy
  • pillow
  • pyqt5 (only if you want to use the GUI)
  • future (only if you need to use Python 2 - in this case, use pip2/python2 instead of pip3/python3 in the following instructions)

These dependencies can be installed using pip:

pip3 install numpy scipy pillow pyqt5

After downloading the source code from, you can then run the scripts and directly with your Python interpreter.


These usage examples assume that you have installed knossos_cuber with installation method 1., 2. or 3..

(If you prefer to run the scripts directly out of the code folder, replace the following mentions of knossos_cuber by python3 and knossos_cuber_gui by python3, respectively.)


If you run knossos_cuber without any arguments, you get the following output:

usage: knossos_cuber [-h] [--format FORMAT] [--config CONFIG]
                     source_dir target_dir
knossos_cuber: error: too few arguments

knossos_cuber expects at least 3 arguments:

  • --format/-f: The format of your image files. Currently, the options png, tif and jpg are supported.
  • source_dir: The path to the directory where your images are located in.
  • target_dir: Path to the output directory.

For example: knossos_cuber -f png input_dir output_dir

If you run it like this, knossos_cuber will use sane default parameters for dataset generation. These parameters can be found in config.ini, and can be overridden by supplying an own configuration file using the --config/-c argument:

For example: knossos_cuber -f png -c my_conf.ini input_dir output_dir


For a GUI version of this program, run knossos_cuber_gui. It accepts an additional argument, --config/-c, that should be the path to another configuration file.


knossos_cuber is part of KNOSSOS. Head to KNOSSOS' main site or our Github Repository for more information.