Class: VisualRecognitionV3

VisualRecognitionV3

new VisualRecognitionV3(options)

Visual Recognition v3

Normal usage requires an API key. Dedicated instances require a username and password.

Parameters:
Name Type Description
options Object
Source:

Members

(static) VERSION_DATE_2016_05_20 :string

Type:
  • string
Source:
See:

Methods

addImage(params, callback)

Add an image to a collection Beta. Add images to a collection. Each collection can contain 1000000 images.

Example Response:

{ "images": [ { "image_id": "9725bc", "image_file": "obama.jpg", "created": "2016-09-20T14:41:49.927Z", "metadata": { "foo": "bar" } } ], "images_processed": 1 }

Parameters:
Name Type Description
params Object
Properties
Name Type Attributes Description
collection_id String
image_file ReadableStream

The image file (.jpg or .png) of the image to add to the collection. Maximum file size of 2 MB.

metadata Object <optional>

optional arbitrary metadata. This can be anything that can be specified in a JSON object. For example, key-value pairs. Maximum 2 KB of metadata for each image.

callback function
Source:

classify(params, callback) → {ReadableStream|undefined}

Accepts either a url, a single image file, or a zip file with multiple images (.jpeg, .png, .gif) and scores every available classifier on each image. It then applies a threshold and returns the list of relevant classifier scores for each image.

Parameters:
Name Type Description
params Object
Properties
Name Type Attributes Default Description
images_file ReadStream | Buffer | Object <optional>

The image file (.jpg, .png, .gif) or compressed (.zip) file of images to classify. The total number of images is limited to 20. Either images_file or url must be specified. The SDK attempts to determine content-type automatically, but this may be overridden by providing an object: {value: Buffer|Stream, options: {filename: 'file.ext', contentType: 'image/type'}}

url String <optional>

The URL of an image (.jpg, .png, .gif). Redirects are followed, so you can use shortened URLs. The resolved URL is returned in the response. Either images_file or url must be specified.

classifier_ids Array <optional>
['default']

An array of classifier IDs to classify the images against.

owners Array <optional>
['me','IBM']

An array with the value(s) "IBM" and/or "me" to specify which classifiers to run.

threshold Number <optional>

A floating point value that specifies the minimum score a class must have to be displayed in the response.

callback function
Source:
Returns:
Type
ReadableStream | undefined
Example
* {
  "images": [{
    "classifiers": [{
      "classes": [{
        "class": "animal",
        "score": 0.998771,
        "type_hierarchy": "/animals"
      }, {
        "class": "mammal",
        "score": 0.998499,
        "type_hierarchy": "/animals/mammal"
      }, {
        "class": "dog",
        "score": 0.900249,
        "type_hierarchy": "/animals/pets/dog"
      }, {
        "class": "puppy",
        "score": 0.5,
        "type_hierarchy": "/animals/pets/puppy"
      }],
      "classifier_id": "default",
      "name": "default"
    }],
    "image": "dog.jpg"
  }],
  "images_processed": 1
}

createClassifier(params) → {ReadableStream|undefined}

Train a new classifier from example images which are uploaded. This call returns before training has completed. You'll need to use the getClassifer method to make sure the classifier has completed training and was successful before you can classify any images with the newly created classifier.

Parameters:
Name Type Description
params Object
Properties
Name Type Attributes Description
name String

The desired short name of the new classifier.

classname_positive_examples ReadStream

_positive_examples One or more compressed (.zip) files of images that depict the visual subject for a class within the new classifier. Must contain a minimum of 10 images. You may supply multiple files with different class names in the key.

negative_examples ReadStream <optional>

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. Required if only one positive set is provided.

Source:
Returns:
Type
ReadableStream | undefined
Examples
{
  foo_positive_examples: fs.createReadStream('./foo-pics.zip'),
  negative_examples: fs.createReadStream('./not-foo-pics.zip'),
  name: 'to-foo-or-not'
}
{
 foo_positive_examples: fs.createReadStream('./foo-pics.zip'),
 bar_positive_examples: fs.createReadStream('./bar-pics.zip'),
 name: 'foo-vs-bar'
}
{
 foo_positive_examples: fs.createReadStream('./foo-pics.zip'),
 bar_positive_examples: fs.createReadStream('./bar-pics.zip'),
 negative_examples: fs.createReadStream('./not-foo-pics.zip'),
 name: 'foo-bar-not'
}
{
  "classifier_id": "fruit_679357912",
  "name": "fruit",
  "owner": "a3a48ea7-492b-448b-87d7-9dade8bde5a9",
  "status": "training",
  "created": "2016-05-23T21:50:41.680Z",
  "classes": [{
    "class": "banana"
  }, {
    "class": "apple"
  }]
}

createCollection(params, callback)

Create a collection Beta. Create a new collection of images to search. You can create a maximum of 5 collections.

Example response:

