imageclassification

imageclassification / ResNetModelRunner / 0.2.0

README.md

Overview

This algorithm takes a pre-trained ResNet[1] and a set of images as input, and performs classification over these images.

Applicable Scenarios and Problems

Let's say you have trained an image classifier using our Image Classification Trainer algorithm. It performs as expected on the test data, and now you are ready to deploy this for future use. Moreover, you want to use the power of Algorithmia platform to deploy your model. This is where the ResNet Model Runner comes into play. You can provide your saved model stored in Algorithmia Data Storage, Amazon S3 or Dropbox and perform inference on new images, which you provide as another input.

Usage

The algorithm expects a model and a path to a folder or a list of files to perform inference on. The output is a set of predictions. Users can also provide a list of class labels to get text labels, instead of integers.

Input

Required Arguments

  • (Required) A string denoting the URI where the model is located.
  • (Required) A string or list of strings denoting the URI of the images that will be provided as input to the model.
  • (Optional) A list of strings containing the string labels for each class.
  • (Optional) A list of labels containing ground truth values for test data for evaluation.

Output

  • A list containing class predictions for provided images. If class_labels is provided, this list performs a one-to-one mapping between the elements of class_labels and class_ids. If not, only integers returned.

  • accuracy is returned if a ground_truth parameter is provided in the input.

Examples

Example 1.

Below is the bare minimum example, with two inputs: one for pre-trained model and a folder for the images.

{
        "pretrained_model_path": "data://.my/saved_models/resnet-152.t7",
        "images": "data://.my/sample_train_data",
}

Output:

{
    'test_predictions': [5, 5, 0, 2, 0, 4, 5, 5, 2, 0, 6, 3, 0, 0, 0, 2, 0, 0, 0, 1, 0, 3, 5, 0, 0, 0, 1 .... ]
}

Example 2.

Alternatively, it is possible to provide a list of strings, each for a single image.

{
        "pretrained_model_path": "data://.my/saved_models/resnet-152.t7",
        "images": ["data://.my/sample_train_data/image1.jpg",
                   "data://.my/sample_train_data/image2.jpg",
                   "data://.my/sample_train_data/image3.jpg",
                   "data://.my/sample_train_data/image4.jpg",
                   ...
                   ...
                   ...
                   ]
}

Output:

{
    'test_predictions': [5, 5, 0, 2, 0, 4, 5, 5, 2, 0, 6, 3, 0, 0, 0, 2, 0, 0, 0, 1, 0, 3, 5, 0, 0, 0, 1 .... ]
}

Example 3.

A complete example including the optional arguments is as follows:

{
        "pretrained_model_path": "data://.my/saved_models/resnet-152.t7",
        "images": ["data://.my/sample_train_data/image1.jpg",
                   "data://.my/sample_train_data/image2.jpg",
                   "data://.my/sample_train_data/image3.jpg",
                   "data://.my/sample_train_data/image4.jpg",
                   ...
                   ...
                   ...
                   ],
        "ground_truth" : ["cat", "cat", "cat", "dog", "dog", .... ],
        "class_labels" : ["cat", "dog"]
}

Output:

{
    "test_predictions": ["cat", "dog", "cat", "cat", "dog", .... ]
    "accuracy": 87.2
}

Attributions

The algorithm uses a ResNet[1] pre-trained on ImageNet[2] dataset. The ResNet implementation and the pre-trained ResNet are parts of torchvision library, and implemented in PyTorch.

torchvision library is copyrighted under BSD 3-Clause license(A copy of the license document can be found at: https://github.com/pytorch/vision/blob/master/LICENSE).

PyTorch library is copyrighted under BSD 3-Clause license(A copy of the license document can be found at: https://github.com/pytorch/pytorch/blob/master/LICENSE).

Parts of this algorithm has been modified from fine-tuning.pytorch library by Bumsoo Kim. This library is copyrighted under MIT License (A copy of the license document can be found at: https://github.com/meliketoy/fine-tuning.pytorch/blob/master/LICENSE)

[1] https://arxiv.org/pdf/1512.03385.pdf

[2] [2] http://www.image-net.org/