Page tree
Skip to end of metadata
Go to start of metadata

Software architecture

A software is an external application that is able to interact with the Cytomine server. The software may get, add update or delete data according to the user right. The integration with Cytomine is done thanks to the client (Java, Python,...).

In this document, we will take the example of a simple scripts computing annotations area with term T inside an annotation (ROI). We call it: "ComputeAnnotationStat".
This software has 4 steps:

  • Get the annotation ROI from Cytomine (the location properties is needed),
  • Search on Cytomine all annotations with the term T inside the ROI location,
  • Compute the sum of the area for all annotations,
  • Add a property to the annotation ROI. The key is "AREA_OF_TERM" (where TERM is the term T name) and the value is the areas sum.

The 2 main parameters are the id of the annotation ROI and the id of term T.

The script will be available on Cytomine server in directory algo/ (relative to Cytomine home directory in the server).
The software needs two dependencies: algo/computeAnnotationStats/Cytomine-Java-Client.jar (Cytomine client) and algo/computeAnnotationStats/jts-1.13.jar (JTS for GIS ops).

How to create software

Here is the basic steps to add a new software to Cytomine:

  1. Create a software instance,
  2. Create a software parameter list,
  3. Create a service for this software (Optional),
  4. Adapt your script,
  5. Add the software to a project
  6. Adapt your software/algo

Create a software

First create a new software with a client (Java or Python).
Here is the properties description:

nameStringSoftware name

Software service in Cytomine. More details in next sections. 
This might be a generic service like launchLocalScriptService (the software must be in the same server).


If you want to display result information on the web client, you can provide a template name.
The basic template is DownloadFiles that just provides a simple table to download file uploaded by the job.

executedCommandStringCommand to execute the software
groovy -cp 

Here is the code to create or new software with the Java client:

String name = "ComputeAnnotationStat"
String serviceName = "launchLocalScriptService"
String resultName = "DownloadFiles"
String executedCommand = "groovy -cp algo/computeAnnotationStats/Cytomine-Java-Client.jar:algo/computeAnnotationStats/jts-1.13.jar algo/computeAnnotationStats/computeAnnotationStats.groovy"
Software software = cytomine.addSoftware(name, serviceName, resultName, executedCommand);

Examples are also available in Python e.g. in our Cytomine-DataMining repository in the applications/ directory (e.g. file with the add_software function).

Create software parameters

The software command may contains some hard-corded parameters (e.g: script name, "-cp dep.jar",...) but you may need some extra parameters.
In this case, the 2 main parameters will be the annotation ROI id and the term T id. 

nameStringParameter name
"annotation", "term"

Parameter type. Usefull to provide a "auto-generate" form in cytomine to launch the software.

  • Number, String Boolean, List...: the form will check if the input content is valid (valid number, valid boolean,...),
  • Domain, ListDomain: the form may provide a list of domain instance (DomainList = multiple choice). Its just the domain id that will be send to the software. See other properties


"Number", "String", "Domain",...
softwareLongSoftware id for this parameterThe software
ComputeAnnotationStat id
mandatorybooleanThe parameter is mandatory (auto-check in the form)"annotation" is mandatory and "term" too
indexLongParameters will be send to the server with a specific orderThe software will take "annotation" before "term" param, so annotation index must be lower than term index.
default_valueStringDefault value if mandatory is false 
set_by_serverBooleanThe parameter value is automatically set by the server. The parameter will not be print the launch form. 

If type = Domain/ListDomain, we may add a service URI to get the choice for the select input in the launch form.
In this example, we need the term id (and the annotation ROI id). For the term id, its better to provide a select box with "Term 1, Term 2,..." than to provide an input box asking the user to type the term id.
In this case, the uri value will be "/api/ontology/$currentOntology$/project.json". The service must response a collection with object (object must have at least an id property)

$currentOntology$ will be replace by the current project ontology id. A software may be link with multiple project, so we cannot directly set the ontology id.

