<commit_before># Integrating the Watson Developer Cloud AlchemyAPI AlchemyVision Image Tagging Service with Watson Explorer

[IBM Watson Explorer](http://www.ibm.com/smarterplanet/us/en/ibmwatson/explorer.html) combines search and content analytics with unique cognitive computing capabilities available through external cloud services such as [Watson Developer Cloud](http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/) to help users find and understand the information they need to work more efficiently and make better, more confident decisions.

The [Watson AlchemyVision](http://www.alchemyapi.com/products/alchemyvision) API employs our deep learning innovations to understand a picture’s content and context. Organizations across a variety of industries — ranging from publishing and advertising to eCommerce and enterprise search — can effectively integrate images as part of big data analytics being used to make critical business decisions.

AlchemyVision sees complex visual scenes in their entirety — without needing any textual clues — leveraging a holistic approach to understanding the multiple objects and surroundings in common smartphone photos and online images.

There are additional cognitive functions available via the AlchemyAPI service in Bluemix that will be covered in other integration examples.  The full AlchemyAPI reference is available on the [AlchemyAPI website](http://www.alchemyapi.com/api).

The goal of this tutorial is to demonstrate how to get started with an integration between Watson Explorer and the Watson AlchemyAPI service available on IBM Watson Developer Cloud. By the end of the tutorial you will have a modified Engine search collection that can send image data to a custom Bluemix Java application which uses AlchemyAPI for image analysis.  The Engine collection will store the AlchemyVision analysis results along with image thumbnails as search results.  Finally, you will modify an Engine display and your AppBuilder application to display the image thumbnail search results.

![Screen shot of an Engine image search result.](images/engine-image-result.png)

## Prerequisites
Please see the [Introduction](https://github.com/Watson-Explorer/wex-wdc-integration-samples) for an overview of the integration architecture, and the tools and libraries that need to be installed to create Java-based applications in Bluemix.

- An [IBM Bluemix](https://ace.ng.bluemix.net/) account
- [Watson Explorer](http://www.ibm.com/smarterplanet/us/en/ibmwatson/explorer.html) - Installed, configured, and running
- Some basic familiarity with Watson Explorer Engine and Watson Explorer Application Builder.  Completion of the Watson Explorer [Engine meta-data tutorial](http://www-01.ibm.com/support/knowledgecenter/SS8NLW_11.0.0/com.ibm.swg.im.infosphere.dataexpl.engine.tut.md.doc/c_vse-metadata-tutorial.html) and the Watson Explorer [AppBuilder tutorial](http://www.ibm.com/support/knowledgecenter/SS8NLW_11.0.0/com.ibm.swg.im.infosphere.dataexpl.appbuilder.doc/c_de-ab-devapp-tutorial.html) should be sufficient, but are not strictly necessary.
- An API key from the [AlchemyAPI website](https://www.alchemyapi.com/api/register.html)


## What's Included in this Tutorial

This tutorial will walk through the creation and deployment of four components.

1. A basic Bluemix application exposing the Watson AlchemyAPI service as a web service.
2. The ImageMagick® package.
3. A Watson Explorer Engine image converter.  This converter uses ImageMagick® to produce a thumbnail, and then converts the thumbnail to VXML.
4. A Watson Explorer Engine AlchemyVision converter.  This converter sends an image to the Bluemix application, which in turn sends the image to the AlchemyVision service for analysis.  The converter takes the analysis response and converts it to VXML.

Simple modifications to the Engine and AppBuilder result display are also made to properly render image thumbnails as search results.


## Step-by-Step Tutorial

This section provides details on the steps required to create an AlchemyAPI service in Bluemix, deploy a basic Watson AlchemyVision application in Bluemix, install ImageMagick®, install the new image and AlchemyVision converters, and make changes to Engine and AppBuilder result displays.

### Creating the AlchemyAPI service and application in Bluemix

The Bluemix documentation can be found [here](https://www.ng.bluemix.net/docs/).

Navigate to the Bluemix dashboard and create a new application with Liberty for Java.

A new AlchemyAPI service must be created via the ACE Bluemix web UI.  The AlchemyAPI service cannot be created via the command line.  Navigate to the Bluemix dashboard and create a new AlchemyAPI service.  Notice that you are required to provide your AlchemyAPI key when the service is created.  Notice also that you must supply the name of the application you just created.  For the sake of the example, we have chosen to name the service `wex-AlchemyAPI`.  Notice that "user-provided" is the only available service plan for AlchemyAPI right now.

   
### Configuring and Deploying the Watson AlchemyAPI AlchemyVision Image Tagging application in Bluemix

Clone this Git repository, or download the zip, extract, and navigate to the repository directory on the commandline.

The example Bluemix application uses a `manifest.yml` file to specify the application name, services bindings, and basic application settings.  Using a manifest simplifies distribution and deployment of CloudFoundry applications.

* Modify the manifest.yml file to agree with the service name, application name, and host name of the service and application you created in the previous step.

If you have not done so already, sign in to Bluemix.

```
$> cf api api.ng.bluemix.net
...
$> cf login
```

Build the application web service using [Apache Maven](http://maven.apache.org/). Before performing this step, verify that you are in the `/bluemix` directory of this repository. This will generate a Java WAR called `wex-wdc-AlchemyVision-sample.war`.

```
$> mvn install
```


Finally, deploy the application to your space in the Bluemix cloud.  Subsequent pushes to Bluemix will overwrite the previous instances you have deployed.

```
$> cf push
```


Once the application has finished restarting, you can now view the route that was created for your application with `cf routes`.  The running application URL can be determined by combining the host and domain from the routes listing.  You can also find this information in the `manifest.yml` file.

### Installing ImageMagick®

[ImageMagick®](http://www.imagemagick.org/) is a software suite used to create, edit, compose, or convert images.  ImageMagick® is free software delivered as a ready-to-run binary distribution or as source code that you may use, copy, modify, and distribute in both open and proprietary applications.  It is distributed under the [Apache 2.0 license](http://www.imagemagick.org/script/license.php).

Navigate to the [ImageMagick® download page](http://www.imagemagick.org/script/binary-releases.php) and follow the instructions for your operating system to download and install ImageMagick®.  Linux users may find that an ImageMagick® package is already installed, or available from a package repository.

Once installation is complete, make a note of the location of the `convert` binary that is part of the ImageMagick® suite.  **Ensure that the path to ImageMagick® binaries is part of the path environment variable for your web server user**.  You will need this path information when you configure the converters in the next steps.

### Installing and Configuring the Engine Image Converter

With the default Engine configuration, only text is indexed, not images.  Images are either discarded during a crawl, or, at best, image metadata (like EXIF data) is extracted from the image file and indexed.

In fact, the default collection configuration contains a crawl filter and a converter filter that eliminates most image filetypes.  The first step to using the image converter is to allow image filetypes.

1. Create a new collection and navigate to the crawling configuration tab.  Click the **edit** button across from the "**Binary file extensions (filter)**" crawl condition.  Add the following in the **Extensions to keep** setting:
   ```
   *.jpg
   *.JPG
   *.jpeg
   *.JPEG
   *.png
   *.PNG
   *.tif
   *.TIF
   *.tiff
   *.TIFF
   *.gif
   *.GIF
   ```
   ![Screen shot of extensions to keep.](images/extensions-to-keep.png) 
   Note that ImageMagick® can handle many additional image types.  You may add wildcards to this list for any image type that ImageMagick® handles.
2. Now add a new crawl condition to properly identify these image types.  Click the **Add a new condition** button and select **Custom conditional settings**.  Add the same wildcard list above to the new crawl condition to apply the condition to all incoming image URLs.  Then open the **Retrieval and encodings** section and specify `image` as the **Default content type**.
   ![Screen shot of the new crawl condition.](images/new-crawl-condition.png)
3. The default collection configuration includes a list of **Text cache content types**.  If URL data, during conversion, ever becomes any of the listed content types, the data will be saved in a database.  This "cached" version of the data is made available at query time via the "cache" link in search results.  However, this cache feature does not make sense for image results.  Clear the list of **Text cache content types** in the **Converting** section of the **Crawling** tab.
4. The default collection configuration includes a binary extensions filter converter as well.  This is designed to eliminate indexing of images extracted from successfully crawled data.  For example, a zip file containing images will not be filtered by the crawl condition.  Let's allow these images by navigating to the converting tab and clicking **edit** across from the **Binary file extensions (filter)** converter.  Once again, paste the wildcard list from step 1 into the **Extensions to keep** setting and click **OK**.

The image converter in this repository leverages ImageMagick® to produce a thumbnail, which is then [base64](https://en.wikipedia.org/wiki/Base64) encoded and indexed.  Proper indexing attributes are used to ensure that the base64 data cannot match queries or go through clustering.  Continue with these steps to add the converter to Engine.

5. In Engine, create a new XML Element by ensuring you are on the **Configuration** tab of the admin tool and then clicking the "+" across from "XML" in the left menu.  The element and name can have any value.
6. Copy the entire contents of [function.vse-converter-image-to-vxml.xml](/engine/function.vse-converter-image-to-vxml.xml).
7. Paste the copied XML into the Engine XML text box, replacing all text that was previously there.
8. Save the converter configuration by clicking **OK**
<commit_msg>minor formatting changes<commit_after># Integrating the Watson Developer Cloud AlchemyAPI AlchemyVision Image Tagging Service with Watson Explorer

[IBM Watson Explorer](http://www.ibm.com/smarterplanet/us/en/ibmwatson/explorer.html) combines search and content analytics with unique cognitive computing capabilities available through external cloud services such as [Watson Developer Cloud](http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/) to help users find and understand the information they need to work more efficiently and make better, more confident decisions.

The [Watson AlchemyVision](http://www.alchemyapi.com/products/alchemyvision) API employs our deep learning innovations to understand a picture’s content and context. Organizations across a variety of industries — ranging from publishing and advertising to eCommerce and enterprise search — can effectively integrate images as part of big data analytics being used to make critical business decisions.

AlchemyVision sees complex visual scenes in their entirety — without needing any textual clues — leveraging a holistic approach to understanding the multiple objects and surroundings in common smartphone photos and online images.

There are additional cognitive functions available via the AlchemyAPI service in Bluemix that will be covered in other integration examples.  The full AlchemyAPI reference is available on the [AlchemyAPI website](http://www.alchemyapi.com/api).

The goal of this tutorial is to demonstrate how to get started with an integration between Watson Explorer and the Watson AlchemyAPI service available on IBM Watson Developer Cloud. By the end of the tutorial you will have a modified Engine search collection that can send image data to a custom Bluemix Java application which uses AlchemyAPI for image analysis.  The Engine collection will store the AlchemyVision analysis results along with image thumbnails as search results.  Finally, you will modify an Engine display and your AppBuilder application to display the image thumbnail search results.

![Screen shot of an Engine image search result.](images/engine-image-result.png)

## Prerequisites
Please see the [Introduction](https://github.com/Watson-Explorer/wex-wdc-integration-samples) for an overview of the integration architecture, and the tools and libraries that need to be installed to create Java-based applications in Bluemix.

- An [IBM Bluemix](https://ace.ng.bluemix.net/) account
- [Watson Explorer](http://www.ibm.com/smarterplanet/us/en/ibmwatson/explorer.html) - Installed, configured, and running
- Some basic familiarity with Watson Explorer Engine and Watson Explorer Application Builder.  Completion of the Watson Explorer [Engine meta-data tutorial](http://www-01.ibm.com/support/knowledgecenter/SS8NLW_11.0.0/com.ibm.swg.im.infosphere.dataexpl.engine.tut.md.doc/c_vse-metadata-tutorial.html) and the Watson Explorer [AppBuilder tutorial](http://www.ibm.com/support/knowledgecenter/SS8NLW_11.0.0/com.ibm.swg.im.infosphere.dataexpl.appbuilder.doc/c_de-ab-devapp-tutorial.html) should be sufficient, but are not strictly necessary.
- An API key from the [AlchemyAPI website](https://www.alchemyapi.com/api/register.html)


## What's Included in this Tutorial

This tutorial will walk through the creation and deployment of four components.

1. A basic Bluemix application exposing the Watson AlchemyAPI service as a web service.
2. The ImageMagick® package.
3. A Watson Explorer Engine image converter.  This converter uses ImageMagick® to produce a thumbnail, and then converts the thumbnail to VXML.
4. A Watson Explorer Engine AlchemyVision converter.  This converter sends an image to the Bluemix application, which in turn sends the image to the AlchemyVision service for analysis.  The converter takes the analysis response and converts it to VXML.

Simple modifications to the Engine and AppBuilder result display are also made to properly render image thumbnails as search results.


## Step-by-Step Tutorial

This section provides details on the steps required to create an AlchemyAPI service in Bluemix, deploy a basic Watson AlchemyVision application in Bluemix, install ImageMagick®, install the new image and AlchemyVision converters, and make changes to Engine and AppBuilder result displays.

### Creating the AlchemyAPI service and application in Bluemix

The Bluemix documentation can be found [here](https://www.ng.bluemix.net/docs/).

Navigate to the Bluemix dashboard and create a new application with Liberty for Java.

A new AlchemyAPI service must be created via the ACE Bluemix web UI.  The AlchemyAPI service cannot be created via the command line.  Navigate to the Bluemix dashboard and create a new AlchemyAPI service.  Notice that you are required to provide your AlchemyAPI key when the service is created.  Notice also that you must supply the name of the application you just created.  For the sake of the example, we have chosen to name the service `wex-AlchemyAPI`.  Notice that "user-provided" is the only available service plan for AlchemyAPI right now.

   
### Configuring and Deploying the Watson AlchemyAPI AlchemyVision Image Tagging application in Bluemix

Clone this Git repository, or download the zip, extract, and navigate to the repository directory on the commandline.

The example Bluemix application uses a `manifest.yml` file to specify the application name, services bindings, and basic application settings.  Using a manifest simplifies distribution and deployment of CloudFoundry applications.

* Modify the manifest.yml file to agree with the service name, application name, and host name of the service and application you created in the previous step.

If you have not done so already, sign in to Bluemix.

```
$> cf api api.ng.bluemix.net
...
$> cf login
```

Build the application web service using [Apache Maven](http://maven.apache.org/). Before performing this step, verify that you are in the `/bluemix` directory of this repository. This will generate a Java WAR called `wex-wdc-AlchemyVision-sample.war`.

```
$> mvn install
```


Finally, deploy the application to your space in the Bluemix cloud.  Subsequent pushes to Bluemix will overwrite the previous instances you have deployed.

```
$> cf push
```


Once the application has finished restarting, you can now view the route that was created for your application with `cf routes`.  The running application URL can be determined by combining the host and domain from the routes listing.  You can also find this information in the `manifest.yml` file.

### Installing ImageMagick®

[ImageMagick®](http://www.imagemagick.org/) is a software suite used to create, edit, compose, or convert images.  ImageMagick® is free software delivered as a ready-to-run binary distribution or as source code that you may use, copy, modify, and distribute in both open and proprietary applications.  It is distributed under the [Apache 2.0 license](http://www.imagemagick.org/script/license.php).

Navigate to the [ImageMagick® download page](http://www.imagemagick.org/script/binary-releases.php) and follow the instructions for your operating system to download and install ImageMagick®.  Linux users may find that an ImageMagick® package is already installed, or available from a package repository.

Once installation is complete, make a note of the location of the `convert` binary that is part of the ImageMagick® suite.  **Ensure that the path to ImageMagick® binaries is part of the path environment variable for your web server user**.  You will need this path information when you configure the converters in the next steps.

### Installing and Configuring the Engine Image Converter

With the default Engine configuration, only text is indexed, not images.  Images are either discarded during a crawl, or, at best, image metadata (like EXIF data) is extracted from the image file and indexed.

In fact, the default collection configuration contains a crawl filter and a converter filter that eliminates most image filetypes.  The first step to using the image converter is to allow image filetypes.

1. Create a new collection and navigate to the crawling configuration tab.  Click the **edit** button across from the "**Binary file extensions (filter)**" crawl condition.  Add the following in the **Extensions to keep** setting:

   ```
   *.jpg
   *.JPG
   *.jpeg
   *.JPEG
   *.png
   *.PNG
   *.tif
   *.TIF
   *.tiff
   *.TIFF
   *.gif
   *.GIF
   ```

   ![Screen shot of extensions to keep.](images/extensions-to-keep.png) 
   Note that ImageMagick® can handle many additional image types.  You may add wildcards to this list for any image type that ImageMagick® handles.
2. Now add a new crawl condition to properly identify these image types.  Click the **Add a new condition** button and select **Custom conditional settings**.  Add the same wildcard list above to the new crawl condition to apply the condition to all incoming image URLs.  Then open the **Retrieval and encodings** section and specify `image` as the **Default content type**.
   ![Screen shot of the new crawl condition.](images/new-crawl-condition.png)
3. The default collection configuration includes a list of **Text cache content types**.  If URL data, during conversion, ever becomes any of the listed content types, the data will be saved in a database.  This "cached" version of the data is made available at query time via the "cache" link in search results.  However, this cache feature does not make sense for image results.  Clear the list of **Text cache content types** in the **Converting** section of the **Crawling** tab.
4. The default collection configuration includes a binary extensions filter converter as well.  This is designed to eliminate indexing of images extracted from successfully crawled data.  For example, a zip file containing images will not be filtered by the crawl condition.  Let's allow these images by navigating to the converting tab and clicking **edit** across from the **Binary file extensions (filter)** converter.  Once again, paste the wildcard list from step 1 into the **Extensions to keep** setting and click **OK**.

The image converter in this repository leverages ImageMagick® to produce a thumbnail, which is then [base64](https://en.wikipedia.org/wiki/Base64) encoded and indexed.  Proper indexing attributes are used to ensure that the base64 data cannot match queries or go through clustering.  Continue with these steps to add the converter to Engine.

5. In Engine, create a new XML Element by ensuring you are on the **Configuration** tab of the admin tool and then clicking the "+" across from "XML" in the left menu.  The element and name can have any value.
6. Copy the entire contents of [function.vse-converter-image-to-vxml.xml](/engine/function.vse-converter-image-to-vxml.xml).
7. Paste the copied XML into the Engine XML text box, replacing all text that was previously there.
8. Save the converter configuration by clicking **OK**

{'fraction_non_alphanumeric': 0.0593779882519011, 'fraction_numerical': 0.003005327626246528, 'mean_word_length': 4.624071702944942, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 11, 'https://': 10, 'lorem ipsum': 0, 'www.': 24, 'xml': 8}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 12, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '392458', 'n_tokens_mistral': 5687, 'n_tokens_neox': 5290, 'n_words': 2952}