watson_developer_cloud.visual_recognition_v3 module¶

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.

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

Bases: watson_developer_cloud.watson_service.WatsonService

The Visual Recognition V3 service.

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

classify(images_file=None, parameters=None, accept_language=None, images_file_content_type=None, images_filename=None, url=None, threshold=None, owners=None, classifier_ids=None, **kwargs)[source]¶

Classify images.

Classify images with built-in or custom classifiers.

Parameters:	images_file (file) – An image file (.jpg, .png) or .zip file with images. Maximum image size is 10 MB. Include no more than 20 images and limit the .zip file to 100 MB. Encode the image and .zip file names in UTF-8 if they contain non-ASCII characters. The service assumes UTF-8 encoding if it encounters non-ASCII characters. You can also include images with the url property in the parameters object. parameters (str) – (Deprecated) A JSON object that specifies additional request options. The parameter can be sent as a string or a file, and can include these inputs: - url: A string with the image URL to analyze. Must be in .jpg, or .png format. The minimum recommended pixel density is 32X32 pixels per inch, and the maximum image size is 10 MB. You can also include images in the images_file parameter. - threshold: A floating point value that specifies the minimum score a class must have to be displayed in the response. The default threshold for returning scores from a classifier is 0.5. Set the threshold to 0.0 to ignore the classification score and return all values. - owners: An array of the categories of classifiers to apply. Use IBM to classify against the default general classifier, and use me to classify against your custom classifiers. To analyze the image against both classifier categories, set the value to both IBM and me. The built-in default classifier is used if both classifier_ids and owners parameters are empty. The classifier_ids parameter overrides owners, so make sure that classifier_ids is empty. - classifier_ids: Specifies which classifiers to apply and overrides the owners parameter. You can specify both custom and built-in classifiers. The built-in default classifier is used if both classifier_ids and owners parameters are empty. The following built-in classifier IDs require no training: - default: Returns classes from thousands of general tags. - food: (Beta) Enhances specificity and accuracy for images of food items. - explicit: (Beta) Evaluates whether the image might be pornographic. Example: {“classifier_ids”:[“CarsvsTrucks_1479118188”,”explicit”],”threshold”:0.6}. 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. url (str) – A string with the image URL to analyze. Must be in .jpg, or .png format. The minimum recommended pixel density is 32X32 pixels per inch, and the maximum image size is 10 MB. You can also include images in the images_file parameter. threshold (float) – A floating point value that specifies the minimum score a class must have to be displayed in the response. The default threshold for returning scores from a classifier is 0.5. Set the threshold to 0.0 to ignore the classification score and return all values. owners (list[str]) – An array of the categories of classifiers to apply. Use IBM to classify against the default general classifier, and use me to classify against your custom classifiers. To analyze the image against both classifier categories, set the value to both IBM and me. The built-in default classifier is used if both classifier_ids and owners parameters are empty. The classifier_ids parameter overrides owners, so make sure that classifier_ids is empty. classifier_ids (list[str]) – The classifier_ids parameter overrides owners, so make sure that classifier_ids is empty. - classifier_ids: Specifies which classifiers to apply and overrides the owners parameter. You can specify both custom and built-in classifiers. The built-in default classifier is used if both classifier_ids and owners parameters are empty. The following built-in classifier IDs require no training: - default: Returns classes from thousands of general tags. - food: (Beta) Enhances specificity and accuracy for images of food items. - explicit: (Beta) Evaluates whether the image might be pornographic. Example: “classifier_ids=”CarsvsTrucks_1479118188”,”explicit”. headers (dict) – A dict containing the request headers
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, url=None, **kwargs)[source]¶

Detect faces in images.

