Skill Level: Any Skill Level

This Watson Visual Recognition component let's us customize ( or train ) images ( photos in jpg or png format) as positive and negative images and once done - we can call this with a sample image to arrive at closest score, or closest match.


You will need a Bluemix Id, multiple image zip files ( or less than 5 MB ), and a sample image in png or jpg format.

A server with Curl installed and some basic understanding or knowledge of what it does and how to use it.


  1. Create a Bluemix ID, and prepare to use the Visual Recognition Service.

    Where could this Visual Recognition component be useful :
    Let's say you are building a Robot with a visual capability using a webcam, and it needs to navigate thru a maze and there are road signs, left and right. The robot would be trained to recognize them and move or glide along respectively.


    Let's say a certain office would like to monitor the employees walking in thru a back door, and act accordingly, then the Visual Recognition component could be trained to understand or learn the employees faces and then when a new employee's face appears not to match – an appropriate action will be undertaken.

    There are multiple use cases where this can be used.


    To begin using the service, follow these steps.

    Log in to Bluemix at
    Create an instance of the service:

    In the Bluemix Catalog, select your service.
    Under Add Service, type a unique name for the service instance in the Service name field. For example, type tutorial-<username>. Leave the default values for the other options.
    Click Create.
    Copy your credentials:

    Click Service Credentials to view your service credentials.
    Copy your credentials.

    ¬†( it would look something like “2ad1de1d6651cba0046f8b4d7056d6d9aeXXXX” )

  2. Overall steps that we are going to follow in this blog.

     Details on how to use each command will follow- but this is just an introduction to various commands that we are going to use.

    1. Customize or Train our Visual Recognition instance to understand just the images we are interested in.

    Once this is done – the VR instance generates a unique “classifier_id”. Use this classifier “id” for further use.

    2. Once done, check that the training is ready by issuing a curl command and validating that the image classification or training is “ready” to be used.

    Use the “classifier id ” to check on the status.

    If the status is not “ready” then wait until the training is fully interpreted by the Watson Visual Recognition component.

    3. Classify the image. ( meaning “interpret” ) the image.

    Provide the “classifier id” to interpret or classify the image.

    4. List the images  that our VR instance is trained or configured to  interpret.

    Will list all the classfiers that are configured under our API Key.

    5. Delete the classifier id

    Will delete any “classifier id”s from our instance.¬† Will help when we are testing and if we want to recreate multiple instances.


    and now .. the details.

  3. Train the Visual Recognition ( or Create classifiers )

     The first thing I need to do is set up a libraries containing the positive and negative images.
    Positive images are images that I am interested in intrepreting.
    Negative Images are ones that are reverse of images that I am interested in.

    e.g: Left Road signs, Vs Right Road Signs.
    Cars Vs Trucks
    Dogs Vs Cats  // Dog images are ones that I am going to be using for reference and if it is a Cat Image that means I am NOT interested in it. Things like that.

    Libraries in my opinion are zip files of images.

    Currently in my experience a zip file of jpg or png of 5 MB or less .

    It is good to have at least 50 sample images in the zip file ( approx ) to get a good result.


    Format of the command to Classify or Train.

    There would be multiple sets of zip files that we might want to classify, and the format would be on lines of “positive” and “negative” sets.

    All the images that we want to positively identify would be classified as “positive images”, and likewise the opposite set would be called “negative images”… that ones that are not identified as positive.

    e.g:¬† We can have 2 sets of images or zip files,¬† One with all “Right Road Signs” call it “positive”, and another set to contain “Left road signs” or call it “negative”.

    There can also be just positive sets or zip files that contain the images that we would like to store in our library. ( The negative files are optional )


    We can provide both the Positive and Negative sets during training.

    Here I will create a set to do both the Positive and Negative Training of images.


    ( I'd think of this positive sets as a library that the Visual Recognition component would refer further down the road when a new image is provided to be interpreted. )

    curl -X POST -F “” -F “” -F “name=roadsigns” “${api_key}&version=2016-05-20”

    Here, the keyword is “positive_examples” and “negative_examples”. The positive examples can be prefixed with an identifier of our choice, in this case it is “right_positive_examples”.


    – The “roadsigns” is just an identifier that I would like to use in the “classifier_id” that this command returns.

    (I have a small shell script where I have exported the API_KEY that I got during registration and used the command above.)


  4. Check if the Training of the images is done or "ready"

    The Visual Recognition takes a certain amount of time 1-2 minutes or more depending on the size of the image file.

    To determine if this is ready – use this command and it should show that the classifier is ready.


    A simple script can be constructed as shown:


    export api_key=”23456789XXXXX”

    curl -X GET “${classifier_id}?api_key=${api_key}&version=2016-05-20”


    Returns a JSON as shown:

    “classifier_id”: “roadsigns_1720015993”,
    “name”: “roadsigns”,
    “owner”: “a01f7f63-e008-4544-9164-b325c460635d”,
    “status”: “ready”,
    “created”: “2016-12-12T12:04:29.710Z”,
    “classes”: [{“class”: “right”}]}

  5. Classify ( or Interpret) the new image by looking at the Positive and Negative samples.


    Let's say I want to interpret this new image by looking at the reference zip files that was provided during the earlier custom classifier stage ( the first step ).


    Create a simple JSON file in the same folder where we have trained the images and insert the classifier_id


    “classifier_ids”: [“roadsigns_1619963636”, “default”]


    The classifier id “default” means to look up IBMs default Visual recognition engine during interpretation as well.

    If we want to just refer to our library only – then¬† remove the keyword “default”


    “classifier_ids”: [“roadsigns_1619963636”]


    A simple shell script ( with the “default” classifier-id in the myparams.json file )


    export api_key=”234567890XXXX”

    curl -X POST -F “images_file=@leftimage_sample.png” -F “parameters=@myparams.json” “${api_key}&version=2016-05-20”



    “classifiers”: [
    “classes”: [
    “class”: “logo”,
    “score”: 0.524979,
    “type_hierarchy”: “/products/materials/graphics/logo”
    “classifier_id”: “default”,
    “name”: “default”
    “classes”: [
    “class”: “roundel”,
    “score”: 0.946
    “class”: “plate”,
    “score”: 0.949
    “class”: “shield”,
    “score”: 0.952
    “class”: “ultramarine color”,
    “score”: 0.907
    “classifier_id”: “default”,
    “name”: “default”
    “image”: “leftimage_sample.png”
    “images_processed”: 1


  6. Interpreting the scores.

    Lower the score, lower it is resembling the positive images.

    Now, to get a good or better scoring – set the threshold=0 in the curl query.

    Also check the json file to see the list of libraries ( or classifier_id)  we are referring to.

    notice that the “default is missing” – so this means you will NOT see the corresponding “default” identifier in the JSON output.

    “classifier_ids”: [“roadsigns_608210761”]


    some examples :

    curl -X POST -F “images_file=@leftimage_sample.png” -F “parameters=@myparams.json” “${api_key}&version=2016-05-20&threshold=0


    curl -X POST -F “images_file=@rightimage_sample.png” -F “parameters=@myparams.json” “${api_key}&version=2016-05-20&threshold=0”

    Right Image : ( notice the score ) , The right images are classified as Positive images.



    Left Image: ( notice the score ) The left images are classified as negative images.



    The myparams.json is as follows.



    This concludes the demo.

  7. Deleting the classifier


    A simple shell script  would take in the api_key that was generated at the time of creation of the service.


    curl -X DELETE “$1?api_key=${api_key}&version=2016-05-20”

  8. Listing the classifiers

    Let's say we want to list the classifiers that are created for this API Key,


    Shell Script:


    export api_key=”1234567890XXX”

    curl -X GET “${api_key}&version=2016-05-20”


    The response JSON is :

    {“classifiers”: [{
    “classifier_id”: “roadsigns_1720015993”,
    “name”: “roadsigns”,
    “status”: “ready”



  9. Sample Classifiers

  10. References used in this blog.


Join The Discussion