Skip to content
This repository has been archived by the owner on Nov 17, 2023. It is now read-only.

[MXNET-248] Scala Infer API docs editorial pass #10307

Merged
merged 6 commits into from
Apr 5, 2018
Merged

[MXNET-248] Scala Infer API docs editorial pass #10307

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b969d4e
scala infer api docs update
aaronmarkham Mar 28, 2018
91ac8a6
removed backslashes
aaronmarkham Mar 28, 2018
43b5e00
minor formatting
aaronmarkham Mar 28, 2018
fb910d9
removed ending p tags
aaronmarkham Mar 28, 2018
9e80262
scalastyle fixes
aaronmarkham Apr 4, 2018
87b6a7a
Merge branch 'master' into scaladocs
aaronmarkham Apr 4, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions ...ain/scala/ml/dmlc/mxnetexamples/inferexample/imageclassifier/ImageClassifierExample.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,11 @@ import java.io.File
import scala.collection.mutable.ListBuffer

/**
* Example showing usage of Infer package to do inference on resnet-152 model
* Follow instructions in README.md to run this example.
* <p>
* Example inference showing usage of the Infer package on a resnet-152 model.
* @see <a href="https://github.com/apache/incubator-mxnet\
* blob/master/scala-package/examples/src/main/scala/ml/dmlc/mxnetexamples/inferexample\
* imageclassifier/" target="_blank">Instructions to run this example</a>
*/
object ImageClassifierExample {

Expand Down
8 changes: 8 additions & 0 deletions ...c/main/scala/ml/dmlc/mxnetexamples/inferexample/objectdetector/SSDClassifierExample.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,14 @@ import java.nio.file.{Files, Paths}

import scala.collection.mutable.ListBuffer

/**
* <p>
* Example single shot detector (SSD) using the Infer package
* on a ssd_resnet50_512 model.
* @see <a href="https://github.com/apache/incubator-mxnet\
* blob/master/scala-package/examples/src/main/scala/ml/dmlc/mxnetexamples/inferexample\
* objectdetector/" target="_blank">Instructions to run this example</a>
*/
class SSDClassifierExample {
@Option(name = "--model-path-prefix", usage = "the input model directory and prefix of the model")
private val modelPathPrefix: String = "/model/ssd_resnet50_512"
Expand Down
59 changes: 30 additions & 29 deletions scala-package/infer/src/main/scala/ml/dmlc/mxnet/infer/Classifier.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,35 +28,36 @@ import scala.collection.mutable.ListBuffer
trait ClassifierBase {

/**
* Takes an Array of Floats and returns corresponding labels, score tuples.
* @param input: IndexedSequence one-dimensional array of Floats.
* @param topK: (Optional) How many top_k(sorting will be based on the last axis)
* elements to return, if not passed returns unsorted output.
* @return IndexedSequence of (Label, Score) tuples.
* Takes an array of floats and returns corresponding (Label, Score) tuples
* @param input Indexed sequence one-dimensional array of floats
* @param topK (Optional) How many result (sorting based on the last axis)
* elements to return. Default returns unsorted output.
* @return Indexed sequence of (Label, Score) tuples
*/
def classify(input: IndexedSeq[Array[Float]],
topK: Option[Int] = None): IndexedSeq[(String, Float)]

/**
* Takes a Sequence of NDArrays and returns Label, Score tuples.
* @param input: Indexed Sequence of NDArrays
* @param topK: (Optional) How many top_k(sorting will be based on the last axis)
* elements to return, if not passed returns unsorted output.
* @return Traversable Sequence of (Label, Score) tuple
* Takes a sequence of NDArrays and returns (Label, Score) tuples
* @param input Indexed sequence of NDArrays
* @param topK (Optional) How many result (sorting based on the last axis)
* elements to return. Default returns unsorted output.
* @return Traversable sequence of (Label, Score) tuple
*/
def classifyWithNDArray(input: IndexedSeq[NDArray],
topK: Option[Int] = None): IndexedSeq[IndexedSeq[(String, Float)]]
topK: Option[Int] = None): IndexedSeq[IndexedSeq[(String, Float)]]
}

/**
* A class for classifier tasks
* @param modelPathPrefix PathPrefix from where to load the symbol, parameters and synset.txt
* Example: file://model-dir/resnet-152(containing resnet-152-symbol.json
* file://model-dir/synset.txt
* @param inputDescriptors Descriptors defining the input node names, shape,
* layout and Type parameters
* @param contexts Device Contexts on which you want to run Inference, defaults to CPU.
* @param epoch Model epoch to load, defaults to 0.
* @param modelPathPrefix Path prefix from where to load the model artifacts
* These include the symbol, parameters, and synset.txt
* Example: file://model-dir/resnet-152 (containing
* resnet-152-symbol.json, resnet-152-0000.params, and synset.txt)
* @param inputDescriptors Descriptors defining the input node names, shape,
* layout and type parameters
* @param contexts Device contexts on which you want to run inference; defaults to CPU
* @param epoch Model epoch to load; defaults to 0
*/
class Classifier(modelPathPrefix: String,
protected val inputDescriptors: IndexedSeq[DataDesc],
Expand All @@ -75,11 +76,11 @@ class Classifier(modelPathPrefix: String,
protected[infer] val handler = MXNetHandler()

/**
* Takes a flat arrays as input and returns a List of (Label, tuple)
* @param input: IndexedSequence one-dimensional array of Floats.
* @param topK: (Optional) How many top_k(sorting will be based on the last axis)
* elements to return, if not passed returns unsorted output.
* @return IndexedSequence of (Label, Score) tuples.
* Takes flat arrays as input and returns (Label, Score) tuples.
* @param input Indexed sequence one-dimensional array of floats
* @param topK (Optional) How many result (sorting based on the last axis)
* elements to return. Default returns unsorted output.
* @return Indexed sequence of (Label, Score) tuples
*/
override def classify(input: IndexedSeq[Array[Float]],
topK: Option[Int] = None): IndexedSeq[(String, Float)] = {
Expand All @@ -98,12 +99,12 @@ class Classifier(modelPathPrefix: String,
}

/**
* Takes input as NDArrays, useful when you want to perform multiple operations on
* the input Array or when you want to pass a batch of input.
* @param input: Indexed Sequence of NDArrays
* @param topK: (Optional) How many top_k(sorting will be based on the last axis)
* elements to return, if not passed returns unsorted output.
* @return Traversable Sequence of (Label, Score) tuple
* Perform multiple classification operations on NDArrays.
* Also works with batched input.
* @param input Indexed sequence of NDArrays
* @param topK (Optional) How many result (sorting based on the last axis)
* elements to return. Default returns unsorted output.
* @return Traversable sequence of (Label, Score) tuples
*/
override def classifyWithNDArray(input: IndexedSeq[NDArray], topK: Option[Int] = None)
: IndexedSeq[IndexedSeq[(String, Float)]] = {
Expand Down
58 changes: 30 additions & 28 deletions scala-package/infer/src/main/scala/ml/dmlc/mxnet/infer/ImageClassifier.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,16 +29,17 @@ import javax.imageio.ImageIO


/**
* A class for Image classification tasks.
* A class for image classification tasks.
* Contains helper methods.
*
* @param modelPathPrefix PathPrefix from where to load the symbol, parameters and synset.txt
* Example: file://model-dir/resnet-152(containing resnet-152-symbol.json
* file://model-dir/synset.txt
* @param inputDescriptors Descriptors defining the input node names, shape,
* layout and Type parameters
* @param contexts Device Contexts on which you want to run Inference, defaults to CPU.
* @param epoch Model epoch to load, defaults to 0.
* @param modelPathPrefix Path prefix from where to load the model artifacts.
* These include the symbol, parameters, and synset.txt.
* Example: file://model-dir/resnet-152 (containing
* resnet-152-symbol.json, resnet-152-0000.params, and synset.txt).
* @param inputDescriptors Descriptors defining the input node names, shape,
* layout and type parameters
* @param contexts Device contexts on which you want to run inference; defaults to CPU
* @param epoch Model epoch to load; defaults to 0
*/
class ImageClassifier(modelPathPrefix: String,
inputDescriptors: IndexedSeq[DataDesc],
Expand Down Expand Up @@ -66,9 +67,9 @@ class ImageClassifier(modelPathPrefix: String,
/**
* To classify the image according to the provided model
*
* @param inputImage PathPrefix of the input image
* @param topK Get top k elements with maximum probability
* @return List of list of tuples of (class, probability)
* @param inputImage Path prefix of the input image
* @param topK Number of result elements to return, sorted by probability
* @return List of list of tuples of (Label, Probability)
*/
def classifyImage(inputImage: BufferedImage,
topK: Option[Int] = None): IndexedSeq[IndexedSeq[(String, Float)]] = {
Expand All @@ -88,9 +89,9 @@ class ImageClassifier(modelPathPrefix: String,
/**
* To classify batch of input images according to the provided model
*
* @param inputBatch Input batch of Buffered images
* @param topK Get top k elements with maximum probability
* @return List of list of tuples of (class, probability)
* @param inputBatch Input array of buffered images
* @param topK Number of result elements to return, sorted by probability
* @return List of list of tuples of (Label, Probability)
*/
def classifyImageBatch(inputBatch: Traversable[BufferedImage], topK: Option[Int] = None):
IndexedSeq[IndexedSeq[(String, Float)]] = {
Expand Down Expand Up @@ -123,10 +124,10 @@ object ImageClassifier {
/**
* Reshape the input image to a new shape
*
* @param img input image
* @param newWidth rescale to new width
* @param newHeight rescale to new height
* @return Rescaled BufferedImage
* @param img Input image
* @param newWidth New width for rescaling
* @param newHeight New height for rescaling
* @return Rescaled BufferedImage
*/
def reshapeImage(img: BufferedImage, newWidth: Int, newHeight: Int): BufferedImage = {
val resizedImage = new BufferedImage(newWidth, newHeight, BufferedImage.TYPE_INT_RGB)
Expand All @@ -143,10 +144,11 @@ object ImageClassifier {
* <p>
* Note: Caller is responsible to dispose the NDArray
* returned by this method after the use.
*
* @param resizedImage BufferedImage to get pixels from
* @param inputImageShape Should be same as inputDescriptor shape
* @return NDArray pixels array
* </p>
* @param resizedImage BufferedImage to get pixels from
* @param inputImageShape Input shape; for example for resnet it is (1,3,224,224).
Should be same as inputDescriptor shape.
* @return NDArray pixels array
*/
def bufferedImageToPixels(resizedImage: BufferedImage, inputImageShape: Shape): NDArray = {
// Get height and width of the image
Expand Down Expand Up @@ -184,19 +186,19 @@ object ImageClassifier {
}

/**
* Loading input batch of images
* @param inputImagePath Path of single input image
* @return BufferedImage Buffered image
* Loads an input images from file
* @param inputImagePath Path of single input image
* @return BufferedImage Buffered image
*/
def loadImageFromFile(inputImagePath: String): BufferedImage = {
val img = ImageIO.read(new File(inputImagePath))
img
}

/**
* Loading input batch of images
* @param inputImagePaths
* @return List of buffered images-
* Loads a batch of images from a folder
* @param inputImageDirPath Path to a folder of images
* @return List of buffered images
*/
def loadInputBatch(inputImagePaths: List[String]): Traversable[BufferedImage] = {
inputImagePaths.map(path => ImageIO.read(new File(path)))
Expand Down
45 changes: 24 additions & 21 deletions scala-package/infer/src/main/scala/ml/dmlc/mxnet/infer/ObjectDetector.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,15 +27,16 @@ import scala.collection.mutable.ListBuffer
/**
* A class for object detection tasks
*
* @param modelPathPrefix PathPrefix from where to load the symbol, parameters and synset.txt
* Example: file://model-dir/ssd_resnet50_512
* (will resolve both ssd_resnet50_512-symbol.json
* and ssd_resnet50_512-0000.params)
* file://model-dir/synset.txt
* @param inputDescriptors Descriptors defining the input node names, shape,
* layout and Type parameters
* @param contexts Device Contexts on which you want to run Inference, defaults to CPU.
* @param epoch Model epoch to load, defaults to 0.
* @param modelPathPrefix Path prefix from where to load the model artifacts.
* These include the symbol, parameters, and synset.txt.
* Example: file://model-dir/ssd_resnet50_512 (containing
* ssd_resnet50_512-symbol.json, ssd_resnet50_512-0000.params,
* and synset.txt)
* @param inputDescriptors Descriptors defining the input node names, shape,
* layout and type parameters
* @param contexts Device contexts on which you want to run inference.
* Defaults to CPU.
* @param epoch Model epoch to load; defaults to 0
*/
class ObjectDetector(modelPathPrefix: String,
inputDescriptors: IndexedSeq[DataDesc],
Expand All @@ -58,11 +59,12 @@ class ObjectDetector(modelPathPrefix: String,
protected[infer] val width = imgClassifier.width

/**
* To Detect bounding boxes and corresponding labels
* Detects objects and returns bounding boxes with corresponding class/label
*
* @param inputImage : PathPrefix of the input image
* @param topK : Get top k elements with maximum probability
* @return List of List of tuples of (class, [probability, xmin, ymin, xmax, ymax])
* @param inputImage Path prefix of the input image
* @param topK Number of result elements to return, sorted by probability
* @return List of list of tuples of
* (class, [probability, xmin, ymin, xmax, ymax])
*/
def imageObjectDetect(inputImage: BufferedImage,
topK: Option[Int] = None)
Expand All @@ -77,12 +79,13 @@ class ObjectDetector(modelPathPrefix: String,

/**
* Takes input images as NDArrays. Useful when you want to perform multiple operations on
* the input Array, or when you want to pass a batch of input images.
* the input array, or when you want to pass a batch of input images.
*
* @param input : Indexed Sequence of NDArrays
* @param topK : (Optional) How many top_k(sorting will be based on the last axis)
* elements to return. If not passed, returns all unsorted output.
* @return List of List of tuples of (class, [probability, xmin, ymin, xmax, ymax])
* @param input Indexed Sequence of NDArrays
* @param topK (Optional) How many top_k (sorting will be based on the last axis)
* elements to return. If not passed, returns all unsorted output.
* @return List of list of tuples of
* (class, [probability, xmin, ymin, xmax, ymax])
*/
def objectDetectWithNDArray(input: IndexedSeq[NDArray], topK: Option[Int])
: IndexedSeq[IndexedSeq[(String, Array[Float])]] = {
Expand Down Expand Up @@ -136,9 +139,9 @@ class ObjectDetector(modelPathPrefix: String,
/**
* To classify batch of input images according to the provided model
*
* @param inputBatch Input batch of Buffered images
* @param topK Get top k elements with maximum probability
* @return List of list of tuples of (class, probability)
* @param inputBatch Input array of buffered images
* @param topK Number of result elements to return, sorted by probability
* @return List of list of tuples of (class, probability)
*/
def imageBatchObjectDetect(inputBatch: Traversable[BufferedImage], topK: Option[Int] = None):
IndexedSeq[IndexedSeq[(String, Array[Float])]] = {
Expand Down
Loading