As Cytomine is a Restful application, the data stored and managed by Cytomine can be obtained via specific URLs to get only the relevant information (without the visual interface).
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.
Note that a client will have the same permission than a human user. So a client will not be able to :
- See an annotation of another contributor of a Read-only project that he doesn't manage;
- Add or remove contributors of a project he doesn't manage;
- Fetch data without authentication;
The Cytomine clients are used as library into some scripts or programming projects. Look at their dedicated pages to know how to install them.
The first step with the use of a Cytomine client is to authenticate you to the Cytomine instance that you want to interact with.
This authentication is made with 3 arguments :
- The URL of the Cytomine instance;
- The public key of a user;
- The private key of a user.
These keys can be found in your https://doc.cytomine.org/Get Started V2?structure=UsersV2" class="wiki wikinew text-danger tips">account settings.
In the Python client, it's done with the with statement:
with Cytomine(host=params.host, public_key=params.public_key, private_key=params.private_key) as cytomine:
In the Java client, it's done with connection static method of the Cytomine class:
Cytomine.connection(cytomineCoreUrl, publickey, privatekey);
new Cytomine(CYTOMINE_CORE_URL); await Cytomine.instance.login(username, password, rememberMe); //or await Cytomine.instance.loginWithToken(username, token);
As Cytomine is a project following the Object Oriented Paradigm, it is built on basic element called objects, domains or models. In Cytomine, users, projects, annotations or images are objects.
In our external clients, these objects are called models and each object in Cytomine have its model representation (a class) in the external clients. Each object (an instance of model):
- has a set of attributes corresponding to resource attributes
- is managed itself through fetch(), save(), update() and delete() methods that communicate with the Cytomine-core server
- has some utilities to be serialized to JSON
Technically, all models inherits from a parent class Model that encapsulate functions as save(), update(), delete(), get_url(), etc.
//in Java //creation of a project Long ontID = 0L; Ontology ontology = new Ontology().fetch(ontID); String name = "test"; Project p = new Project(name,ontology).save(); //fetch a project Long projectID = 0L; Project p = new Project().fetch(projectID); //update a project p.set("name", name+"bis"); p.update(); //delete a project p.delete();
In some cases, the server provides supplementary actions for some resources. These actions are encapsulated in additional methods for the model (downloading an ImageInstance, uploading an attached file, ...).
A Collection is a representation of a collection of models.
This class contains methods that allow you to fetch multiples models with filters and/or pagination (with max and offset parameters).
You can use the Collection class directly with a Model:
Collection c = new Collection<>(ImageInstance.class); c.addFilter("project", project.getId().toString()); c.fetch(); // will return all the image instance into the projectCollection c = new Collection<>(ImageInstance.class, 0,2); c.addFilter("project", project.getId().toString()); c.fetch(); // will return the two first image instances into the project
However, there is specific class in some case:
ImageInstanceCollection.fetchByProject(project); // will return all the image instance into the project ImageInstanceCollection.fetchByProject(project,0,2); // will return the two first image instances into the project
Usually, a specific class is created for :
- specific methods related to these models collection;
- syntaxic sugar;