ibm_watson.visual_recognition_v3 module

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

class VisualRecognitionV3(version: str, authenticator: ibm_cloud_sdk_core.authenticators.authenticator.Authenticator = None, service_name: str = 'visual_recognition')

Bases: ibm_cloud_sdk_core.base_service.BaseService

The Visual Recognition V3 service.

DEFAULT_SERVICE_URL = 'https://api.us-south.visual-recognition.watson.cloud.ibm.com'

DEFAULT_SERVICE_NAME = 'visual_recognition'

classify(*, images_file: BinaryIO = None, images_filename: str = None, images_file_content_type: str = None, url: str = None, threshold: float = None, owners: str = None, classifier_ids: str = None, accept_language: str = None, **kwargs) → ibm_cloud_sdk_core.detailed_response.DetailedResponse

Classify images.

Classify images with built-in or custom classifiers.

Parameters

• images_file (TextIO) – (optional) An image file (.gif, .jpg, .png, .tif) 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 an image with the url parameter.

• images_filename (str) – (optional) The filename for images_file.

• images_file_content_type (str) – (optional) The content type of images_file.

• url (str) – (optional) The URL of an image (.gif, .jpg, .png, .tif) to analyze. The minimum recommended pixel density is 32X32 pixels, but the service tends to perform better with images that are at least 224 x 224 pixels. The maximum image size is 10 MB. You can also include images with the images_file parameter.

• threshold (float) – (optional) The minimum score a class must have to be displayed in the response. Set the threshold to 0.0 to return all identified classes.

• owners (List[str]) – (optional) The categories of classifiers to apply. The classifier_ids parameter overrides owners, so make sure that classifier_ids is empty. - Use IBM to classify against the default general classifier. You get the same result if both classifier_ids and owners parameters are empty. - Use me to classify against all your custom classifiers. However, for better performance use classifier_ids to specify the specific custom classifiers to apply. - Use both IBM and me to analyze the image against both classifier categories.

• classifier_ids (List[str]) – (optional) Which classifiers to apply. Overrides the owners parameter. You can specify both custom and built-in classifier IDs. 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: Enhances specificity and accuracy for images of food items. - explicit: Evaluates whether the image might be pornographic.

• accept_language (str) – (optional) The desired language of parts of the response. See the response for details.

• headers (dict) – A dict containing the request headers

Returns

A DetailedResponse containing the result, headers and HTTP status code.

Return type

DetailedResponse

create_classifier(name: str, positive_examples: BinaryIO, *, negative_examples: BinaryIO = None, negative_examples_filename: str = None, **kwargs) → ibm_cloud_sdk_core.detailed_response.DetailedResponse

Create a classifier.

