How to upload an image using the Python client

In this tutorial we will see how to use the Cytomine Python client to upload and image to a Cytomine instance, and to associate it to a project, using the upload_image.py script available in the examples folder.

Step 0 : have a USER type account on a Cytomine instance

For this tutorial, we will assume that you have an active user account in a running Cytomine instance, and this user account is a USER type, allowing you to upload images to this Cytomine.

In this tutorial, we will consider that this instancce respond at the main URL http://demo.cytomine.local. But if your instance is on your computer only, it can also be http://localhost-core or something like that.

Step 1 : install and test the Cytomine Python client

For this tutorial, we will consider that you have a Cytomine Python client installed and ready to run on your computer. If it's not yet done, please follow all the instructions detailed on the Python client page, including the test at the bottom of the page.

The upload_image.py script that we will use here is located in the "examples" folder inside your main Cytomine-python-client folder. You can run it from there, or move it anywhere on your computer, for example in the folder where are your images to upload.

For this tutorial we will assume it is located at /home/cytomine/Cytomine-python-client/examples/upload_image.py

Step 2 : get your user keys in your Cytomine instance

To alow the upload_image.py script to login in your name in the Cytomine instance, you must identify yourself using your user account public and private keys.

The keys are available in the account page of your Cytomine instance.

Here are the keys that we will use for this tutorial :

Cytomine user account keys  

Step 3 : get the upload URL of your Cytomine instance

When an image is uploaded to a Cytomine instance, it is using a distinct URL than the main one. This URL is mentioned as UPLOAD_URL in the configuration.sh script used when you have installed your instance.

If you do not have acces to this configuration.sh script, pleas ask your Cytomine administrator to give you this URL.

In our example, we will assume this UPLOAD_URL to be http://demo-upload.cytomine.local

Step 4 : locate your image

For this example we will use the cat vasculo-nervous pedicle hsm0080.svs file from the Cytomine Open Access Image collection, and will assume that it is stored in /media/data/images/hsm0080.svs path.

Step 5 : run the script and upload your image

The Cytomine Python client can be run from anywhere on your computer. To upload an image you have two solutions : run the upload_image.py script from the Cytomine-python-client/examples/ folder, or to move it in the folder where are your images.

We will give below the some examples, using all the informations collected in previous steps given as arguments.

Important note : the python command 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 command will be associated to Python 2 and the python3 command will be associated to Python 3. So adapt the commands below to your running version !

Run the upload_image.py from the /home/cytomine/Cytomine-python-client/examples folder, to upload an image located in /media/data/images/ :

python upload_image.py --cytomine_host "http://demo.cytomine.local" --cytomine_upload_host "http://demo-upload.cytomine.local" --cytomine_public_key "091d732d-89ae-43d7-bdfb-cc455d38680f" --cytomine_private_key "54efff2a-01e2-4f7f-b833-cbe609686ddf" --filepath "/media/data/images/HSM0080.svs"

Run the upload_image.py located in /home/cytomine/Cytomine-python-client/examples but from the /media/data/images/ folder, where the image is :

python /home/cytomine/Cytomine-python-client/examples/upload_image.py --cytomine_host "http://demo.cytomine.local" --cytomine_upload_host "http://demo-upload.cytomine.local" --cytomine_public_key "091d732d-89ae-43d7-bdfb-cc455d38680f" --cytomine_private_key "54efff2a-01e2-4f7f-b833-cbe609686ddf" --filepath "HSM0080.svs"

If you copy the upload_image.py script to /media/data/images/, you can use it from there to upload the image using :

python upload_image.py --cytomine_host "http://demo.cytomine.local" --cytomine_upload_host "http://demo-upload.cytomine.local" --cytomine_public_key "091d732d-89ae-43d7-bdfb-cc455d38680f" --cytomine_private_key "54efff2a-01e2-4f7f-b833-cbe609686ddf" --filepath "HSM0080.svs"

The latter command will give you this output :

[2020-05-13 04:39:21,730][INFO] [GET] [currentuser] CURRENT USER - 61 : admin | 200 OK
[2020-05-13 04:39:21,879][INFO] [GET] [storage collection] 1 objects | 200 OK
[2020-05-13 04:39:27,508][INFO] Image uploaded successfully to http://demo-upload.cytomine.local
[uploadedfile] 4135 : None

The first line say that the user "admin" is authentified, the second that he have access to his storage, and the that the file have been uploaded, and received the uploadedfile id 4135.
If we check in the front end, in the user storage, we will find this image, read to be used in projects :
HSM0080.svs file in storage after successfull upload  

Step 6 (optional) : upload AND add to a project

If you want to upload the image AND to add it in a specific project, you will have to get the ID of this project in the Cytomine instance database. This ID is available in the URL of your project.

Let's say your project URL is : http://demo3.cytomine.local/#/project/4233/images ==> your project ID is 4233. The above command can then receive an additional argument :

python upload_image.py --cytomine_host "http://demo.cytomine.local" --cytomine_upload_host "http://demo-upload.cytomine.local" --cytomine_public_key "091d732d-89ae-43d7-bdfb-cc455d38680f" --cytomine_private_key "54efff2a-01e2-4f7f-b833-cbe609686ddf" --filepath "HSM0080.svs" --cytomine_id_project "4233"

The output will then be :

[2020-05-13 04:52:37,900][INFO] [GET] [currentuser] CURRENT USER - 61 : admin | 200 OK
[2020-05-13 04:52:37,915][INFO] [GET] [project] 4233 : demo upload | 200 OK
[2020-05-13 04:52:37,925][INFO] [GET] [storage collection] 1 objects | 200 OK
[2020-05-13 04:52:42,233][INFO] Image uploaded successfully to http://demo-upload.cytomine.local
[uploadedfile] 4246 : None

The second line says that the project ID is correct and the project name is "demo upload".
After the upload, the image is in the user storage, and in this project image list :
HSM0080.svs file in project after successfull upload