VisualRecognition

public class VisualRecognition

IBM Watson™ Visual Recognition is discontinued. Existing instances are supported until 1 December 2021, but as of 7 January 2021, you can’t create instances. Any instance that is provisioned on 1 December 2021 will be deleted. {: deprecated} 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.

serviceURL
The base URL to use when contacting the service.
Declaration
Swift

public var serviceURL: String?
version
Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-03-19.
Declaration
Swift

public var version: String
defaultServiceName
Service identifiers
Declaration
Swift

public static let defaultServiceName: String
defaultHeaders
The default HTTP headers for all requests to the service.
Declaration
Swift

public var defaultHeaders: [String : String]
authenticator
Undocumented
Declaration
Swift

public let authenticator: Authenticator
init(version:authenticator:serviceName:)
Create a VisualRecognition object.

If an authenticator is not supplied, the initializer will retrieve credentials from the environment or a local credentials file and construct an appropriate authenticator using these credentials. The credentials file can be downloaded from your service instance on IBM Cloud as ibm-credentials.env. Make sure to add the credentials file to your project so that it can be loaded at runtime.

If an authenticator is not supplied and credentials are not available in the environment or a local credentials file, initialization will fail by throwing an exception. In that case, try another initializer that directly passes in the credentials.
- serviceName: String = defaultServiceName


                    
                    
                    init(version:authenticator:)

Create a VisualRecognition object.

Declaration

Swift

public init(version: String, authenticator: Authenticator)

Parameters

`version`	Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is `2018-03-19`.
`authenticator`	The Authenticator object used to authenticate requests to the service

disableSSLVerification()
Allow network requests to a server without verification of the server certificate. IMPORTANT: This should ONLY be used if truly intended, as it is unsafe otherwise.
Declaration
Swift

public func disableSSLVerification()


                    
                    
                    classify(imagesFile:imagesFilename:imagesFileContentType:url:threshold:owners:classifierIDs:acceptLanguage:headers:completionHandler:)

Classify images.

Classify images with built-in or custom classifiers.

Declaration

Swift

public func classify(
    imagesFile: Data? = nil,
    imagesFilename: String? = nil,
    imagesFileContentType: String? = nil,
    url: String? = nil,
    threshold: Double? = nil,
    owners: [String]? = nil,
    classifierIDs: [String]? = nil,
    acceptLanguage: String? = nil,
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<ClassifiedImages>?, WatsonError?) -> Void)

Parameters

`imagesFile`	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.
`imagesFilename`	The filename for imagesFile.
`imagesFileContentType`	The content type of imagesFile.
`url`	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`	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`	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.
`classifierIDs`	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.
`acceptLanguage`	The desired language of parts of the response. See the response for details.
`headers`	A dictionary of request headers to be sent with this request.
`completionHandler`	A function executed when the request completes with a successful result or error


                    
                    
                    createClassifier(name:positiveExamples:negativeExamples:negativeExamplesFilename:headers:completionHandler:)

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.
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.

Declaration

Swift

public func createClassifier(
    name: String,
    positiveExamples: [String: Data],
    negativeExamples: Data? = nil,
    negativeExamplesFilename: String? = nil,
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<Classifier>?, WatsonError?) -> Void)

Parameters

`name`	The name of the new classifier. Encode special characters in UTF-8.
`positiveExamples`	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.
`negativeExamples`	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.
`negativeExamplesFilename`	The filename for negativeExamples.
`headers`	A dictionary of request headers to be sent with this request.
`completionHandler`	A function executed when the request completes with a successful result or error


                    
                    
                    listClassifiers(verbose:headers:completionHandler:)

Retrieve a list of classifiers.

Declaration

Swift

public func listClassifiers(
    verbose: Bool? = nil,
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<Classifiers>?, WatsonError?) -> Void)

Parameters

`verbose`	Specify `true` to return details about the classifiers. Omit this parameter to return a brief list of classifiers.
`headers`	A dictionary of request headers to be sent with this request.
`completionHandler`	A function executed when the request completes with a successful result or error


                    
                    
                    getClassifier(classifierID:headers:completionHandler:)

Retrieve classifier details.

Retrieve information about a custom classifier.

Declaration

Swift

public func getClassifier(
    classifierID: String,
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<Classifier>?, WatsonError?) -> Void)

Parameters

`classifierID`	The ID of the classifier.
`headers`	A dictionary of request headers to be sent with this request.
`completionHandler`	A function executed when the request completes with a successful result or error


                    
                    
                    updateClassifier(classifierID:positiveExamples:negativeExamples:negativeExamplesFilename:headers:completionHandler:)

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. 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.
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.

Declaration

Swift

public func updateClassifier(
    classifierID: String,
    positiveExamples: [String: Data]? = nil,
    negativeExamples: Data? = nil,
    negativeExamplesFilename: String? = nil,
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<Classifier>?, WatsonError?) -> Void)

Parameters

`classifierID`	The ID of the classifier.
`positiveExamples`	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.
`negativeExamples`	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.
`negativeExamplesFilename`	The filename for negativeExamples.
`headers`	A dictionary of request headers to be sent with this request.
`completionHandler`	A function executed when the request completes with a successful result or error


                    
                    
                    deleteClassifier(classifierID:headers:completionHandler:)

