Update README: examples

Change-Id: I0bd9387f333ad6e87c1a153152d5f0e1bfdc2bf5

examples/setup.md → docs/development/setup.md

@@ -1,16 +1,15 @@
-Setup
-=====
+# Setup development environment
 
 ## Install jdk
 
-djl.ai requires JDK 8 (or later). We recommend use JDK8 since there are some known glitches with JDK 11+.
+Our project requires JDK 8 (or later). We recommend use JDK8 since there are some known glitches with JDK 11+.
 
 Verify Java is available in your $PATH environment variable. If you have multiple versions of Java installed,
 you can use $JAVA_HOME environment variable to control which version of Java to use.
 
 For ubuntu:
 ```bash
-sudo apt-get install openjdk-8-jre-headless
+sudo apt-get install openjdk-8-jdk-headless
 ```
 
 For centos
@@ -30,7 +29,14 @@ manually if you have trouble with the previous commands.
 
 ## Install IntelliJ (Optional)
 
-You can use the IDE of your choice. We recommend using IntelliJ since we are using IntelliJ for the examples in our documentation.
+You can use the IDE of your choice. We recommend using IntelliJ.
+
+### Import DJL project into IntelliJ
+
+1. Open IntelliJ and click `Import Project`.
+2. Navigate to the project root folder and click "Open".
+3. Choose `Import project from existing model`, you can select `Gradle`
+4. Use the default configuration and click `OK`.
 
 ## Gradle/Maven (Not required)
 

examples/README.md

