Work with Cognitive Image Functionality

You can provide the inputs for these two functionalities in two ways:

By uploading a single image file as input. In this case, the equivalent tensor format of the uploaded image is generated with proper preprocessing for the model. Supported image file formats include:
- Bitmap (.bmp)
- Portable Bitmap (.pbm)
- Portable Graymap (.pgm)
- Portable Pixmap (.ppm)
- Sun Raster Graphic (.sr)
- Raster Graphic (.ras)
- Joint Photographic Expert Group (.jpeg, .jpg, .jpe, .jp2)
- Tag Image File Format (.tiff, .tif)
- Portable Network Graphics (.png)
By uploading a collection of scoring input records. Here, mini-batch scoring with ONNX image models is done with <model_attribute_name, value/array> pairs. Here, value/array can be either an encoded image in base64 string or a 4D array storing processed image pixel values. The shape of the 4D array must be 1x3x224x224.

Use the Linux utility jq to parse the JSON output into a readable format. The jq utility is included in all the major Linux distribution repositories. On Oracle Linux and Red Hat systems, you can install this utility by running this command:

$ sudo yum install jq

Note:

Using jq in the cURL command does not return the HTTP response. To return HTTP response, remove jq command and add the -i flag to the curl command.

This section lists these examples that demonstrates how to:

Get a list of model endpoints
Get the topN categories of an image along with their respective probabilities
Get the feature extraction results for input images

1: Get a List of Model Endpoints

This example shows how to get a list of model endpoints. Run the following command to get the list of model endpoints:

curl -X GET --header "Authorization: Bearer ${token}" "<oml-cloud-service-location-url>/omlmod/v1/cognitive-image"

The command returns the following details:

{
    "items": [
        {
            "name": "classification",
            "description": "A cognitive image scoring endpoint that returns the classification of the images.",
            "links": [
                {
                    "rel": "classification",
                    "href": "http://adb.us-sanjose-1.oraclecloud.com/omlmod/v1/cognitive-image/classification"
                },
                {
                    "rel": "self",
                    "href": "http://adb.us-sanjose-1.oraclecloud.com/omlmod/v1/cognitive-image/."
                }
            ]
        },
        {
            "name": "feature-extraction",
            "description": "A cognitive image scoring endpoint that extracts features of the images.",
            "links": [
                {
                    "rel": "feature-extraction",
                    "href": "http://adb.us-sanjose-1.oraclecloud.com/omlmod/v1/cognitive-image/feature-extraction"
                },
                {
                    "rel": "self",
                    "href": "http://adb.us-sanjose-1.oraclecloud.com/omlmod/v1/cognitive-image/."
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "self",
            "href": "http://adb.us-sanjose-1.oraclecloud.com/omlmod/v1/cognitive-image"
        }
    ]
}

2: Get the Top N Categories of an Image

This example shows how to get the top N categories of an image that is in .jpg format by sending a POST request to the cognitive-image/classification endpoint. This example also returns the probabilities of each categories that the input images belong to.

Run the following command to get the top 4 categories that the image img.jpg could possibly belong to along with the probabilities:

curl -X POST --header "Authorization: Bearer $token" <oml-cloud-service-location-url>/omlmod/v1/cognitive-image/classification \
-F imageData=@img.jpg
-F topN=4

In this example:

$token is the environmental variable that is assigned to the token obtained through the Authorization API.
img.png is the path of the image file. In this example, the picture contains a small dog.
4 is the number of top classes with the corresponding probabilities returned by the model.
topN is an optional parameter for classification endpoints. Pass this parameter as part of the input to determine how many categories to return for each images sorted by probabilities. topN must be >=0. By default, the top 5 classes with the highest probabilities are returned. When topN=0, the entire unsorted classification output list is returned.

The command returns the top 4 classes along with their respective probabilities. Here is the scoring result:

{
    "scoringResults": [
        {
            "classifications": [
                {
                    "label": "Dog",
                    "probability": 0.9995992183685303
                },
                {
                    "label": "Puppy",
                    "probability": 0.9975613355636597
                },
                {
                    "label": "Companion dog",
                    "probability": 0.997296154499054
                },
                {
                    "label": "Dog breed",
                    "probability": 0.9910918474197388
                }
            ]
        }
    ]
}

3: Get the Image Feature Extraction Results

This example demonstrates how to get the image feature extraction results for the input images by sending a POST request to the cognitive-image/feature-extraction endpoint. This functionality uses the prebuilt ONNX image model for scoring.

Run the following cURL command to get the most relevant keywords:

curl -X POST --header "Authorization: Bearer $token" 
<oml-cloud-service-location-url>/omlmod/v1/cognitive-image/feature-extraction \
-F imageData=@img.png

The command returns the weights of all features.

{
    "scoringResults": [
        {
            "weights": [
                0.1776999,
                0.30117133,
                0.0,
                0.0,
                0.0,
                0.06017106,
                0.0,
                0.007070067,
                0.0,
                0.0,
                0.0
            ]
        }
    ]
}