{ collection_id: 'integration_test_1474313373701_d9665f', name: 'integration_test_1474313373701', status: 'available', created: '2016-09-19T19:29:34.019Z', images: 0, capacity: 1000000 }

Parameters:
Name Type Description
params Object
Properties
Name Type Description
name String

The name of the new collection. The name can be a maximum of 128 UTF8 characters, with no spaces.

callback function
Source:

deleteClassifier(params, callback) → {ReadableStream|undefined}

Deletes a custom classifier with the specified classifier id.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
classifier_id String

The classifier id

callback function
Source:
Returns:
Type
ReadableStream | undefined

deleteCollection(params, callback)

Delete a collection Beta. Delete a user created collection.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
collection_id String
callback function
Source:

deleteImage(params, callback)

Delete an image Beta. Delete an image from a collection.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
collection_id String
image_id String
callback function
Source:

deleteImageMetadata(params, callback)

Delete image metadata Beta. Delete all metadata associated with an image.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
collection_id String
image_id ReadableStream
callback function
Source:

detectFaces(params, callback) → {ReadableStream|undefined}

Accepts either a url, a single image file, or a zip file with multiple images (.jpeg, .png, .gif) and attempts to extract faces and identities. It then applies a threshold and returns the list of relevant identities, locations, and metadata for found faces for each image.

Parameters:
Name Type Description
params Object
Properties
Name Type Attributes Description
images_file ReadStream <optional>

The image file (.jpg, .png, .gif) or compressed (.zip) file of images to classify. The total number of images is limited to 15. Either images_file or url must be specified.

url String <optional>

The URL of an image (.jpg, .png, .gif). Redirects are followed, so you can use shortened URLs. The resolved URL is returned in the response. Either images_file or url must be specified.

callback function
Source:
Returns:
Type
ReadableStream | undefined
Example
{
  "images": [{
    "faces": [{
      "age": {
        "max": 54,
        "min": 45,
        "score": 0.40459
      },
      "face_location": {
        "height": 131,
        "left": 80,
        "top": 68,
        "width": 123
      },
      "gender": {
        "gender": "MALE",
        "score": 0.993307
      },
      "identity": {
        "name": "Barack Obama",
        "score": 0.970688,
        "type_hierarchy": "/people/politicians/democrats/barack obama"
      }
    }],
    "image": "obama.jpg"
  }],
  "images_processed": 1
}

findSimilar(params, callback) → {ReadableStream|undefined}

Find similar images Beta. Upload an image to find similar images in your custom collection.

Example response:

{ "similar_images":[ { "image_id":"dresses_1257263", "created":"2016-09-04T21:49:16.908Z", "metadata":{ "weight":10, "cut":"a line", "color":"red" }, "score":"0.79" } ], "image_file":"red_dress.jpg", "images_processed": 1 }

Parameters:
Name Type Description
params Object
Properties
Name Type Attributes Default Description
collection_id String

The collection id

image_file ReadableStream

The image file (.jpg or .png) of the image to search against the collection.

limit Number <optional>
10

limit The number of similar results you want returned. Default limit is 10 results, you can specify a maximum limit of 100 results.

callback function
Source:
Returns:
Type
ReadableStream | undefined

getClassifier(params, callback) → {ReadableStream|undefined}

Retrieves information about a specific classifier.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
classifier_id Boolean

The classifier id

callback function
Source:
Returns:
Type
ReadableStream | undefined
Example
{
  "classifier_id": "fruit_679357912",
  "name": "fruit",
  "owner": "a3a42ea7-492b-448b-87d7-9dfde8bde519 ",
  "status": "ready",
  "created": "2016-05-23T21:50:41.680Z",
  "classes": [{
    "class": "banana"
  }, {
    "class": "apple"
  }]
}

getCollection(params, callback)

Retrieve collection details Beta. Retrieve information about a specific collection.

Example response:

{ collection_id: 'integration_test_1474313373701_d9665f', name: 'integration_test_1474313373701', status: 'available', created: '2016-09-19T19:29:34.019Z', images: 0, capacity: 1000000 }

Parameters:
Name Type Description
params Object
Properties
Name Type Description
collection_id String
callback function
Source:

getCredentialsFromBluemix() → {*}

Bluemix uses a different naming convention for VR v3 than for other services

Source:
Returns:
Type
*

getCredentialsFromEnvironment(name) → {Object}

Pulls api_key from the VISUAL_RECOGNITION_API_KEY env property

Also checks for VISUAL_RECOGNITION_USERNAME and VISUAL_RECOGNITION_PASSWORD for dedicated instances.

Parameters:
Name Type Description
name String
Source:
Returns:
Type
Object

getImage(params, callback)

Get image details Beta. List details about a specific image in a collection.

Example Response:

