Skip to content

Commit b4e7e5e

Browse files
ajbozarthajbozarth
authored
Update README for Code Pattern (#3)
## README Updates - Added Code Pattern Title - Added Code Pattern Overview - Added Code Pattern Goals - Added Flow and Architecture Diagram rough draft - Added Steps ToC - Added (Optional) API Step - Updated icons README with License - Made small text and formatting updates ## Code Pattern Documentation to be added to wiki ### Code Pattern Long Name (wiki: Short Description) Use an open source object detector deep learning model to display and filter objects recognized in an image in a web application ### Code Pattern Description (wiki: Introduction) The IBM Model Asset eXchange (MAX) has given application developers without data science experience easy access to prebuilt machine learning models. This code pattern shows how to create a simple web application to visualize the text output of a MAX model. The web app uses the Object Detector from MAX and creates a simple web UI that displays bounding boxes around detected objects in an image and lets you filter the objects based on their label and probable accuracy given by the model.
1 parent 6a57728 commit b4e7e5e

File tree

3 files changed

+119
-10
lines changed

3 files changed

+119
-10
lines changed

‎README.md

Lines changed: 114 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,35 @@
11
[![Build Status](https://travis-ci.org/CODAIT/MAX-Object-Detector-Web-App.svg?branch=master)](https://travis-ci.org/CODAIT/MAX-Object-Detector-Web-App)
22

3-
# Object Detector Web App
4-
A web app wrapping the [MAX Object Detector](https://github.com/IBM/MAX-Object-Detector) model output
3+
# Create a web app to visually interact with objects detected using machine learning
4+
5+
In this Code Pattern we will use one of the models from the
6+
[Model Asset eXchange (MAX)](https://developer.ibm.com/code/exchanges/models/),
7+
an exchange where developers can find and experiment with open source deep learning models.
8+
Specifically we will be using the [Object Detector](https://github.com/IBM/MAX-Object-Detector)
9+
to create a web application that will recognize objects in an image and allow the user to
10+
filter the objects based on their detected label and prediction accuracy. The web application
11+
provides an interactive user interface backed by a lightweight Node.js server using Express.
12+
The server hosts a client-side web UI and relays API calls to the model from the web UI to a REST
13+
end point for the model. The Web UI takes in an image and sends it to the model REST endpoint
14+
via the server and displays the detected objects on the UI. The model's REST endpoint is set up
15+
using the docker image provided on MAX. The Web UI displays the detected objects in an image
16+
using a bounding box and label and includes a toolbar to filter the detected objects based on
17+
their labels or a threshold for the prediction accuracy.
18+
19+
When the reader has completed this Code Pattern, they will understand how to:
20+
21+
* Build a docker image of the Object Detector MAX Model
22+
* Deploy a deep learning model with a REST endpoint
23+
* Recognize objects in an image using the MAX Model's REST API
24+
* Run a web application that using the model's REST API
25+
26+
![Architecture](doc/source/images/architecture.png)
27+
28+
## Flow
29+
30+
1. User uses Web UI to send an image to Model API
31+
2. Model API returns object data and Web UI displays detected objects
32+
3. User interacts with Web UI to view and filter detected objects
533

634
## Included Components
735

@@ -18,7 +46,25 @@ free and open source deep learning models.
1846

1947
## Run Locally
2048

21-
### Deploy the Model
49+
#### Start the Model API
50+
51+
1. [Deploy the Model](#1-deploy-the-model)
52+
2. [Experiment with the API (Optional)](#2-experiment-with-the-api-optional)
53+
54+
#### Start the Web App
55+
56+
0. [Use the embedded web app](#use-the-embedded-web-app)
57+
1. [Get a local copy of the repository](#1-get-a-local-copy-of-the-repository)
58+
2. [Install dependencies](#2-install-dependencies)
59+
3. [Start the web app server](#3-start-the-web-app-server)
60+
4. [Configure ports (Optional)](#4-configure-ports-optional)
61+
62+
### Start the Model API
63+
64+
> NOTE: The set of instructions in this section are a modified version of the ones found on the
65+
[Object Detector Project Page](https://github.com/IBM/MAX-Object-Detector)
66+
67+
#### 1. Deploy the Model
2268

2369
To run the docker image, which automatically starts the model serving API, run:
2470

@@ -30,12 +76,73 @@ This will pull a pre-built image from Docker Hub (or use an existing image if al
3076
If you'd rather build the model locally you can follow the steps in the
3177
[model README](https://github.com/IBM/MAX-Object-Detector/#steps).
3278

79+
#### 2. Experiment with the API (Optional)
80+
81+
The API server automatically generates an interactive Swagger documentation page.
82+
Go to `http://localhost:5000` to load it. From there you can explore the API and also create test requests.
83+
84+
Use the `model/predict` endpoint to load a test image and get predicted labels for the image from the API.
85+
The coordinates of the bounding box are returned in the `detection_box` field, and contain the array of normalized
86+
coordinates (ranging from 0 to 1) in the form `[ymin, xmin, ymax, xmax]`.
87+
88+
The [model assets folder](https://github.com/IBM/MAX-Object-Detector/tree/master/assets)
89+
contains a few images you can use to test out the API, or you can use your own.
90+
91+
You can also test it on the command line, for example:
92+
93+
```
94+
$ curl -F "image=@assets/dog-human.jpg" -XPOST http://localhost:5000/model/predict
95+
```
96+
97+
You should see a JSON response like that below:
98+
99+
```json
100+
{
101+
"status": "ok",
102+
"predictions": [
103+
{
104+
"label_id": "1",
105+
"label": "person",
106+
"probability": 0.944034993648529,
107+
"detection_box": [
108+
0.1242099404335022,
109+
0.12507188320159912,
110+
0.8423267006874084,
111+
0.5974075794219971
112+
]
113+
},
114+
{
115+
"label_id": "18",
116+
"label": "dog",
117+
"probability": 0.8645511865615845,
118+
"detection_box": [
119+
0.10447660088539124,
120+
0.17799153923988342,
121+
0.8422801494598389,
122+
0.732001781463623
123+
]
124+
}
125+
]
126+
}
127+
```
128+
129+
You can also control the probability threshold for what objects are returned using the `threshold` argument like below:
130+
131+
```
132+
$ curl -F "image=@assets/dog-human.jpg" -XPOST http://localhost:5000/model/predict?threshold=0.5
133+
```
134+
135+
The optional `threshold` parameter is the minimum `probability` value for predicted labels returned by the model.
136+
The default value for `threshold` is `0.7`.
137+
33138
### Start the Web App
34139

140+
#### Use the embedded web app
141+
35142
The latest release of the web app is deployed with the model API above and is available at
36143
[`http://localhost:5000/app`](http://localhost:5000/app)
37144

38-
To start the web app using the latest development code follow the steps below:
145+
To start the web app using Node.js and running the latest code, follow the steps below:
39146

40147
#### 1. Get a local copy of the repository
41148

@@ -53,13 +160,13 @@ $ cd MAX-Object-Detector-Web-App
53160

54161
#### 2. Install dependencies
55162

56-
Make sure node.js and npm are installed then, in a terminal, run the following command:
163+
Make sure Node.js and npm are installed then, in a terminal, run the following command:
57164

58165
```
59166
$ npm install
60167
```
61168

62-
#### 3. Start the Web App
169+
#### 3. Start the web app server
63170

64171
You then start the web app by running:
65172

@@ -69,7 +176,7 @@ $ node app
69176

70177
You can then access the web app at: [`http://localhost:8090`](http://localhost:8090)
71178

72-
#### 4. Configuring ports (Optional)
179+
#### 4. Configure ports (Optional)
73180

74181
If you want to use a different port or are running the model API at a different location you can change them with command-line options:
75182

‎doc/source/images/architecture.png

34.4 KB
Loading

‎static/img/cocoicons/README.md

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
The images contained here are taken from https://github.com/cocodataset/cocodataset.github.io
1+
The icons contained here were taken as is from the [COCO website GitHub](https://github.com/cocodataset/cocodataset.github.io)
2+
with permission of the COCO Consortium.
23

3-
They are used with the permission of the COCO team and this README will be
4-
removed once we have a open source license to reference in their repository.
4+
# License
5+
6+
"[COCO Website](http://cocodataset.org)" by [COCO Consortium](http://cocodataset.org/#people) is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0)

0 commit comments

Comments
 (0)