@@ -1,53 +1,61 @@
-djl.ai - examples
-=================
-
-## Overview
-
-The djl.ai API is designed to be an extremely easy to use deep learning framework for Java
-developers. djl.ai does not require you to be a Machine Learning/Deep Learning expert to get
-started. You can use your existing Java expertise as an on-ramp to learn and use ML/DL. You can
-use your favorite IDE to build/train/deploy your models and integrate these models with your
-Java applications.
-
-djl.ai API is deep learning framework agnostic, so you don't have to make a choice
-between frameworks when starting your project. You can switch to a different framework at any
-time you want. djl.ai also provides automatic CPU/GPU choice based on the hardware configuration
-to ensure the best performance.
-
-djl.ai API provides native Java development experience. It functions similarly to any other Java library.
-djl.ai's ergonomic API interface is designed to guide you with best practices to accomplish your
-deep learning task.
-
-The following is an example of how to write inference code:
-
-```java
-    // Assume user uses a pre-trained model from model zoo, they just need to load it
-    Map<String, String> criteria = new HashMap<>();
-    criteria.put("layers", "18");
-    criteria.put("flavor", "v1");
-
-    // Load pre-trained model from model zoo
-    try (Model<BufferedImage, Classifications> model = MxModelZoo.RESNET.loadModel(criteria)) {
-        try (Predictor<BufferedImage, Classifications> predictor = model.newPredictor()) {
-            BufferedImage img = readImage(); // read image
-            Classifications result = predictor.predict(img);
-
-            // get the classification and probability
-            ...
-        }
-    }
+# DeepJavaLibrary - examples
+
+This module contains examples to demonstrate how developers can use the DeepJavaLibrary API.
+
+The following is a list of examples:
+
+- [Image classification example](docs/image_classification.md)
+- [Single-shot Object detection example](docs/object_detection.md)
+- [Bert question and answer example](docs/BERT_question_and_answer.md)
+
+## Prerequisite
+
+* You need to have JDK 8 (or later) installed on your system. Read [here](../docs/development/setup.md) for more detail.
+* You should also be familiar with the API documentation: [Javadoc](https://djl-ai.s3.amazonaws.com/java-api/0.2.0/index.html)
+
+
+# Getting started: 30 seconds to run an example
+
+## Building with command line
+
+This example project supports building with both gradle and maven. To build, use the following:
+
+### gradle
+
+```sh
+cd examples
+./gradlew jar
+```
+
+### maven build
+
+```sh
+cd examples
+mvn package
 ```
 
-## djl.ai API reference
+### Run example code
+With the gradle `application` plugin you can execute example code directly.
+You can find how to run each example in each example's detail document.
+Here is an example that executes object detection example:
+
+```sh
+cd examples
+./gradlew run
+```
 
-You can find more information here: [Javadoc](https://djl-ai.s3.amazonaws.com/java-api/0.1.0/index.html)
+## Engine selection
 
-## Examples project
+djl.ai is engine agnostic, so you can choose different engine providers. We currently
+provide MXNet engine implementation.
 
-Read [Examples project](examples.md) for more detail about how to setup development environment and dependencies.
+With MXNet, you can choose different flavors of the native MXNet library.
+In this example, we use `mxnet-native-mkl` for OSX platform. You might need to 
+change it for your platform in [pom.xml](pom.xml) or [build.gradle](build.gradle).
 
-You can also read individual examples: 
+Available MXNet versions are as follows:
 
-1. [Image classification example](CLASSIFY.md)
-2. [Single-shot Object detection example](SSD.md)
-3. [Bert question and answer example](BERTQA.md)
+| Version              |
+| -------------------- |
+| mxnet-native-mkl     |
+| mxnet-native-cu101mkl|

examples/build.gradle

@@ -16,11 +16,11 @@ dependencies {
     compile "commons-cli:commons-cli:1.4"
     compile "org.apache.logging.log4j:log4j-slf4j-impl:2.12.1"
     compile "com.google.code.gson:gson:2.8.5"
-    compile "ai.djl:api:0.1.0"
-    compile "ai.djl:basicdataset:0.1.0"
-    compile "ai.djl:model-zoo:0.1.0"
-    compile "ai.djl.mxnet:mxnet-model-zoo:0.1.0"
-    runtime "ai.djl.mxnet:mxnet-native-mkl:1.6.0:${classifier}"
+    compile "ai.djl:api:0.2.0-SNAPSHOT"
+    compile "ai.djl:basicdataset:0.2.0-SNAPSHOT"
+    compile "ai.djl:model-zoo:0.2.0-SNAPSHOT"
+    compile "ai.djl.mxnet:mxnet-model-zoo:0.2.0-SNAPSHOT"
+    runtime "ai.djl.mxnet:mxnet-native-mkl:1.6.0-SNAPSHOT:${classifier}"
 
     testImplementation 'org.testng:testng:6.14.3'
 }
@@ -35,7 +35,7 @@ application {
     mainClassName = System.getProperty("main", "ai.djl.examples.inference.ObjectDetection")
 }
 
-run{
+run {
     systemProperties System.getProperties()
 }
 

examples/djl.gradle

@@ -27,7 +27,7 @@ dependencies {
 
     runtime "ai.djl.mxnet:mxnet-native-mkl:1.6.0-SNAPSHOT:${classifier}"
 
-    testCompile ("org.testng:testng:${testng_version}") {
+    testCompile("org.testng:testng:${testng_version}") {
         exclude group: "junit", module: "junit"
     }
 }
@@ -82,7 +82,7 @@ application {
     mainClassName = System.getProperty("main", "ai.djl.examples.inference.ObjectDetection")
 }
 
-run{
+run {
     systemProperties System.getProperties()
     systemProperties.remove("user.dir");
 }

examples/docs/image_classification.md

@@ -0,0 +1,46 @@
+# Image classification example
+
+Image classification refers to the task of extracting information classes from an image.
+
+In this example, we will show you how to implement inference code with DJL API to recognize handwritten digit from an image.
+
+The following is the image classification example source code: [ImageClassification.java](https://github.com/awslabs/djl/blob/master/examples/src/main/java/ai/djl/examples/inference/ImageClassification.java).
+
+You can also find the jupyter notebook tutorial [here](../../jupyter/README.md#run-image-classification-with-your-first-model).
+The jupyter notebook explains the key concepts in detail.
+
+## Setup Guide
+
+Follow [setup](../../docs/development/setup.md) to configure your development environment.
+
+## Run image classification example
+
+### Prepare your model
+The model we are using is generated by the [training example](train_your_first_model.md).
+Run the training example to generate the model before continuing with this example.
+The trained model will be stored as `build/model/mlp-XXXX.params`.
+
+### Input image file
+In the previous training example, we trained the model using the grayscale handwritten digit dataset, MNIST.
+You can find the following image in your project test resource folder: `src/test/resources/0.png`
+
+![0](../src/test/resources/0.png)
+
+### Build the project and run
+
+```
+cd examples
+./gradlew run -Dmain=ai.djl.examples.inference.ImageClassification
+```
+
+```text
+[INFO ] - [
+        class: "0", probability: 0.99996
+        class: "2", probability: 0.00002
+        class: "6", probability: 5.4e-06
+        class: "9", probability: 2.5e-06
+        class: "8", probability: 8.5e-07
+]
+```
+
+The results show that there's a 99.996% probability that the image contains a "0" digit.