[MXNET-53]Image classifier for scala-infer package (apache#10054)

* Image classifier for infer package

scala-package/examples/pom.xml

@@ -14,6 +14,24 @@
   <name>MXNet Scala Package - Examples</name>
 
   <profiles>
+    <profile>
+      <id>osx-x86_64-cpu</id>
+      <properties>
+        <platform>osx-x86_64-cpu</platform>
+      </properties>
+    </profile>
+    <profile>
+      <id>linux-x86_64-cpu</id>
+      <properties>
+        <platform>linux-x86_64-cpu</platform>
+      </properties>
+    </profile>
+    <profile>
+      <id>linux-x86_64-gpu</id>
+      <properties>
+        <platform>linux-x86_64-gpu</platform>
+      </properties>
+    </profile>
     <profile>
       <id>release</id>
       <build>
@@ -107,13 +125,22 @@
         <groupId>net.alchim31.maven</groupId>
         <artifactId>scala-maven-plugin</artifactId>
       </plugin>
+      <plugin>
+        <groupId>org.scalatest</groupId>
+        <artifactId>scalatest-maven-plugin</artifactId>
+        <configuration>
+          <argLine>
+            -Djava.library.path=${project.parent.basedir}/native/${platform}/target \
+            -Dlog4j.configuration=file://${project.basedir}/src/test/resources/log4j.properties
+          </argLine>
+        </configuration>
+      </plugin>
       <plugin>
         <groupId>org.scalastyle</groupId>
         <artifactId>scalastyle-maven-plugin</artifactId>
       </plugin>
     </plugins>
   </build>
-
   <dependencies>
     <dependency>
       <groupId>ml.dmlc.mxnet</groupId>
@@ -123,7 +150,7 @@
     </dependency>
     <dependency>
       <groupId>ml.dmlc.mxnet</groupId>
-      <artifactId>mxnet-infer</artifactId>
+      <artifactId>mxnet-infer_${scala.binary.version}</artifactId>
       <version>1.2.0-SNAPSHOT</version>
       <scope>provided</scope>
     </dependency>
@@ -147,5 +174,10 @@
       <artifactId>opencv</artifactId>
       <version>2.4.9-7</version>
     </dependency>
+    <dependency>
+      <groupId>org.slf4j</groupId>
+      <artifactId>slf4j-simple</artifactId>
+      <version>1.7.5</version>
+    </dependency>
   </dependencies>
 </project>

scala-package/examples/scripts/inferexample/imageclassifier/get_resnet_data.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you 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.
+
+set -e
+
+MXNET_ROOT=$(cd "$(dirname $0)/../../.."; pwd)
+
+data_path=$MXNET_ROOT/scripts/inferexample/models/resnet-152/
+
+image_path=$MXNET_ROOT/scripts/inferexample/images/
+
+if [ ! -d "$data_path" ]; then
+  mkdir -p "$data_path"
+fi
+
+if [ ! -d "$image_path" ]; then
+  mkdir -p "$image_path"
+fi
+
+if [ ! -f "$data_path" ]; then
+  wget http://data.mxnet.io/models/imagenet-11k/resnet-152/resnet-152-0000.params -P $data_path
+  wget http://data.mxnet.io/models/imagenet-11k/resnet-152/resnet-152-symbol.json -P $data_path
+  wget http://data.mxnet.io/models/imagenet-11k/synset.txt -P $data_path
+  wget https://s3.amazonaws.com/model-server/inputs/kitten.jpg -P $image_path
+fi

scala-package/examples/scripts/inferexample/imageclassifier/run_classifier_example.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you 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.
+
+set -e
+
+MXNET_ROOT=$(cd "$(dirname $0)/../../../../.."; pwd)
+CLASS_PATH=$MXNET_ROOT/scala-package/assembly/osx-x86_64-cpu/target/*:$MXNET_ROOT/scala-package/examples/target/*:$MXNET_ROOT/scala-package/examples/target/classes/lib/*:$MXNET_ROOT/scala-package/infer/target/*
+
+# model dir
+MODEL_PATH_PREFIX=$1
+# input image
+INPUT_IMG=$2
+# which input image dir
+INPUT_DIR=$3
+
+java -Xmx8G -Dmxnet.traceLeakedObjects=true -cp $CLASS_PATH \
+	ml.dmlc.mxnetexamples.inferexample.imageclassifier.ImageClassifierExample \
+	--model-path-prefix $MODEL_PATH_PREFIX \
+	--input-image $INPUT_IMG \
+	--input-dir $INPUT_DIR

scala-package/examples/src/main/scala/ml/dmlc/mxnetexamples/inferexample/imageclassifier/ImageClassifierExample.scala

@@ -0,0 +1,126 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 ml.dmlc.mxnetexamples.inferexample.imageclassifier
+
+import ml.dmlc.mxnet.Shape
+import org.kohsuke.args4j.{CmdLineParser, Option}
+import org.slf4j.LoggerFactory
+
+import ml.dmlc.mxnet.{DType, DataDesc}
+import ml.dmlc.mxnet.infer.ImageClassifier
+
+import scala.collection.JavaConverters._
+import java.io.File
+
+/**
+  * Example showing usage of Infer package to do inference on resnet-152 model
+  * Follow instructions in README.md to run this example.
+  */
+object ImageClassifierExample {
+  private val logger = LoggerFactory.getLogger(classOf[ImageClassifierExample])
+
+  def runInferenceOnSingleImage(modelPathPrefix: String, inputImagePath: String):
+  IndexedSeq[IndexedSeq[(String, Float)]] = {
+    val dType = DType.Float32
+    val inputShape = Shape(1, 3, 224, 224)
+
+    val inputDescriptor = IndexedSeq(DataDesc("data", inputShape, dType, "NCHW"))
+
+    // Create object of ImageClassifier class
+    val imgClassifier: ImageClassifier = new
+        ImageClassifier(modelPathPrefix, inputDescriptor)
+
+    // Loading single image from file and getting BufferedImage
+    val img = ImageClassifier.loadImageFromFile(inputImagePath)
+
+    // Running inference on single image
+    val output = imgClassifier.classifyImage(img, Some(5))
+
+    output
+  }
+
+  def runInferenceOnBatchOfImage(modelPathPrefix: String, inputImageDir: String):
+  IndexedSeq[IndexedSeq[(String, Float)]] = {
+    val dType = DType.Float32
+    val inputShape = Shape(1, 3, 224, 224)
+
+    val inputDescriptor = IndexedSeq(DataDesc("data", inputShape, dType, "NCHW"))
+
+    // Create object of ImageClassifier class
+    val imgClassifier: ImageClassifier = new
+        ImageClassifier(modelPathPrefix, inputDescriptor)
+
+    // Loading batch of images from the directory path
+    val imgList = ImageClassifier.loadInputBatch(inputImageDir)
+
+    // Running inference on batch of images loaded in previous step
+    val outputList = imgClassifier.classifyImageBatch(imgList, Some(5))
+
+    outputList
+  }
+
+  def main(args: Array[String]): Unit = {
+    val inst = new ImageClassifierExample
+    val parser: CmdLineParser = new CmdLineParser(inst)
+    try {
+      parser.parseArgument(args.toList.asJava)
+
+      val modelPathPrefix = if (inst.modelPathPrefix == null) System.getenv("MXNET_DATA_DIR")
+      else inst.modelPathPrefix
+
+      val inputImagePath = if (inst.inputImagePath == null) System.getenv("MXNET_DATA_DIR")
+      else inst.inputImagePath
+
+      val inputImageDir = if (inst.inputImageDir == null) System.getenv("MXNET_DATA_DIR")
+      else inst.inputImageDir
+
+      val singleOutput = runInferenceOnSingleImage(modelPathPrefix, inputImagePath)
+
+      // Printing top 5 class probabilities
+      for (i <- singleOutput) {
+        printf("Classes with top 5 probability = %s \n", i)
+      }
+
+      val batchOutput = runInferenceOnBatchOfImage(modelPathPrefix, inputImageDir)
+
+      val d = new File(inputImageDir)
+      val filenames = d.listFiles.filter(_.isFile).toList
+
+      // Printing filename and inference class with top 5 probabilities
+      for ((f, inferOp) <- (filenames zip batchOutput)) {
+        printf("Input image %s ", f)
+        printf("Class with probability =%s \n", inferOp)
+      }
+    } catch {
+      case ex: Exception => {
+        logger.error(ex.getMessage, ex)
+        parser.printUsage(System.err)
+        sys.exit(1)
+      }
+    }
+  }
+}
+
+class ImageClassifierExample {
+  @Option(name = "--model-path-prefix", usage = "the input model directory")
+  private val modelPathPrefix: String = "/resnet-152/resnet-152"
+  @Option(name = "--input-image", usage = "the input image")
+  private val inputImagePath: String = "/images/kitten.jpg"
+  @Option(name = "--input-dir", usage = "the input batch of images directory")
+  private val inputImageDir: String = "/images/"
+}

scala-package/examples/src/main/scala/ml/dmlc/mxnetexamples/inferexample/imageclassifier/README.md

@@ -0,0 +1,88 @@
+# Image Classification
+
+This folder contains an example for image classification with the [MXNet Scala Infer API](https://github.com/apache/incubator-mxnet/tree/master/scala-package/infer).
+The goal of image classification is to identify the objects contained in images.
+The following example shows recognized object classes with corresponding probabilities using a pre-trained model.
+
+
+## Contents
+
+1. [Prerequisites](#prerequisites)
+2. [Download artifacts](#download-artifacts)
+3. [Run the image inference example](#run-the-image-inference-example)
+4. [Pretrained models](#pretrained-models)
+5. [Infer APIs](#infer-api-details)
+6. [Next steps](#next-steps)
+
+
+## Prerequisites
+
+1. MXNet
+2. MXNet Scala Package
+3. [IntelliJ IDE (or alternative IDE) project setup](http://mxnet.incubator.apache.org/tutorials/scala/mxnet_scala_on_intellij.html) with the MXNet Scala Package
+4. wget
+
+
+## Download Artifacts
+
+For this tutorial, you can get the model and sample input image by running following bash file. This script will use `wget` to download these artifacts from AWS S3.
+
+From the `scala-package/examples/scripts/inferexample/imageclassifier/` folder run:
+
+```bash
+./get_resnet_data.sh
+```
+
+**Note**: You may need to run `chmod +x get_resnet_data.sh` before running this script.
+
+
+## Run the Image Inference Example
+
+Now that you have the model files and the test kitten image, you can run the following script to pass the necessary parameters to the JDK to run this inference example.
+
+```bash
+./run_classifier_example.sh \
+../resnet/resnet-152  ../images/kitten.jpg  ../images/
+```
+
+**Notes**:
+* These are relative paths to this script.
+* You may need to run `chmod +x run_predictor_example.sh` before running this script.
+
+There are few options which you can provide to run the example. Use the `--help` argument to list them.
+
+```bash
+./run_predictor_example.sh --help
+```
+
+The available arguments are as follows:
+
+| Argument                      | Comments                                 |
+| ----------------------------- | ---------------------------------------- |
+| `model-dir`                   | Folder path with prefix to the model (including json, params, and any synset file). |
+| `input-image`                 | The image to run inference on. |
+| `input-dir`                   | The directory of images to run inference on. |
+
+* You must use `model-dir`.
+* You must use `input-image` and `input-dir` as this example shows single image inference as well as batch inference together.
+
+
+## Pretrained Models
+
+The MXNet project repository provides several [pre-trained models on various datasets](https://github.com/apache/incubator-mxnet/tree/master/example/image-classification#pre-trained-models) and examples on how to train them. You may use the [modelzoo.py](https://github.com/apache/incubator-mxnet/blob/master/example/image-classification/common/modelzoo.py) helper script to download these models. Many ImageNet models may be also be downloaded directly from [http://data.mxnet.io/models/imagenet/](http://data.mxnet.io/models/imagenet/).
+
+
+## Infer API Details
+
+This example uses the [ImageClassifier](https://github.com/apache/incubator-mxnet/blob/master/scala-package/infer/src/main/scala/ml/dmlc/mxnet/infer/ImageClassifier.scala)
+class provided by the [MXNet Scala Infer API](https://github.com/apache/incubator-mxnet/tree/master/scala-package/infer).
+It provides methods to load the images, create a NDArray out of a `BufferedImage`, and run prediction using the following Infer APIs:
+* [Classifier](https://github.com/apache/incubator-mxnet/blob/master/scala-package/infer/src/main/scala/ml/dmlc/mxnet/infer/Classifier.scala)
+* [Predictor](https://github.com/apache/incubator-mxnet/blob/master/scala-package/infer/src/main/scala/ml/dmlc/mxnet/infer/Predictor.scala)
+
+
+## Next Steps
+
+Check out the following related tutorials and examples for the Infer API:
+
+* [Single Shot Detector with the MXNet Scala Infer API](../objectdetector/README.md)

scala-package/examples/src/test/resources/log4j.properties

@@ -0,0 +1,24 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you 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.
+
+# for development debugging
+log4j.rootLogger = info, stdout
+
+log4j.appender.stdout = org.apache.log4j.ConsoleAppender
+log4j.appender.stdout.Target = System.out
+log4j.appender.stdout.layout = org.apache.log4j.PatternLayout
+log4j.appender.stdout.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss,SSS} [%t] [%c] [%p] - %m%n