Train a new multi-faceted classifier on the uploaded image data. Create your custom classifier with positive or negative example training images. Include at least two sets of examples, either two positive example files or one positive and one negative file. You can upload a maximum of 256 MB per call. Tips when creating: - If you set the X-Watson-Learning-Opt-Out header parameter to true when you create a classifier, the example training images are not stored. Save your training images locally. For more information, see [Data collection](#data-collection). - Encode all names in UTF-8 if they contain non-ASCII characters (.zip and image file names, and classifier and class names). The service assumes UTF-8 encoding if it encounters non-ASCII characters.

Parameters

• name (str) – The name of the new classifier. Encode special characters in UTF-8.

• positive_examples (dict) – A dictionary that contains the value for each classname. The value is a .zip file of images that depict the visual subject of a class in the new classifier. You can include more than one positive example file in a call. Specify the parameter name by appending _positive_examples to the class name. For example, goldenretriever_positive_examples creates the class goldenretriever. The string cannot contain the following characters: $ * - { } \ | / ' " ` [ ]. Include at least 10 images in .jpg or .png format. The minimum recommended image resolution is 32X32 pixels. The maximum number of images is 10,000 images or 100 MB per .zip file. Encode special characters in the file name in UTF-8.

• negative_examples (TextIO) – (optional) A .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. Encode special characters in the file name in UTF-8.

• negative_examples_filename (str) – (optional) The filename for negative_examples.

• headers (dict) – A dict containing the request headers

Returns

A DetailedResponse containing the result, headers and HTTP status code.

Return type

DetailedResponse

list_classifiers(*, verbose: bool = None, **kwargs) → ibm_cloud_sdk_core.detailed_response.DetailedResponse

Retrieve a list of classifiers.

Parameters

• verbose (bool) – (optional) 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 DetailedResponse containing the result, headers and HTTP status code.

Return type

DetailedResponse

get_classifier(classifier_id: str, **kwargs) → ibm_cloud_sdk_core.detailed_response.DetailedResponse

Retrieve classifier details.

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 DetailedResponse containing the result, headers and HTTP status code.

Return type

DetailedResponse

update_classifier(classifier_id: str, *, positive_examples: BinaryIO = {}, negative_examples: BinaryIO = None, negative_examples_filename: str = None, **kwargs) → ibm_cloud_sdk_core.detailed_response.DetailedResponse

Update a classifier.

Update a custom classifier by adding new positive or negative classes or by adding new images to existing classes. You must supply at least one set of positive or negative examples. For details, see [Updating custom classifiers](https://cloud.ibm.com/docs/visual-recognition?topic=visual-recognition-customizing#updating-custom-classifiers). Encode all names in UTF-8 if they contain non-ASCII characters (.zip and image file names, and classifier and class names). The service assumes UTF-8 encoding if it encounters non-ASCII characters. Tips about retraining: - You can’t update the classifier if the X-Watson-Learning-Opt-Out header parameter was set to true when the classifier was created. Training images are not stored in that case. Instead, create another classifier. For more information, see [Data collection](#data-collection). - Don’t make retraining calls on a classifier until the status is ready. When you submit retraining requests in parallel, the last request overwrites the previous requests. The retrained property shows the last time the classifier retraining finished.

Parameters

• classifier_id (str) – The ID of the classifier.

• positive_examples (dict) – (optional) A dictionary that contains the value for each classname. The value is a .zip file of images that depict the visual subject of a class in the classifier. The positive examples create or update classes in the classifier. You can include more than one positive example file in a call. Specify the parameter name by appending _positive_examples to the class name. For example, goldenretriever_positive_examples creates the class goldenretriever. The string cannot contain the following characters: $ * - { } \ | / ' " ` [ ]. Include at least 10 images in .jpg or .png format. The minimum recommended image resolution is 32X32 pixels. The maximum number of images is 10,000 images or 100 MB per .zip file. Encode special characters in the file name in UTF-8.

• negative_examples (TextIO) – (optional) A .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. Encode special characters in the file name in UTF-8.

• negative_examples_filename (str) – (optional) The filename for negative_examples.

• headers (dict) – A dict containing the request headers

Returns

A DetailedResponse containing the result, headers and HTTP status code.

Return type

DetailedResponse

delete_classifier(classifier_id: str, **kwargs) → ibm_cloud_sdk_core.detailed_response.DetailedResponse

Delete a classifier.

Parameters

• classifier_id (str) – The ID of the classifier.

• headers (dict) – A dict containing the request headers

Returns

A DetailedResponse containing the result, headers and HTTP status code.

Return type

DetailedResponse

get_core_ml_model(classifier_id: str, **kwargs) → ibm_cloud_sdk_core.detailed_response.DetailedResponse

Retrieve a Core ML model of a classifier.

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

Parameters

• classifier_id (str) – The ID of the classifier.

• headers (dict) – A dict containing the request headers

Returns

A DetailedResponse containing the result, headers and HTTP status code.

Return type

DetailedResponse

delete_user_data(customer_id: str, **kwargs) → ibm_cloud_sdk_core.detailed_response.DetailedResponse

Delete labeled data.

Deletes all data associated with a specified customer ID. The method has no effect if no data is associated with the customer ID. You associate a customer ID with data by passing the X-Watson-Metadata header with a request that passes data. For more information about personal data and customer IDs, see [Information security](https://cloud.ibm.com/docs/visual-recognition?topic=visual-recognition-information-security).

Parameters

• customer_id (str) – The customer ID for which all data is to be deleted.

• headers (dict) – A dict containing the request headers

Returns

A DetailedResponse containing the result, headers and HTTP status code.

Return type

DetailedResponse

class ClassifyEnums

Bases: object

class AcceptLanguage(value)

Bases: enum.Enum

The desired language of parts of the response. See the response for details.

EN = 'en'

AR = 'ar'

DE = 'de'

ES = 'es'

FR = 'fr'

IT = 'it'

JA = 'ja'

KO = 'ko'

PT_BR = 'pt-br'

ZH_CN = 'zh-cn'

ZH_TW = 'zh-tw'

class Class(class_: str)

Bases: object

A category within a classifier.

Attr str classclass_

The name of the class.

classmethod from_dict(_dict: Dict) → ibm_watson.visual_recognition_v3.Class

Initialize a Class object from a json dictionary.

to_dict() → Dict

Return a json dictionary representing this model.

class ClassResult(class_: str, score: float, *, type_hierarchy: str = None)

Bases: object

Result of a class within a classifier.

Attr str classclass_

Name of the class. Class names are translated in the language defined by the Accept-Language request header for the build-in classifier IDs (default, food, and explicit). Class names of custom classifiers are not translated. The response might not be in the specified language when the requested language is not supported or when there is no translation for the class name.

Attr float score

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.

classmethod from_dict(_dict: Dict) → ibm_watson.visual_recognition_v3.ClassResult

Initialize a ClassResult object from a json dictionary.

to_dict() → Dict

Return a json dictionary representing this model.

class ClassifiedImage(classifiers: List[ClassifierResult], *, source_url: str = None, resolved_url: str = None, image: str = None, error: Optional[ibm_watson.visual_recognition_v3.ErrorInfo] = None)

Bases: object

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) Information about what might have caused a failure, such as an image that is too large. Not returned when there is no error.

Attr List[ClassifierResult] classifiers

The classifiers.

classmethod from_dict(_dict: Dict) → ibm_watson.visual_recognition_v3.ClassifiedImage

Initialize a ClassifiedImage object from a json dictionary.

to_dict() → Dict

Return a json dictionary representing this model.

class ClassifiedImages(images: List[ClassifiedImage], *, custom_classes: int = None, images_processed: int = None, warnings: List[WarningInfo] = None)

Bases: object

Results for all images.

Attr int custom_classes

(optional) 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

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.

classmethod from_dict(_dict: Dict) → ibm_watson.visual_recognition_v3.ClassifiedImages

Initialize a ClassifiedImages object from a json dictionary.

to_dict() → Dict

Return a json dictionary representing this model.

class Classifier(classifier_id: str, name: str, *, owner: str = None, status: str = None, core_ml_enabled: bool = None, explanation: str = None, created: datetime.datetime = None, classes: List[Class] = None, retrained: datetime.datetime = None, updated: datetime.datetime = None)

Bases: object

Information about a classifier.

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. Might not be returned by some requests.

Attr str status

(optional) Training status of classifier.

Attr bool core_ml_enabled

(optional) 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 might explain why.

Attr datetime created

(optional) Date and time in Coordinated Universal Time (UTC) that the classifier was created.

Attr List[Class] classes

(optional) Classes that define a classifier.

Attr datetime retrained

(optional) Date and time in Coordinated Universal Time (UTC) that the classifier was updated. 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. Might not be returned by some requests.

classmethod from_dict(_dict: Dict) → ibm_watson.visual_recognition_v3.Classifier

Initialize a Classifier object from a json dictionary.

to_dict() → Dict

Return a json dictionary representing this model.

class StatusEnum(value)

Bases: enum.Enum

Training status of classifier.

READY = 'ready'

TRAINING = 'training'

RETRAINING = 'retraining'

FAILED = 'failed'

class ClassifierResult(name: str, classifier_id: str, classes: List[ClassResult])

Bases: object

Classifier and score combination.

Attr str name

Name of the classifier.

Attr str classifier_id

ID of a classifier identified in the image.

Attr List[ClassResult] classes

Classes within the classifier.

classmethod from_dict(_dict: Dict) → ibm_watson.visual_recognition_v3.ClassifierResult

Initialize a ClassifierResult object from a json dictionary.

to_dict() → Dict

Return a json dictionary representing this model.

class Classifiers(classifiers: List[Classifier])

Bases: object

A container for the list of classifiers.

Attr List[Classifier] classifiers

List of classifiers.

classmethod from_dict(_dict: Dict) → ibm_watson.visual_recognition_v3.Classifiers

Initialize a Classifiers object from a json dictionary.

to_dict() → Dict

Return a json dictionary representing this model.

class ErrorInfo(code: int, description: str, error_id: str)

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 int code

HTTP status code.

Attr str description

Human-readable error description. For example, File size limit exceeded.

Attr str error_id

Codified error string. For example, limit_exceeded.

classmethod from_dict(_dict: Dict) → ibm_watson.visual_recognition_v3.ErrorInfo

Initialize a ErrorInfo object from a json dictionary.

to_dict() → Dict

Return a json dictionary representing this model.

class WarningInfo(warning_id: str, description: str)

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.

classmethod from_dict(_dict: Dict) → ibm_watson.visual_recognition_v3.WarningInfo

Initialize a WarningInfo object from a json dictionary.

to_dict() → Dict

Return a json dictionary representing this model.