Delete a classifier.

Declaration

Swift

public func deleteClassifier(
    classifierID: String,
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<Void>?, WatsonError?) -> Void)

Parameters

`classifierID`	The ID of the classifier.
`headers`	A dictionary of request headers to be sent with this request.
`completionHandler`	A function executed when the request completes with a successful result or error


                    
                    
                    getCoreMLModel(classifierID:headers:completionHandler:)

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.

Declaration

Swift

public func getCoreMLModel(
    classifierID: String,
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<Data>?, WatsonError?) -> Void)

Parameters

`classifierID`	The ID of the classifier.
`headers`	A dictionary of request headers to be sent with this request.
`completionHandler`	A function executed when the request completes with a successful result or error


                    
                    
                    deleteUserData(customerID:headers:completionHandler:)

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.

Declaration

Swift

public func deleteUserData(
    customerID: String,
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<Void>?, WatsonError?) -> Void)

Parameters

`customerID`	The customer ID for which all data is to be deleted.
`headers`	A dictionary of request headers to be sent with this request.
`completionHandler`	A function executed when the request completes with a successful result or error

Core ML


                    
                    
                    getLocalModel(classifierID:)

Retrieve a Core ML model from the local filesystem.

Declaration

Swift

public func getLocalModel(classifierID: String) throws -> MLModel

Parameters


                                classifierID

The ID of the classifier whose Core ML model will be retrieved.

Return Value

A Core ML model loaded from the local filesystem.


                    
                    
                    updateLocalModel(classifierID:completionHandler:)

Download the latest Core ML model to the local filesystem, unless the latest version is already available locally. The classifier must have a coreMLStatus of ready in order to download the latest model.

Declaration

Swift

public func updateLocalModel(
    classifierID: String,
    completionHandler: @escaping (WatsonResponse<Classifier>?, WatsonError?) -> Void)

Parameters

`classifierID`	The ID of the classifier whose Core ML model will be retrieved.
`completionHandler`	A function executed when the request completes with a successful result or error. If both the response and error are `nil`, then the Core ML model already exists locally.

listLocalModels()
List the Core ML models stored in the local filesystem.
Declaration
Swift

public func listLocalModels() throws -> [String]
Return Value

A list of classifier IDs with local Core ML models that are available for classification.


                    
                    
                    deleteLocalModel(classifierID:)

Delete a Core ML model from the local filesystem.

Declaration

Swift

public func deleteLocalModel(classifierID: String) throws

Parameters


                                classifierID

The ID of the classifier whose Core ML model shall be deleted.


                    
                    
                    classifyWithLocalModel(imageData:classifierIDs:threshold:completionHandler:)

Classify an image using a Core ML model from the local filesystem.

Declaration

Swift

public func classifyWithLocalModel(
    imageData: Data,
    classifierIDs: [String] = ["default"],
    threshold: Double? = nil,
    completionHandler: @escaping (ClassifiedImages?, WatsonError?) -> Void)

Parameters

`imageData`	The image to classify.
`classifierIDs`	A list of the classifier ids to use. “default” is the id of the built-in classifier.
`threshold`	The minimum score a class must have to be displayed in the response.
`completionHandler`	A function executed when the request completes with a successful result or error


                    
                    
                    classify(image:threshold:owners:classifierIDs:acceptLanguage:completionHandler:)

Classify images.

Classify images with built-in or custom classifiers.

Declaration

Swift

public func classify(
    image: UIImage,
    threshold: Double? = nil,
    owners: [String]? = nil,
    classifierIDs: [String]? = nil,
    acceptLanguage: String? = nil,
    completionHandler: @escaping (WatsonResponse<ClassifiedImages>?, WatsonError?) -> Void)

Parameters

`image`	An image to classify. Since the service limits images to 10MB, the image will be compressed. For greater control over the image’s compression, you should compress the image yourself, save it to a file, and call the other `classify` method.
`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 `imagesFile` 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 `classifierIDs` and `owners` parameters are empty. The `classifierIDs` parameter overrides `owners`, so make sure that `classifierIDs` is empty.
`classifierIDs`	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.
`acceptLanguage`	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.
`completionHandler`	A function executed when the request completes with a successful result or error


                    
                    
                    classifyWithLocalModel(image:classifierIDs:threshold:completionHandler:)

Classify an image using a Core ML model from the local filesystem.

Declaration

Swift

@available(iOS 11.0, tvOS 11.0, watchOS 4.0, *)
public func classifyWithLocalModel(
    image: UIImage,
    classifierIDs: [String] = ["default"],
    threshold: Double? = nil,
    completionHandler: @escaping (ClassifiedImages?, WatsonError?) -> Void)

Parameters

`image`	The image to classify.
`classifierIDs`	A list of the classifier ids to use. “default” is the id of the built-in classifier.
`threshold`	The minimum score a class must have to be displayed in the response.
`failure`	A function executed if an error occurs.
`success`	A function executed with the image classifications.