Python client

Available Docker container

For Docker users, a Docker image is available for the use of our Python client.
To open a Python terminal with an installed Cytomine client, you can run the command

sudo docker run -it cytomine/software-python3-base:v2.2.1

To run a Python script, _script.py_, don't forget to map the folder containing your script (and your output if needed)

sudo docker run -it -v /tmp:/tmp cytomine/software-python3-base:v2.2.1 python /tmp/script.py

How to install

Step 1 : Install Python on your computer

Our Python client is compatible with Python 2.7 and Python 3.6. The following explanations will be based on Python 3, however, they are similar for Python 2.

Important note : the python and pip commands will refer to the Python version running on your computer (assumed to be version 3 in our examples). BUT if you have both Python 2 and Python 3 installed on your computer, the python and pip commands will be associated to Python 2 and the python3 and pip3 commands will be associated to Python 3. So adapt the commands below to your running version.

The way to install Python depends of your OS or Linux distribution. For Windows and MacOS, you can find the installers on the Python.org official website download section.

For Linux, python is available with your package manager. For example, on Ubuntu and any debian-based linux distributions, you can install python and its package manager (pip) with the following command:

sudo apt-get install python3 python3-pip

Install python dependencies.

Our client is based on some python projects that we need to install with the following pip command:

pip install requests requests-toolbelt cachecontrol six future shapely numpy opencv-python-headless

Step 2 : Download the Cytomine Python client

There is two methods to download the Cytomine Python client source code from our GitHub repository before installing it: download a ZIP file, or using git to directly clone it on your computer. Not that this second method is better as it will be more easy, quick and efficient for later upgrades, using git pull.

By direct download of a ZIP file

Go to the Github repository of the Cytomine Python client, and clic on "Clone or Download", then on "Download ZIP".

Unzip the downloaded Cytomine-python-client.zip and enter the Cytomine-python-client folder.

Using GIT to clone the source code on your computer

First, you will have to install the git client.

For Windows and MacOS, please download and execute the installers available on the official Git website download section.

On debian based Linux distributions :

sudo apt-get install git

Then you will have to clone the source code where you want, and enter the Cytomine-python-client folder using these commands : 

git clone https://github.com/cytomine/Cytomine-python-client.git
cd Cytomine-python-client

Step 3 : Install the Cytomine Python client.

To install the Cytomine client, please enter the Cytomine-python-client folder, and use python to run the setup build and install scripts:

python setup.py build
python setup.py install

How to test it

First at all, you need 3 parameters to connect to a Cytomine instance :

  1. The host URL (example: https://demo.cytomine.coop)
  2. Your public key
  3. Your private key

These keys can be founded in your account setting.

Then, go to your Cytomine-python-client/examples directory. You will find there a test.py file with quite the following content:

# -*- coding: utf-8 -*-

import sys
from argparse import ArgumentParser

if __name__ == '__main__':
    from cytomine import Cytomine
    from cytomine.models.user import *

    parser = ArgumentParser(prog="Cytomine Python client example")

    # Cytomine
    parser.add_argument('--cytomine_host', dest='host', default='demo.cytomine.be', help="The Cytomine host")
    parser.add_argument('--cytomine_public_key', dest='public_key', help="The Cytomine public key")
    parser.add_argument('--cytomine_private_key', dest='private_key', help="The Cytomine private key")
    params, other = parser.parse_known_args(sys.argv[1:])

    with Cytomine(host=params.host, public_key=params.public_key, private_key=params.private_key) as cytomine:
        # Get the connected user
        user = CurrentUser().fetch()

If this file is not there, create it or upgrade your Cytomine Python client.

This code establish a connection with a Cytomine instance determined by its url and print the username of the connected user (the user related to the public and private keys).

Ru it with the command:

python test.py --cytomine_host "The_instance_URL" --cytomine_public_key "Your_public_key" --cytomine_private_key "Your_private_key"

where the The_instance_URL, Your_public_key and Your_private_key variables are replaced by the correct values related to your instance of Cytomine.

As a result, your Cytomine username will be printed on the terminal.

Important note : your python scripts can now be run from anywhere in your computer. Not only from inside Cytomine-python-client folder.

How to use it

Once you got the main concept of all the External clients, you can take a look at the examples scripts (and also the tests) that use the Python client for various interactions with a Cytomine instance (interaction with annotations, add a new user, get images, etc.).

Here is one example in action : How to upload an image using the Python client.