Analyze and get data about faces in images. Responses can include estimated age and gender, and the service can identify celebrities. This feature uses a built-in classifier, so you do not train it on custom classifiers. The Detect faces method does not support general biometric facial recognition.

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) – (Deprecated) A JSON object that specifies a single image (.jpg, .png) to analyze by URL. The parameter can be sent as a string or a file. Example: {“url”:”http://www.example.com/images/myimage.jpg”}. images_file_content_type (str) – The content type of images_file. images_filename (str) – The filename for images_file. url (str) – The URL of an image to analyze. Must be in .gif, .jpg, .png, or .tif format. The minimum recommended pixel density is 32X32 pixels per inch, and the maximum image size is 10 MB. Redirects are followed, so you can use a shortened URL. You can also include images with the images_file parameter. headers (dict) – A dict containing the request headers
Returns:	A dict containing the DetectedFaces response.
Return type:	dict

create_classifier(name, **kwargs)[source]¶: Create a classifier. :param str name: The name of the new classifier. Encode special characters in UTF-8. :param file <NAME>_positive_examples: 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. :param file negative_examples: 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. :param dict headers: A dict containing the request headers :return: A dict containing the Classifier response. :rtype: dict

delete_classifier(classifier_id, **kwargs)[source]¶

Delete a classifier.

Parameters:	classifier_id (str) – The ID of the classifier. headers (dict) – A dict containing the request headers
Return type:	None

get_classifier(classifier_id, **kwargs)[source]¶

Retrieve information about a custom classifier.

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

list_classifiers(verbose=None, **kwargs)[source]¶

Retrieve a list of classifiers.

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

update_classifier(classifier_id, **kwargs)[source]¶: Update a classifier. :param str classifier_id: The ID of the classifier. :param file <NAME>_positive_examples: A compressed (.zip) file of images that depict the visual subject for a class within the classifier. Must contain a minimum of 10 images. :param file negative_examples: 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. :param dict headers: A dict containing the request headers :return: A dict containing the Classifier response. :rtype: dict

get_core_ml_model(classifier_id, **kwargs)[source]¶

Retrieve a Core ML model of a classifier.

Download a Core ML model file (.mlmodel) of a custom classifier that returns core_ml_enabled: true in the classifier details.

Parameters:	classifier_id (str) – The ID of the classifier. headers (dict) – A dict containing the request headers
Returns:	A Response <Response> object representing the response.
Return type:	requests.models.Response

class Class(class_name)[source]¶

Attr str class_name:
	The name of the class.
Attr float score:
	(optional) Confidence score for the property in the range of 0 to 1. A higher score indicates greater likelihood that the class is depicted in the image. The default threshold for returning scores from a classifier is 0.5.
Attr str type_hierarchy:
	(optional) Knowledge graph of the property. For example, /fruit/pome/apple/eating apple/Granny Smith. Included only if identified.

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:

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.

Attr str classifier_id:
	ID of a classifier identified in the image.
Attr str name:	Name of the classifier.
Attr str owner:	(optional) Unique ID of the account who owns the classifier. Returned when verbose=`true`. Might not be returned by some requests.
Attr str status:
	(optional) The training status of classifier.
Attr bool core_ml_enabled:
	Whether the classifier can be downloaded as a Core ML model after the training status is ready.
Attr str explanation:
	(optional) If classifier training has failed, this field may explain why.
Attr datetime created:
	(optional) Date and time in Coordinated Universal Time (UTC) that the classifier was created.
Attr list[Class] classes:
	(optional) Array of classes that define a classifier.
Attr datetime retrained:
	(optional) Date and time in Coordinated Universal Time (UTC) that the classifier was updated. Returned when verbose=`true`. Might not be returned by some requests. Identical to updated and retained for backward compatibility.
Attr datetime updated:
	(optional) Date and time in Coordinated Universal Time (UTC) that the classifier was most recently updated. The field matches either retrained or created. Returned when verbose=`true`. Might not be returned by some requests.

Attr str classifier_id:
Attr str name:	Name of the classifier.
	The ID of a classifier identified in the image.
Attr list[ClassResult] classes:
	An array of classes within the classifier.

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.

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

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

Attr float score:
Attr int min:	(optional) Estimated minimum age.
Attr int max:	(optional) Estimated maximum age.
	(optional) Confidence score in the range of 0 to 1. A higher score indicates greater confidence in the estimated value for the property.

Attr str gender:
	Gender identified by the face. For example, MALE or FEMALE.
Attr float score:
	(optional) Confidence score in the range of 0 to 1. A higher score indicates greater confidence in the estimated value for the property.

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.

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)

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