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.

  • The base URL to use when contacting the service.

    Declaration

    Swift

    public var serviceURL: String?
  • 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
  • Service identifiers

    Declaration

    Swift

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

    Declaration

    Swift

    public var defaultHeaders: [String : String]
  • Undocumented

    Declaration

    Swift

    public let authenticator: Authenticator
  • 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
  • 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

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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

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

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

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

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

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

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