cmc/cleberg.net

  1#+date:        [2020-09-01 Tue 00:00:00]
  2#+title:       IBM Watson Vision API
  3#+description: Technical overview and application instructions for using IBM Watson Visual Recognition service, with focus on API configuration, image input processing, and classification output handling.
  4#+slug:        visual-recognition
  5#+filetags:    :linux:
  6
  7* What is IBM Watson?
  8
  9If you've never heard of [[https://www.ibm.com/watson][Watson]], this service is a suite of enterprise-ready
 10artificial intelligence (AI) services, applications, and tooling provided by
 11IBM. Watson contains quite a few useful tools for data scientists and students,
 12including the subject of this post today: visual recognition.
 13
 14If you'd like to view the official documentation for the Visual Recognition
 15application programming interface (API), visit the [[https://cloud.ibm.com/apidocs/visual-recognition/visual-recognition-v3?code=python][API Docs]].
 16
 17* Prerequisites
 18
 19To be able to use Watson Visual Recognition, you'll need the following:
 20
 211. Create a free account on [[https://www.ibm.com/cloud/watson-studio][IBM Watson Studio]].
 222. Add the [[https://www.ibm.com/cloud/watson-visual-recognition][Watson Visual Recognition]] service to your IBM Watson account.
 233. Get your API key and URL (uniform resource locator). To do this, first go to
 24   the [[https://dataplatform.cloud.ibm.com/home2?context=cpdaas][profile dashboard]] for your IBM account and click on the Watson Visual
 25   Recognition service you created. This will be listed in the section titled
 26   *Your services*. Then click the *Credentials* tab and open the
 27   *Auto-generated credentials* dropdown. Copy your API key and URL so that you
 28   can use them in the Python script later.
 294. *[Optional]* While not required, you can also create the Jupyter Notebook for
 30   this project right inside [[https://www.ibm.com/cloud/watson-studio][Watson Studio]]. Watson Studio will save your
 31   notebooks inside an organized project and allow you to use their other
 32   integrated products, such as storage containers, AI models, documentation,
 33   external sharing, etc.
 34
 35* Calling the IBM Watson Visual Recognition API
 36
 37Okay, now let's get started.
 38
 39To begin, we need to install the proper Python package for IBM Watson.
 40
 41#+begin_src sh
 42pip install --upgrade --user "ibm-watson>=4.5.0"
 43#+end_src
 44
 45Next, we need to specify the API key, version, and URL given to us when we
 46created the Watson Visual Recognition service.
 47
 48#+begin_src python
 49apikey = "<your-apikey>"
 50version = "2018-03-19"
 51url = "<your-url>"
 52#+end_src
 53
 54Now, let's import the necessary libraries and authenticate our service.
 55
 56#+begin_src python
 57import json
 58from ibm_watson import VisualRecognitionV3
 59from ibm_cloud_sdk_core.authenticators import IAMAuthenticator
 60
 61authenticator = IAMAuthenticator(apikey)
 62visual_recognition = VisualRecognitionV3(
 63  version=version,
 64  authenticator=authenticator
 65)
 66
 67visual_recognition.set_service_url(url)
 68#+end_src
 69
 70*[Optional]* If you'd like to tell the API not to use any data to improve their
 71products, set the following header.
 72
 73#+begin_src python
 74visual_recognition.set_default_headers({'x-watson-learning-opt-out': "true"})
 75#+end_src
 76
 77Now we have our API all set and ready to go. For this example, I'm going to
 78include a =dict= of photos to load as we test out the API.
 79
 80#+begin_src python
 81data = [
 82  {
 83    "title": "Grizzly Bear",
 84    "url": "https://example.com/photos/image1.jpg"
 85  },
 86  {
 87    "title": "Nature Lake",
 88    "url": "https://example.com/photos/image2.jpg"
 89  },
 90  {
 91    "title": "Welcome Sign",
 92    "url": "https://example.com/photos/image3.jpg"
 93  },
 94  {
 95    "title": "Honey Badger",
 96    "url": "https://example.com/photos/image4.jpg"
 97  },
 98  {
 99    "title": "Grand Canyon Lizard",
100    "url": "https://example.com/photos/image5.jpg"
101  },
102  {
103    "title": "Castle",
104    "url": "https://example.com/photos/image6.jpg"
105  }
106]
107#+end_src
108
109Now that we've set up our libraries and have the photos ready, let's create a
110loop to call the API for each image. The code below shows a loop that calls the
111URL of each image and sends it to the API, requesting results with at least 60%
112confidence. The results are output to the console with dotted lines separating
113each section.
114
115In the case of an API error, the codes and explanations are output to the
116console.
117
118#+begin_src python
119from ibm_watson import ApiException
120
121for x in range(len(data)):
122try:
123   url = data[x]["url"]
124   images_filename = data[x]["title"]
125   classes = visual_recognition.classify(
126       url=url,
127       images_filename=images_filename,
128       threshold='0.6',
129       owners=["IBM"]).get_result()
130   print("-----------------------------------------------")
131   print("Image Title: ", data[x]["title"], "\n")
132   print("Image URL: ", data[x]["url"], "\n")
133   classification_results = classes["images"][0]["classifiers"][0]["classes"]
134   for result in classification_results:
135       print(result["class"], "(", result["score"], ")")
136   print("-----------------------------------------------")
137except ApiException as ex:
138   print("Method failed with status code " + str(ex.code) + ": " + ex.message)
139#+end_src
140
141* The Results
142
143Here we can see the full result set of our function above. If you view each of
144the URLs that we sent to the API, you'll be able to see that it was remarkably
145accurate. To be fair, these are clear high-resolution, clear photos shot with a
146professional camera. In reality, you will most likely be processing images that
147are lower quality and may have a lot of noise in the photo.
148
149However, we can clearly see the benefit of being able to call this API instead
150of attempting to write our own image recognition function. Each of the
151classifications returned was a fair description of the image.
152
153If you wanted to restrict the results to those that are at least 90% confident
154or greater, you would simply adjust the =threshold= in the
155=visual_recognition.classify()= function.
156
157When your program runs, it should show the output below for each photo you
158provide.
159
160#+begin_src txt
161----------------------------------------------------------------
162Image Title:  Grizzly Bear
163Image URL: https://example.com/photos/image1.jpg
164
165brown bear ( 0.944 )
166bear ( 1 )
167carnivore ( 1 )
168mammal ( 1 )
169animal ( 1 )
170Alaskan brown bear ( 0.759 )
171greenishness color ( 0.975 )
172----------------------------------------------------------------
173#+end_src
174
175* Discussion
176
177Now, this was a very minimal implementation of the API. We simply supplied some
178images and looked to see how accurate the results were. However, you could
179implement this type of API into many machine learning (ML) models.
180
181For example, you could be working for a company that scans their warehouses or
182inventory using drones. Would you want to pay employees to sit there and watch
183drone footage all day in order to identify or count things in the video?
184Probably not. Instead, you could use a classification system similar to this one
185in order to train your machine learning model to correctly identify items that
186the drones show through video. More specifically, you could have your machine
187learning model watch a drone fly over a field of sheep in order to count how
188many sheep are living in that field.
189
190There are many ways to implement machine learning functionality, but hopefully
191this post helped inspire some deeper thought about the tools that can help
192propel us further into the future of machine learning and AI.