Add an external software to Cytomine

Preliminary note

This documentation is related to the V3 of the Cytomine platform that have been released on April 29, 2020.
For the previous versions, please follow this related documentation.


List of the related main concepts :

  • Software : an external script that can be launched by Cytomine for various purposes: building of AI model during training phase, use of AI model for data inference, data mining, statistics, ...
  • Job : a job is a run of a software. A same software can be run several times with different parameters. Each run is a job.
  • Parameter : a software parameter is the declaration of a variable in the software, and a job parameter is the value attributed to this variable during a job (a run of this software).
  • Software router : the component of Cytomine that manages the softwares and the software user repositories. It also assure the launching of a software on a dedicated processing server.
  • Processing Server : the component of Cytomine where the softwares will be run when launched from the Web interface.
  • Software User Repository : an object that contains all the information needed to fetch an external software : a source code forge (currently only GitHub) and a Docker container repository (currentl only DockerHub).

Even if you can use the Cytomine clients to interact with Cytomine and create various scripts, you can also integrate these scripts directly into the Cytomine platform to allow end-users to run them directly from the Web interface. This is what this page is all about :  how to integrate a script into the Cytomine platform.


To be able to plug your script into the Cytomine platform you will need to

  • write a descriptor.json file that will describe the software parameters and their constraints.
  • write and compile a Dockerfile. If you are not familiar with Dockerfiles, please read the dedicated Docker documentation.

Step 1 : create the script

There is currently three external clients : one in Java, one in Javascript and one in Python. Please choose one of these 3 language to program your script with.

In this example, we will create, in Python, a software that will list the images into a project and create a file, that will be uploaded in Cytomine, containing the value of an integer input parameter.

You can found the example.py, the descriptor.json, and the Dockerfile of the software in our example repository.

Once your Python script is created, please test it locally, and validate its use with all kind of possible sofwares parameters values that the users will have to set, and identify all the mandatory dependencies. Do not go to the next step until all dependencies and softwares parameters are identified and described.

Step 2 : Dockerize your script

Inside Cytomine, when a user will launch your Software through the UI, your Software will be run has a Job in an independant container in a Processing Server componant. This allow each Software to be run inside a specific and really adapted execution environment (specific libraries and dependencies, version of Python, etc). In this way, you will not be constrained by a fixed-in-advance set of librairies, you will be able to use the tools you are used to or need to use.

To allow this flexibility, your Sotfware must be developed to allow its "containerization". To do so, you will have to write a Dockerfile that will allow Docker to compile an image of a container hosting your script. If you are not used to Docker, please read the Get Started section on the Docker website, and their complete documentation about Dockerfile.
Note that we have prebuild some base images containing our clients, so you can inherit them in your own Dockerfile for convenience.

In our example Software, we only need the features of the Cytomine python client. So, we will define our Dockerfile with an inheritance of the cytomine/software-python3-base image, add our script file and define the entrypoint as the command to run our script (without arguments).
Our Dockerfile is then:

FROM cytomine/software-python3-base
ADD example.py /app/example.py
ENTRYPOINT ["python", "/app/example.py"]

You can then test if it compile correctly using the docker build command in the folder containing the Dockerfile :

sudo docker build -t my_image .

Step 3 : write the running declarative file

To be able to allow end users to run your software from the Cytomine Web UI, some meta-information about it must be given to the Cytomine platform, using the descriptor.json file.

The descriptor file of our example software can be found here.

The software parameters "cytomine_host", "cytomine_public_key", "cytomine_private_key", "cytomine_id_project", and "cytomine_id_software" are required by the clients and are common to all external scripts. Their values will be set by the Cytomine platform as they are specific of each Cytomine instance.

In adition to these usual parameters, we have, in our example, a specific parameter : "my_integer_parameter". It can be declared as :

      "id": "my_integer_parameter",
      "value-key": "[@ID]",
      "command-line-flag": "--@id",
      "name": "Example integer parameter",
      "set-by-server": false,
      "optional": false,
      "type": "Number"
  • The "id" is the name of this parameter as you use it into your script;
  • The value associated to this parameter will be the value of this "my_integer_parameter" as described in "value-key";
  • The "command-line-flag" indicates that the "id" will be used when Cytomine will generate the command line to run the script;
  • The "name" is a human readable name displayed into the Cytomine UI;
  • As it is a specific parameter, this parameter will be set by the end user and not by the server; so set-by-server" is set to false;
  • "optional" indicates if the value is optional (true) or mandatory (false).
  • "type" describes the type of the required value of this parameter. Supported types are "String", "Number", "Boolean", "Domain", and "ListDomain". The "Domain" and "ListDomain" are references to other Cytomine objects.

