Posted by So far, to showcase BigML’s upcoming Object Detection release, we have demonstrated how you can annotate images on the platform, we have covered an example use case to detect cats and dogs and shared how to execute the newly available features by using the BigML Dashboard, as well as another example to build a plant disease detector. In contrast, this installment demonstrates how to perform Object Detection by calling the BigML REST API.
Briefly, Object Detection is a supervised learning technique for images that not only shows where an object is in the image, but it also can show where instances of objects from multiple classes are located in the image. Let’s jump in and see how we can put it to use programmatically.
Authentication
Before using the API, you must set up your environment variables. You should set BIGML_USERNAME, BIGML_API_KEY, and BIGML_AUTH in your .bash_profile. BIGML_USERNAME is just your username. Your BIGML_API_KEY can be found on the Dashboard by clicking on your username to pull up the account page, and then clicking on ‘API Key’. Finally, BIGML_AUTH is simply the combination of these elements.
export BIGML_USERNAME=my_name export BIGML_API_KEY=123456789 export BIGML_AUTH=“username=$BIGML_USERNAME;api_key=$BIGML_API_KEY;“
Upload Your Data
For this tutorial, we’re using the same cats and dogs dataset used in our previous tutorial demonstrating the new BigML Dashboard capabilities. Once again, a zip file containing a large number of images is organized into multiple folders.
Data sources can be uploaded to BigML in many different ways, so this step should be appropriately adapted to your data with the help of the API documentation. Here, we will create our data source using a local zip file.
curl "https://bigml.io/source?$BIGML_AUTH" -F file=@cats-dogs.zip
You could also upload images included in the cats and dogs dataset to BigML independently and later build a new composite source to group them like this.
curl "https://bigml.io/source?$BIGML_AUTH" \
-X POST \
-H 'content-type: application/json'
-d '{"sources": ["62a978411f386f7d7d000000", "62a978411f386f7d7d000003", ...]}'
Once you have a composite source, you can add, remove or replace the images inside the source by updating the source with arguments: add_sources, remove_sources, or sources. For example, you can use the following command to remove an image from the composite source.
curl "https://bigml.io/source/62a977dd1f386f7d7a000000?$BIGML_AUTH" \
-X PUT \
-H 'content-type: application/json'
-d '{"remove_sources": ["62a978411f386f7d7d000003"]}'</pre>
Annotate Your Data
In our previous tutorial of the BigML Dashboard, we explained Object Detection needs a dedicated field type called regions to build models and showed you how to create them in the Dashboard. Now, we explain how to do the same using the BigML API.
First off, BigML creates a regions field automatically if it’s able to detect a json field in the zip file with the correct structure describing the regions in each image. To create a regions field via the API, you can use the following command, which specifies the required info for the new field, that is, a name and the optype.
curl "https://bigml.io/source/62a977dd1f386f7d7a000000?$BIGML_AUTH" \
-X PUT \
-H 'content-type: application/json'
-d '{
"new_fields": [
{"name": "boxes", "optype": "regions"}
]
}'
You can define as many regions fields as you need.
Now, you have to annotate the images, which means marking what objects are where in the images. You can do this by using the following command, which specifies the list of components (images in the composite) to update, the field id of the regions field, and the value containing the information that define the object instances in the image.
curl "https://bigml.io/source/602e12b74e72556f5100000a?$BIGML_AUTH" \
-X PUT \
-H 'content-type: application/json'
-d '{
"row_values": [
{
"components": [
"62a97825ff0b6052502c8d3a"
],
"field": "100002",
"value": [
[
"cat",
0.03488372093023256,
0.16020671834625322,
0.39244186046511625,
0.8191214470284238
],
[
"dog",
0.46656976744186046,
0.17571059431524547,
0.8473837209302325,
0.8837209302325582
]
]
}
]
}'
In the above example we are annotating two objects in the image with two different classes, cat and dog.
Kindly remember that the full list of arguments can be found in our API documentation.
Creating a Dataset
A BigML dataset is a separate resource and is a serialized form of your data. In the Dashboard, it’s displayed with some simple summary statistics and is the resource consumed by Machine Learning algorithms. To create a dataset from your uploaded data via the API, you can use the following command that specifies the source used to generate the dataset.
curl "https://bigml.io/dataset?$BIGML_AUTH" \
-X POST \
-H 'content-type: application/json' \
-d '{"source": "source/602e12b74e72556f5100000a"}'
Creating a Deepnet
In order to create the Deepnet, you just need your dataset ID. In this case, BigML will train a particular class of deep neural networks — Convolutional Neural Networks (CNN).
curl "https://bigml.io/deepnet?$BIGML_AUTH" \
-X POST \
-H 'content-type: application/json' \
-d '{"dataset": "dataset/62a97d0b1f386f7d7d000027"}'
You guessed it! The full list of Deepnet arguments can also be found in our API documentation.
Evaluating the Deepnet
Once ready, you can evaluate the deepnets predictive performance. You just need to use the deepnet ID and the dataset containing the instances that you want to evaluate against. By default, BigML will provide multiple performance metrics some of which may be more relevant than others for your use case.
curl "https://bigml.io/evaluation?$BIGML_AUTH" \
-X POST \
-H 'content-type: application/json' \
-d '{"dataset": "dataset/62a97d581f386f7d7d00002a",
"deepnet": "deepnet/62a97d741f386f7d7d00002d"}'
Once you have your Evaluation, you may decide that you want to change some of your Deepnets parameters to improve its performance. No problem. If so, just repeat the previous step with different parameters.
Detecting objects: Making Predictions
When you are satisfied with the outstanding performance of your Deepnet, you can begin to use it to detect objects in new images.
To detect objects in an image, which is also referred to as making a single prediction, you must have previously uploaded the image to the BigML platform, which implies that you already have a source created for it. You can select an individual image in existing sources, either single images or images included in composite sources. You just need to pass the value of the source id as the value for the label field.
curl "https://bigml.io/prediction?$BIGML_AUTH" \
-X POST \
-H 'content-type: application/json' \
-d '{
"deepnet": "deepnet/62a97d741f386f7d7d00002d",
"input_data": {
"000002": "source/62a978411f386f7d7d000000"
}
}'
You can also detect objects in many images at the same time by using batch predictions. In this case, you need a dataset containing the images you want to classify.
curl "https://bigml.io/batchprediction?$BIGML_AUTH" \
-X POST \
-H 'content-type: application/json' \
-d '{"deepnet": "deepnet/62a97d741f386f7d7d00002d",
"dataset" : "dataset/62a97d581f386f7d7d00002a"}'
You can also configure the output of the batch prediction, whose full list of arguments can be found in our API documentation. How about that? Once the bath prediction is finished, you can easily download the result as a CSV file, or generate an output dataset whichever suits your needs.
Want to know more about Object Detection?
If you have any questions or you would like to learn more about how Object Detection works, please visit the release page. It includes a series of blog posts to gently introduce Object Detection from scratch. And remember to register for our free live webinar that will take place on June 28, 2022 at 8:00 AM PST / 10:00 AM CST / 5:00 PM CET.
The Official Blog of BigML.com 