Merge pull request #56 from watson-developer-cloud/dev

Added support for Visual Insights

Author: germanattanasio

README.md

@@ -34,8 +34,8 @@ Java code wrappers to quickly get started with the various [Watson Developer Clo
       * [Text to Speech](#text-to-speech)
       * [Tone Analyzer](#tone-analyzer)
       * [Tradeoff Analytics](#tradeoff-analytics)
+      * [Visual Insights](#visual-insights)
       * [Visual Recognition](#visual-recognition)
-      * [Concept Insights](#concept-insights)
     * [Android](#android)
     * [Build + Test](#build--test)
     * [Eclipse and Intellij](#working-with-eclipse-and-intellij-idea)
@@ -105,7 +105,7 @@ System.out.println(sentiment);
 ```
 
 ### Alchemy Vision
-[Alchemy Vision][alchemy_vision] uses deep learning innovations to understand a picture's content and context. It sees complex visual scenes in their entirety —without needing any textual clues— leveraging a holistic approach to understanding the multiple objects and surroundings.
+[Alchemy Vision][alchemy_vision] uses deep learning innovations to understand a picture's content and context. It sees complex visual scenes in their entirety —without needing any textual clues— leveraging a holistic approach to understand the objects, faces, and words in an image.
 
 Example: Extract keywords from an image.
 
@@ -489,6 +489,24 @@ Dilemma dilemma = service.dilemmas(problem);
 System.out.println(dilemma);
 ```
 
+### Visual Insights
+Use the [Visual Insights][visual_insights] to get insight into the themes present in a collection of images based on their visual appearance/content.
+
+
+```java
+import com.ibm.watson.developer_cloud.visual_insights.v1.VisualInsights;
+import com.ibm.watson.developer_cloud.visual_insights.v1.model.Classifiers;
+import java.io.File;
+
+VisualInsights service = new VisualInsights();
+service.setUsernameAndPassword("<username>", "<password>");
+
+File images = new File("src/test/resources/images.zip");
+Summary summary = service.getSummary(images);
+
+System.out.println(summary);
+```
+
 ### Visual Recognition
 Use the [Visual Recognition][visual_recognition] service to recognize the
 following picture.
@@ -586,6 +604,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 [tone-analyzer]: http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/tone-analyzer/
 [dialog]: http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/dialog/
 [concept-insights]: https://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/concept-insights/
+[visual_insights]: http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/visual-insights/
 
 [alchemy_language]: http://www.alchemyapi.com/products/alchemylanguage
 [sentiment_analysis]: http://www.alchemyapi.com/products/alchemylanguage/sentiment-analysis

examples/java/com/ibm/watson/developer_cloud/visual_insights/v1/VisualInsightsExample.java

@@ -0,0 +1,21 @@
+package com.ibm.watson.developer_cloud.visual_insights.v1;
+
+
+import java.io.FileNotFoundException;
+import java.net.URISyntaxException;
+
+import com.ibm.watson.developer_cloud.visual_insights.v1.model.Classifiers;
+
+
+public class VisualInsightsExample {
+
+	public static void main(String[] args) throws URISyntaxException, FileNotFoundException {
+		VisualInsights service = new VisualInsights();
+		service.setUsernameAndPassword("<username>", "<password>");
+
+		Classifiers classifiers = service.getClassifiers();
+
+		System.out.println(classifiers);
+	}
+
+}

src/main/java/com/ibm/watson/developer_cloud/service/Request.java

@@ -21,6 +21,7 @@
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Locale;
+import java.util.Map;
 
 import org.apache.http.HttpEntity;
 import org.apache.http.NameValuePair;
@@ -425,4 +426,35 @@ public Request withHeader(Object... args) {
 	public Request withQuery(Object... args) {
 		return with(queryParams, args);
 	}
+
+	/**
+	 * Adds query parameters.
+	 *
+	 * @param parameters
+	 *            a list of name-value query parameters
+	 *
+	 * @return this
+	 */
+	public Request withQuery(Map<String,Object> parameters) {
+		for (Map.Entry<String, Object> entry : parameters.entrySet()) {
+			withQuery(entry.getKey(),entry.getValue());
+		}
+		return this;
+	}
+
+	/**
+	 * Adds form parameters.
+	 *
+	 * @param parameters
+	 *            a list of name-value form parameters
+	 *
+	 * @return this
+	 */
+	public Request withForm(Map<String,Object> parameters) {
+		for (Map.Entry<String, Object> entry : parameters.entrySet()) {
+			withForm(entry.getKey(),entry.getValue());
+		}
+		return this;
+	}
+
 }

src/main/java/com/ibm/watson/developer_cloud/service/WatsonService.java

@@ -122,8 +122,7 @@ private URI buildRequestURI(HttpRequestBase request) {
 			requestURL = getEndPoint() + request.getURI();
 			return new URI(requestURL);
 		} catch (URISyntaxException e) {
-			log.log(Level.SEVERE, requestURL
-					+ " could not be parsed as a URI reference");
+			log.log(Level.SEVERE, requestURL + " could not be parsed as a URI reference");
 			throw new RuntimeException(e);
 		}
 	}
@@ -396,6 +395,23 @@ protected void setAuthentication(HttpRequestBase request){
 
 	}
 
+	/**
+	 * Execute the request and return the POJO that represent the response.
+	 *
+	 * @param <T>             The POJO that represents the response object
+	 * @param request         the request
+	 * @param returnType      the POJO class to be parsed from the response
+	 * @return the POJO object that represent the response
+	 */
+	protected  <T> T executeRequest(Request request,  Class<T> returnType) {
+		HttpRequestBase requestBase = request.build();
+		try {
+			HttpResponse response = execute(requestBase);
+			return ResponseUtil.getObject(response, returnType);
+		} catch (IOException e) {
+			throw new RuntimeException(e);
+		}
+	}
 	/*
 	 * (non-Javadoc)
 	 *

src/main/java/com/ibm/watson/developer_cloud/visual_Insights/v1/VisualInsights.java

@@ -0,0 +1,122 @@
+/**
+ * Copyright 2015 IBM Corp. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.ibm.watson.developer_cloud.visual_insights.v1;
+
+import java.io.File;
+import java.util.HashMap;
+import java.util.Map;
+
+import org.apache.http.entity.mime.MultipartEntity;
+import org.apache.http.entity.mime.content.FileBody;
+
+import com.ibm.watson.developer_cloud.service.Request;
+import com.ibm.watson.developer_cloud.service.WatsonService;
+import com.ibm.watson.developer_cloud.visual_insights.v1.model.Classifiers;
+import com.ibm.watson.developer_cloud.visual_insights.v1.model.Summary;
+
+
+/**
+ * The IBM Watson Visual Insights gives insight into the themes present in a collection of images based on their visual appearance / content.
+ *
+ * @author Nizar Alseddeg (nmalsedd@us.ibm.com)
+ * @version v1
+ * @see <a
+ * href="http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/visual-insights.html">
+ * Visual Insights</a>
+ */
+public class VisualInsights extends WatsonService {
+
+    private static final String FILE = "file";
+
+	/**
+     * The CLASSIFIERS_PATH. (value is "/classifiers")
+     */
+    private static final String CLASSIFIERS_PATH = "/v1/classifiers";
+
+    /**
+     * The SUMMARY_PATH. (value is "/summary")
+     */
+    private static final String SUMMARY_PATH = "/v1/summary";
+
+
+    /**
+     * The Constant FILTER_NAME. (value is "filter_name")
+     */
+    public static final String FILTER_NAME = "filter_name";
+
+    /**
+     * The service url.
+     * (value is "https://gateway.watsonplatform.net/visual-insights/api")
+     */
+    private static final String URL = "https://gateway.watsonplatform.net/visual-insights-experimental/api";
+
+    /**
+     * Instantiates a new visual insights service.
+     */
+    public VisualInsights() {
+		setEndPoint(URL);
+	}
+    
+    /**
+     * Returns a summary of the collection's visual classifiers
+     *
+     * @return the Summary
+     */
+    public Classifiers getClassifiers() {
+        Request request = Request.Get(CLASSIFIERS_PATH);
+        return executeRequest(request, Classifiers.class);
+    }
+
+    /**
+     * Returns a summary of the collection's visual classifiers, filtered by name
+     *
+     * @param filterName the images File
+     * @return the Summary
+     */
+    public Classifiers getClassifiers(final String filterName) {
+
+        Request request = Request.Get(CLASSIFIERS_PATH);
+
+        if(filterName!=null && !filterName.isEmpty()) {
+            Map<String, Object> queryParameters = new HashMap<String, Object>();
+            queryParameters.put(FILTER_NAME,filterName);
+            request.withQuery(queryParameters);
+        }
+
+        return executeRequest(request, Classifiers.class);
+    }
+
+    /**
+     * Upload a set of images as a zip file for visual insight extraction.
+     *
+     * @param imagesFile the images File
+     * @return the Summary of the collection's visual attributes
+     */
+    public Summary getSummary(final File imagesFile) {
+        if (imagesFile == null || !imagesFile.exists())
+            throw new IllegalArgumentException(
+                    "imagesFile can not be null or empty");
+
+        MultipartEntity reqEntity = new MultipartEntity();
+        reqEntity.addPart(FILE, new FileBody(imagesFile));
+        Request request = Request.Post(SUMMARY_PATH)
+                .withEntity(reqEntity);
+
+        return executeRequest(request, Summary.class);
+
+    }
+
+}

src/main/java/com/ibm/watson/developer_cloud/visual_Insights/v1/model/Classifiers.java

@@ -0,0 +1,74 @@
+/**
+ * Copyright 2015 IBM Corp. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.ibm.watson.developer_cloud.visual_insights.v1.model;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import com.ibm.watson.developer_cloud.service.model.GenericModel;
+
+/**
+ * The Class Classifiers.
+ */
+public class Classifiers extends GenericModel {
+
+    /** The classifiers. */
+    private List<Classifier> classifiers = new ArrayList<Classifier>();
+
+    /**
+     * Gets the classifiers.
+     *
+     * @return the classifiers
+     */
+    public List<Classifier> getClassifiers() {
+        return classifiers;
+    }
+
+    /**
+     * Sets the classifiers.
+     *
+     * @param classifiers
+     *            the new classifiers
+     */
+    public void setClassifiers(List<Classifier> classifiers) {
+        this.classifiers = classifiers;
+    }
+
+    public static class Classifier extends GenericModel {
+
+        private String name;
+
+        /**
+         * Gets the name.
+         *
+         * @return the name
+         */
+        public String getName() {
+            return name;
+        }
+
+        /**
+         * Sets the name.
+         *
+         * @param name
+         *            the new name
+         */
+        public void setName(String name) {
+            this.name = name;
+        }
+    }
+
+}