The Python client allows to interact with Cytomine-core through the RESTful API using Python.
First, setup a Python environment using Miniconda installer, i.e. get the installer script, run it, and add the Anaconda binary directory to your PATH variable. Here is the example for Linux installation:
Follow the installer instructions and when installed, create a Python environment with required client dependencies. The Python client supports Python 2.7 and Python > 3.6 but we recommend to use it in its Python 3 version as the end of support for Python 2 is announced by 2020.
The easiest way to get the Python client is to clone it from Github. If you don't have git on your machine, install it
Clone the Cytomine Python client from our repository
Install the basic Cytomine client with basic functions to communicate with the Cytomine-Core. Pay attention you are in the "cytomine" Python environment.
The client is installed.
Usage and Examples
This Section illustrates how to use the Cytomine-Python-Client to manipulate (import/export/create/delete/...) Cytomine data. Additional examples are available in the Examples Section on the Github repository.
You need 3 parameters to connect to a Cytomine instance :
- The host URL (example: demo.cytomine.be)
- Your public key
- Your private key
It is recommended to use the with statement to establish the HTTP session between the client and the sever. The "with statement" block is a Python feature to efficiently deal with data flows.
The verbose parameter allows to change the verbosity level. By default, it is set to INFO, which prints a summary of a resource when fetched, saved, updated or deleted. See the Python standard logging module for more information.
Another possibility to connect, especially for short scripts is to use the
It is still possible to connect by simply instantiate the Cytomine class for backwards compatibility reasons but is deprecated.
A Cytomine resource (e.g. a project A) is an instance of a domain (e.g. Project). In the client, a resource is a Python object which is an instance of a model class describing its domain. Each object (an instance of model):
- has a set of attributes corresponding to resource attributes
- is managed itself through
delete()methods that communicate with the Cytomine-core server
- has some utilities to be serialized to JSON
- a dictionary of query parameters that will appear in the request: resource.json?param1=value1 (seldom used for models)
A simple example with a project resource:
In some cases, the server provides supplementary actions for some resources. These actions are encapsulated in additional methods for the model.
Download the original file behind an abstract image.
The download() method will get the image and copy it into the temporary directory. The name of the file is the original filename stored into Cytomine-core because the destination path is parsed, and every model attribute can be used. For example, it is possible to save the image with a filename which contains its Cytomine ID, its width and height:
Get the spectrum for a given pixel in an Image Group HDF5.
The pixel request makes the appropriate GET request in background.
A collection is a list of objects that have the same model. A collection is fetched with
For example, to get the list of all projects you have access to:
Collection class extends the Python
MutableSequence class. You can thus work with a collection like with any Python list:
The API often allows to filter a list of resources with an other resource, by specifiying it in the URI. The filtering by URI is performed using the
fetch_with_filter() method. The list of allowed filters for a collection is given by
It will make the appropriate GET request, e.g. :
The behavior of collection requests can sometimes be modified with some query parameters. In the case of collections, these query parameters are the attributes of the Collection class. For example, we can obtain the list of online users with a query parameter:
Particular case: a collection of annotations
A list of annotations can be filtered with many filters (project, user, image, term, ...). The only way given by the API to filter a list of annotations is to use query parameters.
Multiple adds in one request
When you have a lot of new objects belonging to the same model to add, it may be interesting to send these multiple new objects in one request for all instead of one by one (default behavior). The multiple add is currently only supported for Annotation model. Instead of saving annotation one by one, append them into a collection and save the collection:
It is your responsibility to choose which method to use. If you send to much requests (lot of annotations one by one), the server may flush some of your requests if too busy. On the other hand, if you send too much objects in one requests (ex: 100000 annotations in one request) there are many chances that the HTTP request is too heavy for the server.
A bunch of examples are provided with the Python client in the directory Cytomine-python-client/examples/ (see here)
These are ready-to-use scripts for common tasks.
Notes for users of deprecated Python client versions
Previous version were only available in Python 2.7 which was a high limitation.
Most of code written with previous versions should be compatible with new one, but no guarantee is given.
This new version is a complete rewrite of the Python client and improves and adds a lot of features:
- Compatibility Python 2.7 / 3+
- Logging with verbosity levels (standard Python logger)
- Use requests library to handle HTTP
- Collections are iterable
- Model's attributes are written in the code: code is self-documented and ease auto-completion
- Cytomine class is a singleton and its no more necessary to pass it as parameter in every functions
- Model and Collection are self managed
- CytomineJob class extends Cytomine and is thus a singleton where the current user is a user-job.