watson_developer_cloud.visual_recognition_v3 module

Important: As of September 8, 2017, the beta period for Similarity Search is closed. For more information, see [Visual Recognition API – Similarity Search Update](https://www.ibm.com/blogs/bluemix/2017/08/visual-recognition-api-similarity-search-update).

The IBM Watson Visual Recognition service uses deep learning algorithms to identify scenes, objects, and faces in images you upload to the service. You can create and train a custom classifier to identify subjects that suit your needs.

Tip: To test calls to the Custom classifiers methods with the API explorer, provide your api_key from your Bluemix service instance.

class VisualRecognitionV3(version, url='https://gateway-a.watsonplatform.net/visual-recognition/api', api_key=None)

Bases: watson_developer_cloud.watson_service.WatsonService

The Visual Recognition V3 service.

default_url = 'https://gateway-a.watsonplatform.net/visual-recognition/api'

VERSION_DATE_2016_05_20 = '2016-05-20'

classify(images_file=None, parameters=None, accept_language=None, images_file_content_type=None, images_filename=None)

Classify images.

Parameters:

• images_file (file) – An image file (.jpg, .png) or .zip file with images. Include no more than 20 images and limit the .zip file to 5 MB. You can also include images with the url property in the parameters object.
• parameters (str) – Specifies input parameters. The parameter can include these inputs in a JSON object: - url: A string with the image URL to analyze. You can also include images in the images_file parameter. - classifier_ids: An array of classifier IDs to classify the images against. - owners: An array with the values IBM, me, or both to specify which classifiers to run. - threshold: A floating point value that specifies the minimum score a class must have to be displayed in the response. For example: {“url”: “…”, “classifier_ids”: [“…”,”…”], “owners”: [“IBM”, “me”], “threshold”: 0.4}.
• accept_language (str) – Specifies the language of the output class names. Can be en (English), ar (Arabic), de (German), es (Spanish), it (Italian), ja (Japanese), or ko (Korean). Classes for which no translation is available are omitted. The response might not be in the specified language under these conditions: - English is returned when the requested language is not supported. - Classes are not returned when there is no translation for them. - Custom classifiers returned with this method return tags in the language of the custom classifier.
• images_file_content_type (str) – The content type of images_file.
• images_filename (str) – The filename for images_file.

Returns:

A dict containing the ClassifiedImages response.

Return type:

dict

detect_faces(images_file=None, parameters=None, images_file_content_type=None, images_filename=None)

Detect faces in an image.

Parameters:

• images_file (file) – An image file (.jpg, .png) or .zip file with images. Include no more than 15 images. You can also include images with the url property in the parameters object. All faces are detected, but if there are more than 10 faces in an image, age and gender confidence scores might return scores of 0.
• parameters (str) – A JSON string containing the image URL to analyze. For example: {“url”: “…”}.
• images_file_content_type (str) – The content type of images_file.
• images_filename (str) – The filename for images_file.

Returns:

A dict containing the DetectedFaces response.

Return type:

dict

create_classifier(name, **kwargs)

Create a classifier.

Parameters:

• name (str) – The name of the new classifier. Cannot contain special characters.
• <NAME>_positive_examples (file) – A compressed (.zip) file of images that depict the visual subject for a class within the new classifier. Must contain a minimum of 10 images. The swagger limits you to training only one class. To train more classes, use the API functionality.
• negative_examples (file) – A compressed (.zip) file of images that do not depict the visual subject of any of the classes of the new classifier. Must contain a minimum of 10 images.

Returns:

A dict containing the Classifier response.

Return type:

dict

delete_classifier(classifier_id)

Delete a custom classifier.

Parameters:classifier_id (str) – The ID of the classifier. Return type:None

get_classifier(classifier_id)

Retrieve information about a custom classifier.

Parameters:classifier_id (str) – The ID of the classifier. Returns:A dict containing the Classifier response. Return type:dict

list_classifiers(verbose=None)

Retrieve a list of custom classifiers.

Parameters:verbose (bool) – Specify true to return classifier details. Omit this parameter to return a brief list of classifiers. Returns:A dict containing the Classifiers response. Return type:dict

update_classifier(classifier_id, **kwargs)

Update a classifier.

Parameters:

• classifier_id (str) – The ID of the classifier.
• <NAME>_positive_examples (file) – A compressed (.zip) file of images that depict the visual subject for a class within the classifier. Must contain a minimum of 10 images.
• negative_examples (file) – A compressed (.zip) file of images that do not depict the visual subject of any of the classes of the new classifier. Must contain a minimum of 10 images.

Returns:

A dict containing the Classifier response.

Return type:

dict

class Class(class_name)

Bases: object

A category within a classifier.

Attr str class_name:  The name of the class.

class ClassResult(class_name, score=None, type_hierarchy=None)

Bases: object

Result of a class within a classifier.

Attr str class_name:  The name of the class. Attr float score:  (optional) Confidence score for the property. Scores range from 0-1, with a higher score indicating greater correlation. Attr str type_hierarchy:  (optional) Knowledge graph of the property. For example, People/Leaders/Presidents/USA/Barack Obama. Included only if identified.

class ClassifiedImage(classifiers, source_url=None, resolved_url=None, image=None, error=None)

Bases: object

Classifier results for one image.

Attr str source_url:  (optional) Source of the image before any redirects. Not returned when the image is uploaded. Attr str resolved_url:  (optional) Fully resolved URL of the image after redirects are followed. Not returned when the image is uploaded. Attr str image:(optional) Relative path of the image file if uploaded directly. Not returned when the image is passed by URL. Attr ErrorInfo error:  (optional) Attr list[ClassifierResult] classifiers:  

class ClassifiedImages(images, custom_classes=None, images_processed=None, warnings=None)

Bases: object

Classify results for multiple images.

Attr int custom_classes:  (optional) The number of custom classes identified in the images. Attr int images_processed:  (optional) Number of images processed for the API call. Attr list[ClassifiedImage] images:  The array of classified images. Attr list[WarningInfo] warnings:  (optional) Information about what might cause less than optimal output. For example, a request sent with a corrupt .zip file and a list of image URLs will still complete, but does not return the expected output. Not returned when there is no warning.

class Classifier(classifier_id, name, owner=None, status=None, explanation=None, created=None, classes=None)

Bases: object

Information about a classifier.

Attr str classifier_id:  The ID of the classifier. Attr str name:The name of the classifier. Attr str owner:(optional) Unique ID of the account who owns the classifier. Attr str status:  (optional) The training status of classifier. Attr str explanation:  (optional) If classifier training has failed, this field may explain why. Attr datetime created:  (optional) The time and date when classifier was created. Attr list[Class] classes:  (optional) An array of classes that define a classifier.

class ClassifierResult(name, classifier_id, classes)

Bases: object

Classifier and score combination.

Attr str name:Name of the classifier. Attr str classifier_id:  Classifier ID. Only returned if custom classifier. Attr list[ClassResult] classes:  An array of classes within a classifier.

class Classifiers(classifiers)

Bases: object

Verbose list of classifiers retrieved in the GET v2/classifiers call.

Attr list[Classifier] classifiers:  

class DetectedFaces(images, images_processed=None, warnings=None)

Bases: object

DetectedFaces.

Attr int images_processed:  (optional) Number of images processed for the API call. Attr list[ImageWithFaces] images:  The array of images. Attr list[WarningInfo] warnings:  (optional) Information about what might cause less than optimal output. For example, a request sent with a corrupt .zip file and a list of image URLs will still complete, but does not return the expected output. Not returned when there is no warning.

class ErrorInfo(error_id, description)

Bases: object

Information about what might have caused a failure, such as an image that is too large. Not returned when there is no error.

Attr str error_id:  Codified error string. For example, limit_exceeded. Attr str description:  Human-readable error description. For example, File size limit exceeded.

class Face(age=None, gender=None, face_location=None, identity=None)

Bases: object

Provides information about the face.

Attr FaceAge age:  (optional) Attr FaceGender gender:  (optional) Attr FaceLocation face_location:  (optional) Attr FaceIdentity identity:  (optional)

class FaceAge(min=None, max=None, score=None)

Bases: object

Provides age information about a face. If there are more than 10 faces in an image, the response might return the confidence score `0g.

Attr int min:(optional) Estimated minimum age. Attr int max:(optional) Estimated maximum age. Attr float score:  (optional) Confidence score for the property. Scores range from 0-1, with a higher score indicating greater correlation.

class FaceGender(gender, score=None)

Bases: object

Provides information about the gender of the face. If there are more than 10 faces in an image, the response might return the confidence score 0.

Attr str gender:  Gender identified by the face. For example, MALE or FEMALE. Attr float score:  (optional) Confidence score for the property. Scores range from 0-1, with a higher score indicating greater correlation.

class FaceIdentity(name, score=None, type_hierarchy=None)

Bases: object

Provides information about a celebrity who is detected in the image. Not returned when a celebrity is not detected.

Attr str name:Name of the person. Attr float score:  (optional) Confidence score for the property. Scores range from 0-1, with a higher score indicating greater correlation. Attr str type_hierarchy:  (optional) Knowledge graph of the property. For example, People/Leaders/Presidents/USA/Barack Obama. Included only if identified.

class FaceLocation(width, height, left, top)

Bases: object

Defines the location of the bounding box around the face.

Attr float width:  Width in pixels of face region. Attr float height:  Height in pixels of face region. Attr float left:  X-position of top-left pixel of face region. Attr float top:Y-position of top-left pixel of face region.

class ImageWithFaces(faces, image=None, source_url=None, resolved_url=None, error=None)

Bases: object

ImageWithFaces.

Attr list[Face] faces:  An array of the faces detected in the images. Attr str image:(optional) Relative path of the image file if uploaded directly. Not returned when the image is passed by URL. Attr str source_url:  (optional) Source of the image before any redirects. Not returned when the image is uploaded. Attr str resolved_url:  (optional) Fully resolved URL of the image after redirects are followed. Not returned when the image is uploaded. Attr ErrorInfo error:  (optional)

class WarningInfo(warning_id, description)

Bases: object

Information about something that went wrong.

Attr str warning_id:  Codified warning string, such as limit_reached. Attr str description:  Information about the error.