Data and scripting

A Restful application

Cytomine is a Restful application. It means than the data stored and managed by Cytomine can be obtained via specific URLs to get only the relevant information (without the visual interface).

You can test it by fetching the list of all the project of an instance. If you are logged into a Cytomine instance, browse an url like http://CYTOMINE_URL/api/project.json to get all the project that you're allowed to explore.

These access points allow users and external softwares to interact with Cytomine for various purposes : datamining, scripting, create a new visual interface for particular usages, etc. However, it is not convenient to set an HTTP request, its authentication, call it, then analyse and parse the response. To ease the interaction of Cytomine with System Administrators, external softwares and so on, we developed multiple clients that encapsulate the HTTP operations to allow developers to focus on their tasks.

Choosing your Cytomine client

As we have currently clients in Java, Javascript and Python, you can freely choose to program in one of these 3 language.

Note that you can create scripts in other languages but, if the current clients are not compatible with your chosen language, you will need to manage the usually encapsulated tasks as HTTP requests, authentication and so on.
However create a new Cytomine client is a good way to contribute to the Cytomine Open Source project.
Once a Cytomine client is chosen, install it following its documentation before writing your first Cytomine script.
Our clients are developed following the Object-oriented programming paradigm. Please read the External clients page of this documentation for more information about how to interact with Cytomine objects and connections.

How to create a script

We assume that you've already programmed in the selected language, that you have installed the related framework or dependencies and are able to create a new project or environment depending of your selected language.
Once the Cytomine client is installed on your machine, it can be referenced as a library for your project or script.

The following example is in Java. You will found Python examples below.
In this example, we want to count the number of annotations in all our available projects with P as the first letter of the project name and associated with a specific term.

import be.cytomine.client.*;
import be.cytomine.client.collections.*;
import be.cytomine.client.models.*;

String publickey = "XXX";
String privatekey = "YYY";
String cytomineCoreUrl = "http://CORE_URL/";

Long termId = 0L;

//Connection to Cytomine

//get all the available projects
Collection<Project> projects = Collection.fetch(Project.class);

//Instanciate a new list
List projectsStartingWithP = new ArrayList<>();

// Filter the projects
for(int i= 0; i<projects.size();i++){
    Project project = projects.get(i);
    if(project.get("name").startsWith("P") projectsStartingWithP.add(project);
// get the term
Term term = new Term().fetch(termId);

//count the total of annotations
AnnotationCollection ac;
int count = 0;
for(Project p : projectsStartingWithP){
    ac = AnnotationCollection.fetchByTermAndProject(term, p);
    count += ac.size();

For some examples in Python, look at the dedicated Python client page.
Note that the tests are also a good way to know how to use the functions of the clients. The tests can be found for the Javascript client, Python client and Java client

What can I do next ?

You can install and register your script as a Cytomine Software. This will allow other user of your Cytomine instance to easily run it via the User Interface.