JSDoc: Class: VisualRecognitionV3

new VisualRecognitionV3(options)

Parameters:

Name	Type	Description
`options`

Source:

visual-recognition/v3.js, line 90

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:

visual-recognition/v3.js, line 791

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

visual-recognition/v3.js, line 198

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:

visual-recognition/v3.js, line 465

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:

visual-recognition/v3.js, line 652

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:

visual-recognition/v3.js, line 618

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:

visual-recognition/v3.js, line 747

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:

visual-recognition/v3.js, line 895

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:

visual-recognition/v3.js, line 989

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:

visual-recognition/v3.js, line 292

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
`classifier_id`	String			The classifier 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:

visual-recognition/v3.js, line 1036

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:

visual-recognition/v3.js, line 596

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:

visual-recognition/v3.js, line 686

getCredentialsFromBluemix() → {*}

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

Source:

visual-recognition/v3.js, line 148

Returns:

Type: *

getCredentialsFromEnvironment(name) → {Object}

Pulls api_key from SERVICE_NAME_API_KEY env property

Parameters:

Name	Type	Description
`name`	String

Source:

visual-recognition/v3.js, line 138

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:

visual-recognition/v3.js, line 870

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:

visual-recognition/v3.js, line 963

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:

visual-recognition/v3.js, line 561

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:

visual-recognition/v3.js, line 721

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:

visual-recognition/v3.js, line 839

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:

visual-recognition/v3.js, line 382

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:

visual-recognition/v3.js, line 519

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:

visual-recognition/v3.js, line 921