Creating a custom classifier

After you classify an image in the Getting started example, you are ready to train and create a custom classifier. With a custom classifier, you can train the Visual Recognition service to classify images to suit your business needs.

Step 1: Log in, create the service, and get your credentials

If you created your free instance of the Visual Recognition service in "Getting started", use those credentials for this tutorial. If you haven't created a service, go back and run through those steps in the beginning of Getting Started.

Step 2: Creating a custom classifier

The Visual Recognition service can learn from example images you upload to create a new, multi-faceted classifier. Each example file is trained against the other files in that call, and positive examples are stored as classes. These classes are grouped to define a single classifier, but return their own scores.

Note: Negative example files are not stored as classes.

  1. Download the beagle.zip, husky.zip, golden-retriever.zip, and cats.zip example training files.

  2. Call the POST /v3/classifiers method with the following cURL command, which uploads the training data and creates the classifier "dogs":

    • Replace {api-key} with the service credentials you copied in the first step.
    • Modify the location of the {class}_positive_examples to point to where you saved the .zip files.
    curl -X POST -F "beagle_positive_examples=@beagle.zip" -F "husky_positive_examples=@husky.zip" -F "goldenretriever_positive_examples=@golden-retriever.zip" -F "negative_examples=@cats.zip" -F "name=dogs" "https://gateway-a.watsonplatform.net/visual-recognition/api/v3/classifiers?api_key={api-key}&version=2016-05-20"
    

    Positive example filenames require the suffix _positive_examples. In this example, the filenames are beagle_positive_examples, goldenretriever_positive_examples, and husky_positive_examples. The prefix (beagle, goldenretriever, and husky) is returned as the name of class.

    The response includes a new classifier ID and status, for example:

    {
      "classifier_id": "dogs_1941945966",
      "name": "dogs",
      "owner": "xxxx-xxxxx-xxx-xxxx",
      "status": "training",
      "created": "2016-05-18T21:32:27.752Z",
      "classes": [
        {"class": "husky"},
        {"class": "goldenretriever"},
        {"class": "beagle"}
      ]
    }
    
  3. Check the training status periodically until you see a status of ready. Training begins immediately and must finish before you can query the classifier. Replace {api key} and {classifier_id} with your information:

    curl -X GET "https://gateway-a.watsonplatform.net/visual-recognition/api/v3/classifiers/{classifier_id}?api_key={api-key}&version=2016-05-20"
    

Step 3: Updating an existing custom classifier

You can't update a custom classifier with a free API Key. You can update an existing Visual Recognition service custom classifier by adding new classes to an existing classifier, or by adding images to an existing class. Improve on the classifier that you created in step 2 by adding a Dalmatian class to the types of dogs which can be classified, and by adding more images of cats to the negative example set for the "dogs" classifier.

To add new classes to an existing classifier:

  1. Download the dalmatian.zip and more-cats.zip sample training files.

  2. Call the POST /v3/classifiers/{classifier_id} method with the following cURL command, which uploads the training data and updates the classifier "dogs_1941945966":

    • Replace {api-key} with the service credentials you copied in the first step.
    • Replace {classifier_id} with the ID of the classifier you want to update.
    • Modify the location of the {class}_positive_examples to point to where you saved the .zip files.
    curl -X POST -F "dalmatian_positive_examples=@dalmatian.zip" -F "negative_examples=@more-cats.zip"  "https://gateway-a.watsonplatform.net/visual-recognition/api/v3/classifiers/{classifier_id}?api_key={api-key}&version=2016-05-20"
    

    The existing "dogs" classifier is replaced by the retrained one with the same classifier_id. The response lists the new set of classes and the current status. For example:

    {
      "classifier_id": "dogs_1941945966",
      "name": "dogs",
      "owner": "xxxx-xxxxx-xxx-xxxx",
      "status": "retraining",
      "created": "2016-05-18T21:32:27.752Z",
      "classes": [
        {"class": "dalmatian"},
        {"class": "husky"},
        {"class": "goldenretriever"},
        {"class": "beagle"}
      ]
    }
    

    Training begins immediately. When the new one is available, the status changes to ready.

    Don't issue another retraining request until after the current status ready state. Multiple requests to retrain a classifier result in a single retraining taking effect. A timestamp called retrained shows the last time the classifier retraining completed.

    If you call the /classify method while the classifier is retraining, the old definition of the classifier is used.

  3. Check the training status periodically until you see a status of ready. Replace {api key} and {classifier_id} with your information:

    curl -X GET "https://gateway-a.watsonplatform.net/visual-recognition/api/v3/classifiers/{classifier_id}?api_key={api-key}&version=2016-05-20"
    

Step 4: Classifying an image with a custom classifier

When the new classifier completes training, you can call it to see how it performs.

  1. Create a JSON file called myparams.json that includes the parameters for your call, such as the classifier_id of your new classifier, and the default classifier. A simple JSON file might look like the following:

    {
    "classifier_ids": ["dogs_1941945966", "default"] 
    }
    
  2. Use the POST /v3/classify method to test your custom classifier. The following example uploads the image dogs.jpg, and classifies it against the "dogs_1941945966" classifier.

    • Replace {api-key} with the service credentials you copied in the first step.
    • To classify against default classes, omit the parameters parameter.
    curl -X POST -F "images_file=@dogs.jpg" -F "parameters=@myparams.json" "https://gateway-a.watsonplatform.net/visual-recognition/api/v3/classify?api_key={api-key}&version=2016-05-20"
    

    The response includes classifiers, their classes, and a score for each class. Scores range from 0-1, with a higher score indicating greater correlation. The /v3/classify calls omit low-scoring classes by default if high-scoring classes are identified. You can set a minimum score to display by specifying a floating point value for the threshold parameter in your call.

    {
      "images": [
        {
          "classifiers": [
            {
              "classes": [
                {
                  "class": "animal",
                  "score": 1.0,
                  "type_hierarchy": "/animals"
                },
                {
                  "class": "mammal",
                  "score": 1.0,
                  "type_hierarchy": "/animals/mammal"
                },
                {
                  "class": "dog",
                  "score": 0.880797,
                  "type_hierarchy": "/animals/pets/dog"
                }
              ],
              "classifier_id": "default",
              "name": "default"
            },
            {
              "classes": [
                {
                  "class": "goldenretriever",
                  "score": 0.610501
                }
              ],
              "classifier_id": "dogs_2084675858",
              "name": "dogs"
            }
          ],
          "image": "dogs.jpg"
        }
      ],
      "images_processed": 1
    }
    
  3. Review your results.

You're done! You created, trained, and queried a custom classifier with the Visual Recognition service.

Deleting your custom classifier

You might want to delete your custom classifier to begin developing your application with a clean instance.

To delete the classifier, call the DELETE /v3/classifiers/{classifier_id} method. Replace {api_key) with your information. Include the classifier_id for the classifier you want to delete:

curl -X DELETE "https://gateway-a.watsonplatform.net/visual-recognition/api/v3/classifiers/{classifier_id}?api_key={api-key}&version=2016-05-20"

Next steps

Now that you have a basic understanding of how to use the Visual Recognition service custom classifiers, you can dive deeper:

Attributions

All images used on this page are from Flikr and used under Creative Commons Attribution 2.0 license. No changes were made to these images.