# How to upload an image using the Python client
In this tutorial we will see, with more details, 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 (opens new window) script available in the examples folder (opens new window) of the python client repository.
# 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 at least 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 (opens new window). But if your instance is on your computer only, it can also be http://localhost-core (opens new window) or equivalent. Please, adapt these steps to your configuration.
# 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, as usual, adapt the following commands to your 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, please 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 (opens new window)
# Step 4 : Locate your image
For this example we will use the cat vasculo-nervous pedicle hsm0080.svs (opens new window) file from the Cytomine Open Access Image collection (opens new window), 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
2
3
4
The first line say that the user "admin" is authentified, the second that he have access to his storage, and the third 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 :
# 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 (opens new window). You can see than 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
2
3
4
5
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 :