In case of Cytomine objects (type "Domain" or ListDomain"), we will need to specify 3 more informations :

  • "uri" is the link where the Cytomine launcher will fetch the objects.
  • "uri-print-attribute" describes the attribute that will be displayed in the UI launcher.
  • "uri-sort-attribute" will be use to sort the domains on the specified attribute before displaying it.

You will find on GitHub an example with multiples parameters of different types.

Step 4 : add your software to the Cytomine platform

Finally, we will add our software to our Cytomine instance. Please note that a software added to a Cytomine instance is available for all users of this Cytomine instance.

There is currently two ways to add a software to a Cytomine instance : add it using code and containers repositories, or upload everything directly.

Via GitHub and DockerHub

Some trusted code and environment repositories can be added by an administrator to a Cytomine instance, using the tab "Trusted sources" in the "Admin" panel.

Currently only Github repositories can be added for your software code, and only DockerHub can be set for your Docker image repository.

These trusted repositories are frequently automatically fetched by the Cytomine platform, and every new version of your software will be added.

Note that the trusted repositories are entire user repositories, not the specific software one. For exemple, to add our example script to your Cytomine instance, you do not have to set https://github.com/cytomine/S_Segment-CV-AdaptThres-Sample but https://github.com/cytomine/ as trusted code repository. This mean that not only our example script will be added, but all the Cytomine compatible scripts.

To differentiate the Cytomine external scripts of unwanted repositories, a prefix is used in the targeted repositories names. In our exemple, in the Cytomine user repository, the prefix is "S_".

Note that Cytomine will only fetch the release of your software. A release is a particular state of your software (a version) that is tagged in GitHub.

So, in the reachable source code repository, you must create a release of your software if you want it to be addedable in a Cytomine instance.

The next step is to compile a Docker image of your software, using the Dockerfile previously written, with the tag related to your version and push it into DockerHub (ex : S_myscript with release v1.0.0 on github and cytomine/s_myscript:v1.0.0 on DockerHub (if cytomine is your DockerHub username)).

The Cytomine instance will now detect your script in the trusted Github and DockerHub repositories and add or update it in its database.

Congratulations !

If you want more detailed information, you can consult the documentation made by the team from University of Liège.

Via a direct upload

If, for some reason, you do not want to use code and environment repositories, you can add your software directly to the platform via a direct upload to the Core Cytomine component.
Please note that, in this case, the update and version management of your software will not be automatically made via Cytomine.

First, create a zip with your script, the descriptor.json, the Dockerfile and all the files mandatory for the Dockerfile compilation (including your script file).

Currently, upload a software is only possible using the Cytomine Python client and the Cytomine Java client. For our example it can be done as:

software = Software(name, "ValidateAnnotation").upload("/home/test/Documents/Cytomine/S_python_software_example/S_python_software_example.zip")

Cytomine will then read and parse the descriptor file and update the software values.

A script has been added to the collection of exemples availables for the Cytomine Python clientupload_software.py

Using this script you will be able to upload your .zip archive with all your files and descriptors to your favorite Cytomine instance. Exemple of command to use for that :

python upload_software.py  --cytomine_host "YOUR-INSTANCE-URL" --cytomine_public_key "YOUR-PUBLIC-KEY" --cytomine_private_key "YOUR-PRIVATE-KEY" --software_name "Python Software Example" --filepath "S_python_software_example.zip"

All the parameters to consider are explained in the Python client page, and the How to upload an image using the Python client.

Step 5 : run and debug it

You can now browse the Web UI of Cytomine and go to the analysis panel of a project space.
If your software is not yet associated with your project, you will be able to associate it in the Algorithms tab in the Configuration panel of your project space.
Job panel

Click on the Launch new job button to run a job based on your software by selecting the wanted software:

Launch a new job
and fill in the parameter values. As you can see, the type is checked as you declared it previously :

Fill job values
After the run, you will be able to have the detail of the job with its status and, if finished, its output.
Job panel with job detail

Get logs

The Cytomine Python client is dedicated for external scripting and interaction of scripts with a Cytomine instance.
If you use the:

with cytomine.CytomineJob.from_cli(sys.argv) as cyto_job:

like in our example, the client will encapsulate the log management for you and the logs will be uploaded as an attached file related to the job.

We hope that it will help you to understand how your software has been run during this job, and eventually debug it.