uri_print_attributStringDefine the property from the uri service to show in the selectbox. In this case, we want to show the "name" of the
uri_sort_attributStringDefine the property from the uri used to sort the item in the select box. In our case, we sort on "name"
//The default_value, set_by_server, uri, uri_print_attribut, uri_sort_attribut are not yet available in the client
cytomine.addSoftwareParameter("annotation", "Number", software.getId(), "", true, 200);
cytomine.addSoftwareParameter("term", "Number", software.getId(), "", true, 300);

Examples are also available in Python e.g. in our Cytomine-DataMining repository in the applications/ directory (e.g. file with the add_software_parameter function).

Create the service 

When a software is triggered on Cytomine, it creates a Job that executes the application. A service in Cytomine must be defined to run this program.
There are some predefined services:


Launch a software local to the platform.
It run the external command " executedCommand" with parameters:

  1. The executedCommand "hardcoded" parameters
  2. The job id
  3. The user job id
  4. Cytomine  Host
  5. UserJob public key
  6. UserJob private key
  7. All JobParameter (ordered by index asc)

If executedCommand is "java myApp.jar -cp client.jar" and the job parameters are "idImage=5" and "level=hight", the command could be:

java myApp.jar -cp client.jar 123 456 4ger6g548reg eg87987gg8g 5 hight

Write/Adapt your script

Our example, use a basic Groovy script. You can see a complete example in our Github repository in Java.

Extract parameters

We first need to retrieve all parameters:

//we use LaunchLocalScriptService, so we keep the same parameters order
Long idJob = Long.parseLong(args[0])
String userjob = args[1]
String host= args[2]
String publickey = args[3]
String privatekey= args[4]
String annotation= args[5]
String idTerm = args[6]

Retrieve Cytomine data

We can open Cytomine connection and we can call some Cytomine services:

Cytomine cytomine = new Cytomine(host, publickey, privatekey, "./");
Annotation baseAnnotation = cytomine.getAnnotation(Long.parseLong(annotation))
Term term = cytomine.getTerm(Long.parseLong(idTerm))

Update progression and status

During the script execution, its possible to update the job status and progression.
In the web client, the user will see a progress bar and a status label. 

Here is an example in Java:

//do step 1
//do step 2 (big step)
//do step 3
//if failed: cytomine.changeStatus(idJob,Cytomine.JobStatus.FAILED,0)

Similarly this can be done in Python using the update_job_status function (see also the CytomineJob class in the Python client utilities)

Upload algo/script results to Cytomine

A lot of software need to add, edit or remove data on Cytomine. These data may be domain instance (new annotations, add new term to an annotation, add a property to a domain...) or simply a file that will be attached to the job.

  • For a domain instance: simply use the client to add/update or delete data on the server (e.g. function addAnnotation to add an annotation to an image; function addAnnotationTerm to add an ontology term to an existing annotation, ...),
  • For a binary/text file, you need to create a job data and to upload the file to this job data thanks to these methods:

    public JobData addJobData(String key, Long idJob, String filename)
    public void uploadJobData(Long idJobData, byte[] data)

    You can do this:

    JobData data = cytomine.addJobData("report",idJob,"report.csv")

In our example, the job simply add a property to the ROI annotation and add the result as the value. 

Add the software to a project

A software needs to be linked with a project before using it. You can simply do that in the web client (Project configuration > Software) or with a client.

In Java you can use the addSoftwareProject function.

Examples are also available in Python e.g. in our Cytomine-DataMining repository in the applications/ directory (e.g. file with the add_software_project function)

How to run a software (command-line and/or Cytomine-WebUI)

A software can be run through command-line on a remote computer, or through the Cytomine-WebUI using our Software router package (using RabbitMQ broker): See this guide to learn how to made a job executable from the Cytomine-WebUI "Run Job" Panel.

When running an algorithm with certain parameter values (e.g. a threshold value when performing a intensity-based segmentation; or machine learning parameters to build a recognition model), it is useful to store these values for reproducibility. Any job (instance of a software) can have its parameter values stored in the Cytomine-Core database. With such information, it is possible to compare different execution of an algorithm and choose the best parameter values for the task. These parameter values can be checked in the Jobs tab, in the Details section of each job, as illustrated below. 

In Python, they can be added once the job is running using the add_job_parameters function.





  • No labels