{ image_id: '83f3ff', image_file: 'obama.jpg', created: '2016-09-19T21:07:15.141Z'

Parameters:
Name Type Description
params Object
Properties
Name Type Description
collection_id String
image_id String
callback function
Source:

getImageMetadata(params, callback)

Get image metadata Beta. View the metadata for a specific image in a collection.

Example Response:

{"foo": "bar"}

Parameters:
Name Type Description
params Object
Properties
Name Type Description
collection_id String
image_id ReadableStream
callback function
Source:

listClassifiers(params, callback) → {ReadableStream|undefined}

Retrieve a list of all classifiers, including built-in and user-created classifiers.

Parameters:
Name Type Description
params Object
Properties
Name Type Attributes Default Description
verbose Boolean <optional>
false
callback function
Source:
Returns:
Type
ReadableStream | undefined
Example
{
  "classifiers": [{
    "classifier_id": "fruit_679357912",
    "name": "fruit",
    "status": "ready"
  }, {
    "classifier_id": "Dogs_2017013066",
    "name": "Dogs",
    "status": "ready"
  }]
}

listCollections(paramsopt, callback)

List collections Beta. List all custom collections.

Example response:

{ collections: [ { collection_id: 'integration_test_1474313967414_0e320b', name: 'integration_test_1474313967414', status: 'available', created: '2016-09-19T19:39:27.811Z', images: 0, capacity: 1000000 } ] }

Parameters:
Name Type Attributes Description
params Object <optional>
callback function
Source:

listImages(params, callback)

List images in a collection Beta. List the first 100 images in a collection. Each collection can contain 1000000 images.

Example Response:

{ images: [ { image_id: '83f3ff', image_file: 'obama.jpg', created: '2016-09-19T21:07:15.141Z' } ] }

Parameters:
Name Type Description
params Object
Properties
Name Type Attributes Description
collection_id String
image_file ReadableStream

The image file (.jpg or .png) of the image to add to the collection. Maximum file size of 2 MB.

metadata Object <optional>

optional arbitrary metadata. This can be anything that can be specified in a JSON object. For example, key-value pairs. Maximum 2 KB of metadata for each image.

callback function
Source:

recognizeText(params, callback) → {ReadableStream|undefined}

Accepts either a url, single image file, or a zip file with multiple images (.jpeg, .png, .gif) and attempts to recognize text found in the image. It then applies a threshold and returns the list of relevant locations, strings, and metadata for discovered text in each image.

Parameters:
Name Type Description
params Object
Properties
Name Type Attributes Description
images_file ReadStream <optional>

The image file (.jpg, .png, .gif) or compressed (.zip) file of images to classify. The total number of images is limited to 10. Either images_file or url must be specified.

url String <optional>

The URL of an image (.jpg, .png, .gif). Redirects are followed, so you can use shortened URLs. The resolved URL is returned in the response. Either images_file or url must be specified.

callback function
Source:
Returns:
Type
ReadableStream | undefined
Example
{
  "images": [{
    "image": "car.png",
    "text": "3 jag [brio]",
    "words": [{
      "line_number": 0,
      "location": {
        "height": 53,
        "left": 204,
        "top": 294,
        "width": 27
      },
      "score": 0.50612,
      "word": "3"
    }, {
      "line_number": 0,
      "location": {
        "height": 32,
        "left": 264,
        "top": 288,
        "width": 56
      },
      "score": 0.958628,
      "word": "jag"
    }, {
      "line_number": 0,
      "location": {
        "height": 40,
        "left": 324,
        "top": 288,
        "width": 92
      },
      "score": 0.00165806,
      "word": "brio"
    }]
  }],
  "images_processed": 1
}

retrainClassifier(params) → {ReadableStream|undefined}

Retrain a existing classifier from example images which are uploaded. This call returns before retraining has completed. You'll need to use the getClassifer method to make sure the classifier has completed retraining and was successful before you can classify any images with the retrained classifier.

Parameters:
Name Type Description
params Object
Properties
Name Type Attributes Description
classname_positive_examples ReadStream

_positive_examples One or more compressed (.zip) files of images that depict the visual subject for a class within the classifier. You may supply multiple files with different class names in the key.

negative_examples ReadStream <optional>

A compressed (.zip) file of images that do not depict the visual subject of any of the classes of the classifier.

Source:
Returns:
Type
ReadableStream | undefined
Example
{
  "classifier_id": "fruit_679357912",
  "name": "fruit",
  "owner": "a3a48ea7-492b-448b-87d7-9dade8bde5a9",
  "status": "training",
  "created": "2016-05-23T21:50:41.680Z",
  "classes": [{
    "class": "banana"
  }, {
    "class": "apple"
  }]
}

setImageMetadata(params, callback)

Add or update metadata Beta. Add metadata to a specific image in a collection.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
collection_id String
image_id String
metadata Object

Can be anything that can be specified in a JSON object. For example, key-value pairs. Maximum 2 KB of metadata for each image.

callback function
Source: