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
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
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
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.
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.
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
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
First at all, you need 3 parameters to connect to a Cytomine instance :
- The host URL (example: https://demo.cytomine.coop)
- Your public key
- 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() print(user)
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.
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.