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} Provide images to the IBM Watson Visual Recognition service for analysis. The service detects objects based on a set of images with training data.

  • 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 2019-02-11.

    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 2019-02-11.

    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()
  • Analyze images.

    Analyze images by URL, by file, or both against your own collection. Make sure that training_status.objects.ready is true for the feature before you use a collection to analyze images. 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.

    Declaration

    Swift

    public func analyze(
        collectionIDs: [String],
        features: [String],
        imagesFile: [FileWithMetadata]? = nil,
        imageURL: [String]? = nil,
        threshold: Double? = nil,
        headers: [String: String]? = nil,
        completionHandler: @escaping (WatsonResponse<AnalyzeResponse>?, WatsonError?) -> Void)

    Parameters

    collectionIDs

    The IDs of the collections to analyze.

    features

    The features to analyze.

    imagesFile

    An array of image files (.jpg or .png) or .zip files with images.

    • Include a maximum of 20 images in a request.
    • Limit the .zip file to 100 MB.
    • Limit each image file to 10 MB. You can also include an image with the image_url parameter.

    imageURL

    An array of URLs of image files (.jpg or .png).

    • Include a maximum of 20 images in a request.
    • Limit each image file to 10 MB.
    • Minimum width and height is 30 pixels, but the service tends to perform better with images that are at least 300 x 300 pixels. Maximum is 5400 pixels for either height or width. You can also include images with the images_file parameter.

    threshold

    The minimum score a feature must have to be returned.

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

    Create a collection that can be used to store images. To create a collection without specifying a name and description, include an empty JSON object in the request body. Encode the name and description in UTF-8 if they contain non-ASCII characters. The service assumes UTF-8 encoding if it encounters non-ASCII characters.

    Declaration

    Swift

    public func createCollection(
        name: String? = nil,
        description: String? = nil,
        headers: [String: String]? = nil,
        completionHandler: @escaping (WatsonResponse<Collection>?, WatsonError?) -> Void)

    Parameters

    name

    The name of the collection. The name can contain alphanumeric, underscore, hyphen, and dot characters. It cannot begin with the reserved prefix sys-.

    description

    The description of the collection.

    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

  • List collections.

    Retrieves a list of collections for the service instance.

    Declaration

    Swift

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

    Parameters

    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

  • Get collection details.

    Get details of one collection.

    Declaration

    Swift

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

    Parameters

    collectionID

    The identifier of the collection.

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

    Update the name or description of a collection. Encode the name and description in UTF-8 if they contain non-ASCII characters. The service assumes UTF-8 encoding if it encounters non-ASCII characters.

    Declaration

    Swift

    public func updateCollection(
        collectionID: String,
        name: String? = nil,
        description: String? = nil,
        headers: [String: String]? = nil,
        completionHandler: @escaping (WatsonResponse<Collection>?, WatsonError?) -> Void)

    Parameters

    collectionID

    The identifier of the collection.

    name

    The name of the collection. The name can contain alphanumeric, underscore, hyphen, and dot characters. It cannot begin with the reserved prefix sys-.

    description

    The description of the collection.

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

    Delete a collection from the service instance.

    Declaration

    Swift

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

    Parameters

    collectionID

    The identifier of the collection.

    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

  • Get a model.

    Download a model that you can deploy to detect objects in images. The collection must include a generated model, which is indicated in the response for the collection details as "rscnn_ready": true. If the value is false, train or retrain the collection to generate the model. Currently, the model format is specific to Android apps. For more information about how to deploy the model to your app, see the Watson Visual Recognition on Android project in GitHub.

    Declaration

    Swift

    public func getModelFile(
        collectionID: String,
        feature: String,
        modelFormat: String,
        headers: [String: String]? = nil,
        completionHandler: @escaping (WatsonResponse<Data>?, WatsonError?) -> Void)

    Parameters

    collectionID

    The identifier of the collection.

    feature

    The feature for the model.

    modelFormat

    The format of the returned model.

    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

  • Add images.

    Add images to a collection by URL, by file, or both. 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.

    Declaration

    Swift

    public func addImages(
        collectionID: String,
        imagesFile: [FileWithMetadata]? = nil,
        imageURL: [String]? = nil,
        trainingData: String? = nil,
        headers: [String: String]? = nil,
        completionHandler: @escaping (WatsonResponse<ImageDetailsList>?, WatsonError?) -> Void)

    Parameters

    collectionID

    The identifier of the collection.

    imagesFile

    An array of image files (.jpg or .png) or .zip files with images.

    • Include a maximum of 20 images in a request.
    • Limit the .zip file to 100 MB.
    • Limit each image file to 10 MB. You can also include an image with the image_url parameter.

    imageURL

    The array of URLs of image files (.jpg or .png).

    • Include a maximum of 20 images in a request.
    • Limit each image file to 10 MB.
    • Minimum width and height is 30 pixels, but the service tends to perform better with images that are at least 300 x 300 pixels. Maximum is 5400 pixels for either height or width. You can also include images with the images_file parameter.

    trainingData

    Training data for a single image. Include training data only if you add one image with the request. The object property can contain alphanumeric, underscore, hyphen, space, and dot characters. It cannot begin with the reserved prefix sys- and must be no longer than 32 characters.

    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

  • List images.

    Retrieves a list of images in a collection.

    Declaration

    Swift

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

    Parameters

    collectionID

    The identifier of the collection.

    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

  • Get image details.

    Get the details of an image in a collection.

    Declaration

    Swift

    public func getImageDetails(
        collectionID: String,
        imageID: String,
        headers: [String: String]? = nil,
        completionHandler: @escaping (WatsonResponse<ImageDetails>?, WatsonError?) -> Void)

    Parameters

    collectionID

    The identifier of the collection.

    imageID

    The identifier of the image.

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

    Delete one image from a collection.

    Declaration

    Swift

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

    Parameters

    collectionID

    The identifier of the collection.

    imageID

    The identifier of the image.

    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

  • Get a JPEG file of an image.

    Download a JPEG representation of an image.

    Declaration

    Swift

    public func getJpegImage(
        collectionID: String,
        imageID: String,
        size: String? = nil,
        headers: [String: String]? = nil,
        completionHandler: @escaping (WatsonResponse<Data>?, WatsonError?) -> Void)

    Parameters

    collectionID

    The identifier of the collection.

    imageID

    The identifier of the image.

    size

    The image size. Specify thumbnail to return a version that maintains the original aspect ratio but is no larger than 200 pixels in the larger dimension. For example, an original 800 x 1000 image is resized to 160 x 200 pixels.

    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

  • List object metadata.

    Retrieves a list of object names in a collection.

    Declaration

    Swift

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

    Parameters

    collectionID

    The identifier of the collection.

    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 an object name.

    Update the name of an object. A successful request updates the training data for all images that use the object.

    Declaration

    Swift

    public func updateObjectMetadata(
        collectionID: String,
        object: String,
        newObject: String,
        headers: [String: String]? = nil,
        completionHandler: @escaping (WatsonResponse<UpdateObjectMetadata>?, WatsonError?) -> Void)

    Parameters

    collectionID

    The identifier of the collection.

    object

    The name of the object.

    newObject

    The updated name of the object. The name can contain alphanumeric, underscore, hyphen, space, and dot characters. It cannot begin with the reserved prefix sys-.

    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

  • Get object metadata.

    Get the number of bounding boxes for a single object in a collection.

    Declaration

    Swift

    public func getObjectMetadata(
        collectionID: String,
        object: String,
        headers: [String: String]? = nil,
        completionHandler: @escaping (WatsonResponse<ObjectMetadata>?, WatsonError?) -> Void)

    Parameters

    collectionID

    The identifier of the collection.

    object

    The name of the object.

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

    Delete one object from a collection. A successful request deletes the training data from all images that use the object.

    Declaration

    Swift

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

    Parameters

    collectionID

    The identifier of the collection.

    object

    The name of the object.

    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

  • Train a collection.

    Start training on images in a collection. The collection must have enough training data and untrained data (the training_status.objects.data_changed is true). If training is in progress, the request queues the next training job.

    Declaration

    Swift

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

    Parameters

    collectionID

    The identifier of the collection.

    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

  • Add training data to an image.

    Add, update, or delete training data for an image. Encode the object name in UTF-8 if it contains non-ASCII characters. The service assumes UTF-8 encoding if it encounters non-ASCII characters. Elements in the request replace the existing elements.

    • To update the training data, provide both the unchanged and the new or changed values.
    • To delete the training data, provide an empty value for the training data.

    Declaration

    Swift

    public func addImageTrainingData(
        collectionID: String,
        imageID: String,
        objects: [TrainingDataObject]? = nil,
        headers: [String: String]? = nil,
        completionHandler: @escaping (WatsonResponse<TrainingDataObjects>?, WatsonError?) -> Void)

    Parameters

    collectionID

    The identifier of the collection.

    imageID

    The identifier of the image.

    objects

    Training data for specific objects.

    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

  • Get training usage.

    Information about the completed training events. You can use this information to determine how close you are to the training limits for the month.

    Declaration

    Swift

    public func getTrainingUsage(
        startTime: Date? = nil,
        endTime: Date? = nil,
        headers: [String: String]? = nil,
        completionHandler: @escaping (WatsonResponse<TrainingEvents>?, WatsonError?) -> Void)

    Parameters

    startTime

    The earliest day to include training events. Specify dates in YYYY-MM-DD format. If empty or not specified, the earliest training event is included.

    endTime

    The most recent day to include training events. Specify dates in YYYY-MM-DD format. All events for the day are included. If empty or not specified, the current day is used. Specify the same value as start_time to request events for a single day.

    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

  • Analyze images. Analyze images by URL, by file, or both against your own collection. Make sure that training_status.objects.ready is true for the feature before you use a collection to analyze images. 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.

    Declaration

    Swift

    public func analyze(
        images: [UIImage],
        collectionIDs: [String],
        features: [String],
        threshold: Double? = nil,
        headers: [String: String]? = nil,
        completionHandler: @escaping (WatsonResponse<AnalyzeResponse>?, WatsonError?) -> Void)

    Parameters

    images

    an array of UIImages to be classified

    collectionIDs

    The IDs of the collections to analyze. Separate multiple values with commas.

    features

    The features to analyze. Separate multiple values with commas.

    threshold

    The minimum score a feature must have to be returned.

    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