NAV
javascript python shell

Introduction

Monocular is a computer vision API with a whole range of computer vision and image analysis endpoints. These computer vision and image analysis functions are accessed via the API and the data is returned as an easy to parse structure in your chosen language.

What can you do with Monocular?

Here are just a couple of the many things you can do with Monocular:

What is the user dashboard all about?

The user dashboard is your central place for all things Monocular. Here you will find your apps, your API key, SDKs, usage statistics, docs, support options and account management. Everything in one neat little package!

Dashboard

What is an application?

Applications are used to grant access to the API. Applications are what holds your app ID and secret, therefore at least one application is required to connect to the API.

Note: We highly recommend creating separate applications for each code base you have that uses Monocular, to easily visualise your data on the dashboard. Applications are also a useful way to provide security as they can be suspended as needed.

API Call Pricing

Your MonocularAPI subscription provides you with a set number of credits to use per month. The price for an endpoint is shown in a purple circle next to the heading within the documentation. CRUD endpoints are free to use.

The number of credits used by an endpoint depends on the computational complexity of the algorithm. Simple processing endpoints, such as resize or crop, will cost a single credit, with more complex algorithms like testing an object detector costing five or more credits.

Note that these credits are typically on a per-image basis. Thus, the cost of training an object detector will depend on the number of images used. In these cases, the documentation will explain how the credit charge is calculated.

Getting Started

All API calls require an account; calls are tied to an account and an application. The setup is very easy — this guide will walk you through creating and accessing your new account.

1. Create an account

To create an account just head to the sign up page here . You will need to enter your name, email and password and hit sign up - once you’ve done this you’re only one step away from creating your first app!

Sign up window

2. Check your email

Check your email and click your confirmation link to sign in to the dashboard.

3. Choose a plan

We’ll start you off on the free plan so you can start creating right away! To upgrade you will need to update your billing information and choose a plan.

4. Create an application

To create an application you will need to be logged in. Click on the apps icon and hit on the create the new app button.

Create application

Choose a name for your app and click create. You will now have created your first app! You can now access your app ID and secret.

Created application

5. Next steps

The last thing to do is to get setup with your chosen SDK in your favourite language from the examples below and start using Monocular!

To install your SDK, use the following Code:

<script src="https://cdn.jemsoft.io/monocular-javascript-sdk/sdk-1.0.0.js"></script>
pip install monocular
Why not try one of our friendly SDKs?

Authentication

To authorize your App, use this code:

Monocular.initialize({
  clientId: 'jemsonAppID'
});
import monocular

monocular.initialize({ client_id: 'jemsonAppID',
                       client_secret: 'jemsonSecret'
                    })
curl -X POST -d 'client_id=3ee342f69a95865be2fa6fefacd0cbb7&
client_secret=fe134fc7d5944a0b99e7158fb4a22a268c685b0b&
grant_type=client_credentials&
scope=monocular'
"http://monocular.dev/api/oauth/token"

Be sure to replace jemsonAppId with your App ID.

To access Monocular the SDKs need to be provided with particular information regarding your app, particularly your AppID which can be found on the Monocular dashboard.

HTTP Request

All requests to Monocular require an authorization token generated through the following request.

POST https://monocular.jemsoft.io/api/oauth/token

Query Parameters

Parameter Description
client_id The id of the app making the request
client_secret The secret of the app making the request

Manually requesting a token returns JSON with the following format:

{
  "access_token": "access_token",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Usage

To use a token generated from a request, add a header to new requests with the key Authorization. The value should consist of the token_type, then a single space character, followed by access_token. The expires_in value is in seconds, for now thats always an hour.

Referrer URLs

Referrer URLs are used by the Javascript SDK to validate your App without requiring you to store your app secret in your code. This is important for front end only applications!

If you’re developing locally you can include your local host, for example localhost:3000/ however, make sure you remove this when you’re finished, or others could use your account!

This referrer URL feature is useful for front end apps as it will prevent others from stealing your App ID & Secret and using it in their own projects. Add Referrer URLs for where you will be serving your app from. For example, a project hosted at https://monocular.jemsoft.io/face-detector/ can have any of the following Referrer URLs:

https://monocular.jemsoft.io/face-detector

https://monocular.jemsoft.io

You will have to add another line if your app requires both HTTP and HTTPS access.

Processing

Monocular provides a set of processing tools to modify and process images to produce better results when used for computer vision.

See Image Processing to apply processes to images stored on Monocular.

Upscale

1 CREDIT

// Upscale a canvas image
Monocular.upscale(image, {
  'encodeType': 'PNG'
}).then((response) => {

}).catch((error) {
  // Handle errors here
});

// Upscale an image from a URL
Monocular.upscale(url, {
  'encodeType': 'PNG'
}).then((response) => {

}).catch((err) => {

});
# Upscale a PIL image or an image at a path
upscaledImage = Monocular.upscale(
  image=path_or_PIL_image,
  encodeType='PNG')

# Upscale an image from a URL
upscaledImage = Monocular.upscale(
  url='http://image.at.url.com/image.png',
  encodeType='PNG')
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "image=@image/path"
-F "encodeType=PNG"
"https://monocular.jemsoft.io/api/upscale"

curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "url=image/url"
-F "encodeType=PNG"
"https://monocular.jemsoft.io/api/upscale"

Scale the image by a ratio of 1:2 (Doubles the size of the image).

Practical applications

Upscaling may be useful when an object in an image is small (less than 100 x 100 pixels).

Query parameters

Parameter Type Description
image Image (JPEG, PNG, BMP) The image to upscale.
url String The URL of an image to upscale (instead of image).
encodeType String The type to encode the resulting image as.

HTTP Request

POST https://monocular.jemsoft.io/api/upscale

Downscale

1 CREDIT

// Downscale a canvas image
Monocular.downscale(image, {
  'encodeType': 'PNG'
}).then((response) => {

});

// Downscale an iamge from a URL
Monocular.downscale(url, {
  'encodeType': 'PNG'
}).then((response) => {

}).catch((error) {
  // Handle errors here
});
# Downscale a PIL image or an image at a path
downscaledImage = Monocular.downscale(
  image=path_or_PIL_image,
  encode_type='PNG')

# Downscale an image from a URL
downscaledImage = Monocular.downscale(
  url='http://...',
  encode_type='PNG')
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "image=@image/path"
-F "encodeType=PNG"
"https://monocular.jemsoft.io/api/downscale"

curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "url=image/url"
-F "encodeType=PNG"
"https://monocular.jemsoft.io/api/downscale"

Scale the image by a ratio of 2:1 (Halves the size of the image).

Practical applications

Downscaling may be useful when an object in an image is large (greater than 1000 x 1000 pixels).

Query Parameters

Parameter Type Description
image Image (JPEG, PNG, BMP) The image to downscale.
url String The URL of an image to downscale (instead of image).
encodeType String The type to encode the resulting image as.

HTTP Request

POST https://monocular.jemsoft.io/api/downscale

Resize

1 CREDIT

// Resize a canvas image
Monocular.resize(image, {
  'encodeType': 'PNG',
  'width': 1920,
  'height': 1080
}).then((response) => {

}).catch((error) {
  // Handle errors here
});

// Resize an image from a URL
Monocular.resize(url, {
  'encodeType': 'PNG',
  'width': 1920,
  'height': 1080
}).then((response) => {

}).catch((error) {
  // Handle errors here
});
# Resize a PIL image or an image at a path
resizedImage = Monocular.resize(
  image=path_or_PIL_image,
  encode_type='PNG',
  width=1920,
  height=1080)

# Resize an image from a URL
resizedImage = Monocular.resize(
  url='http://...',
  encode_type='PNG',
  width=1920,
  height=1080)
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "image=@image/path"
-F "encodeType=PNG"
-F "width=1920"
-F "height=1080"
"https://monocular.jemsoft.io/api/resize"

curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "url=image/url"
-F "encodeType=PNG"
-F "width=1920"
-F "height=1080"
"https://monocular.jemsoft.io/api/resize"

Resize an image to the given width and height.

Query Parameters

Parameter Type Description
image Image (JPEG, PNG, BMP) The image to resize.
url String The URL of an image to resize (instead of image).
encodeType String The type to encode the resulting image as.
width Number Width of resulting image (pixels) Max. 10000
height Number Height of resulting image (pixels) Max. 10000

HTTP Request

POST https://monocular.jemsoft.io/api/resize

Rotate

1 CREDIT

// Rotate a canvas image
Monocular.rotate(image, {
  'encodeType': 'PNG',
  'angle': angle
}).then((response) => {

}).catch((error) {
  // Handle errors here
});

// Rotate an image from a URL
Monocular.rotate(url, {
  'encodeType': 'PNG',
  'angle': angle
}).then((response) => {

}).catch((error) {
  // Handle errors here
});
# Rotate a PIL image or an image at a path
rotatedImage = Monocular.rotate(
  image=path_or_PIL_image,
  encode_type='PNG',
  angle=90)

# Rotate an image from a URL
rotatedImage = Monocular.rotate(url='http://...',
  encode_type='PNG',
  angle=90)
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "image=@image/path"
-F "encodeType=PNG"
-F "angle=90"
"https://monocular.jemsoft.io/api/rotate"

curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "url=image/url"
-F "encodeType=PNG"
-F "angle=90"
"https://monocular.jemsoft.io/api/rotate"

Rotate an image by the given number of degrees.

Query Parameters

Parameter Type Description
image Image (JPEG, PNG, BMP) The image to rotate.
url String The URL of an image to rotate (instead of image).
encodeType String The type to encode the resulting image as.
angle Number Angle of resulting image (degrees)

HTTP Request

POST https://monocular.jemsoft.io/api/rotate

Flip

1 CREDIT

// Flip a canvas image
Monocular.flip(image, {
  'encodeType': 'PNG',
  'vertical': boolean,
  'horizontal': boolean
}).then((response) => {

}).catch((error) {
  // Handle errors here
});

// Flip an image from a URL
Monocular.flip(image, {
  'encodeType': 'PNG',
  'vertical': boolean,
  'horizontal': boolean
}).then((response) => {

}).catch((error) {
  // Handle errors here
});
# Flip a PIL image or an image at a path
flippedImage = Monocular.flip(
  image=path_or_PIL_image,
  encode_type='PNG',
  vertical=True,
  horizontal=False)

# Flip an image from a URL
flippedImage = Monocular.flip(
  url='http://...',
  encode_type='PNG',
  vertical=True,
  horizontal=True)
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "image=@image/path"
-F "encodeType=PNG"
-F "vertical=true"
-F "horizontal=false"
"https://monocular.jemsoft.io/api/flip"

curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "url=image/url"
-F "encodeType=PNG"
-F "vertical=true"
-F "horizontal=false"
"https://monocular.jemsoft.io/api/flip"

Flips an image horizontally, vertically or both horizontally and vertically.

Practical Applications

If an object is symmetrical, you could flip the object for more training data.

Query Parameters

Parameter Type Description
image Image (JPEG, PNG, BMP) The image to rotate.
url String The URL of an image to rotate (instead of image).
encodeType String The type to encode the resulting image as.
horizontal Boolean Flip the image horizontally.
vertical Boolean Flip the image vertically.

HTTP Request

POST https://monocular.jemsoft.io/api/flip

Crop

1 CREDIT

// Crop a canvas image
Monocular.crop(image, {
  'encodeType': 'PNG',
  'left': number,
  'top': number,
  'right': number,
  'bottom': number
}).then((response) => {

}).catch((error) {
  // Handle errors here
});

// Crop an image from a URL
Monocular.crop(image, {
  'encodeType': 'PNG',
  'left': number,
  'top': number,
  'right': number,
  'bottom': number
}).then((response) => {

}).catch((error) {
  // Handle errors here
});
# Crop a PIL image or an image at a path
croppedImage = Monocular.crop(
  image=path_or_PIL_image,
  encode_type='PNG',
  left=30, top=30,
  right=1000, bottom=800)

# Crop an image from a URL
croppedImage = Monocular.crop(
  url='http://...',
  encode_type='PNG',
  left=30, top=30,
  right=1000, bottom=800)
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "image=@image/path"
-F "encodeType=PNG"
-F "top=0"
-F "left=0"
-F "bottom=1000"
-F "right=1000"
"https://monocular.jemsoft.io/api/crop"

curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "url=image/url"
-F "encodeType=PNG"
-F "top=0"
-F "left=0"
-F "bottom=1000"
-F "right=1000"
"https://monocular.jemsoft.io/api/crop"

Crops an image to the given left-top (x1, y1), and right-bottom (x2, y2) coordinates of a rectangle.

Query Parameters

Parameter Type Description
image Image (JPEG, PNG, BMP) The image to rotate.
url String The URL of an image to rotate (instead of image).
encodeType String The type to encode the resulting image as.
left Number Left element of the left, top coordinate or ‘x1’ 0 < left < right
top Number Top element of the left, top coordinate or 'y1’ 0 < top < bottom
right Number Right element of the right, bottom coordinate or 'x2’. left < right < image_width
bottom Number Bottom element of the right, bottom coordinate or 'y2’ top < bottom < image_height

HTTP Request

POST https://monocular.jemsoft.io/api/crop

Erode and Dilate

1 CREDIT

// Coming Soon
# Coming Soon
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "image=@image/path"
-F "encodeType=PNG"
-F "anchor=[1,1]"
-F "kernelAnchor=[1,1]"
-F "kernelShape=Rectangle"
-F "kernelSize=[3, 3]"
-F "borderType=Reflect"
-F "iterations=2"
"https://monocular.jemsoft.io/api/erode"

curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "url=image/url"
-F "encodeType=PNG"
-F "anchor=[1,1]"
-F "kernelAnchor=[1,1]"
-F "kernelShape=Rectangle"
-F "kernelSize=[3, 3]"
-F "borderType=Reflect"
-F "iterations=2"
"https://monocular.jemsoft.io/api/erode"

Erode

Erosion is a morphological operation that can be thought of as growing the darker regions of the image and shrinking the lighter regions.

Dilate

Dilate is a morphological operation that can be thought of as shrinking the darker regions of the image and growing the lighter regions

Practical Applications

Some practical applications are: - Thickening or thinning lines - If the line is black and our background is white, then a erosion will will thicken the line and dilation with thin out the line. - Filling or finding holes within the image - By expanding the black or white parts of the image, if our image has black ‘holes’ within particular shapes of interest, we can perform a dilations on the image which will shrink these holes until there is eventually no more holes within the image. The same is true for white holes and erosion. - Removing noise from an image - If you have a lot of black spots in your image, then using a dilation may be worthwhile to look into.

Query Parameters

Parameter Type Description
image Image (JPEG, PNG, BMP) The image to rotate.
url String The URL of an image to rotate (instead of image).
encodeType String The type to encode the resulting image as.
anchor [Number, Number] [x, y] where x and y make up the center point of the structuring element.
kernelAnchor [Number, Number] [x, y] where x and y make up the center point of the structuring element.
kernelShape String Shape of the structuring element, either Rectangle, Ellipse or Cross.
kernelSize [Number, Number] [width, height] where width and height make up the size of the structuring element you wish to use.
borderType String Determines the pixel location if the structuring element goes out of bounds.
borderValue Number Value to use for the Constant border type.
iterations Number Amount of times to do the operation (Maximum of 10).

Border Types

The border type is used to determine the pixel location if the structuring element goes out of bounds of the image.

Type Description
Replicate Replicates the values around the borders.
Reflect Reflects the values in the image to outside of the border.
Reflect 101 Does the same as reflect, but ignores the value around the closest border.
Wrap Wraps the border around.
Constant Sets anything out of bounds to a constant value (borderValue)

HTTP Request

POST https://monocular.jemsoft.io/api/erode

POST https://monocular.jemsoft.io/api/dilate

Threshold

1 CREDIT

// Coming Soon
# Coming Soon
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "image=@image/path"
-F "encodeType=PNG"
-F "threshold=127"
-F "max=255"
-F "thresholdType=Binary"
"https://monocular.jemsoft.io/api/threshold"

curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "url=image/url"
-F "encodeType=PNG"
-F "threshold=127"
-F "max=255"
-F "thresholdType=Binary"
"https://monocular.jemsoft.io/api/threshold"

A threshold transforms any pixel below or above a certain threshold to some value. The value it transforms it to depends on the type of threshold you are using.

Query Parameters

Parameter Type Description
image Image (JPEG, PNG, BMP) The image to rotate.
url String The URL of an image to rotate (instead of image).
encodeType String The type to encode the resulting image as.
threshold Number Threshold value to use. (Maximum 255)
max Number Maximum value of the threshold. (Maximum 255)
thresholdType String Type of threshold to use.

Threshold Types

Type Description
Binary A binary threshold either sets pixel to 0 or to the maxValue. This will set the pixel to maxValue if the pixel is greater than the specified threshold.
Binary Inverted This is the opposite of Binary, it sets the pixel to maxValue if the pixel is less than the specified threshold.
To Zero To zero will leave the pixel alone if it is greater than a certain threshold, otherwise if it is less than or equal to a certain threshold it will transform it to zero.
To Zero Inverted The opposite of To Zero, leaves the pixel alone if it is less than a certain threshold, otherwise if it is greater than or equal to a certain threshold it will transform it to zero.
Truncate Truncate will truncate each pixel to threshold if it is greater than threshold. Otherwise it is left alone.

HTTP Request

POST https://monocular.jemsoft.io/api/threshold

Distance Transform

1 CREDIT

// Coming Soon
# Coming Soon
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "image=@image/path"
-F "encodeType=PNG"
-F "distanceType=manhattan"
-F "maskSize=5x5"
"https://monocular.jemsoft.io/api/distance-transform"

curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "url=@image/path"
-F "encodeType=PNG"
"https://monocular.jemsoft.io/api/distance-transform"

Transforms an image to a distance map. This distance map represents how far away each pixel is from the nearest black pixel. Black pixels by definition will have distance 0.

Query Parameters

Parameter Type Description
image Image (JPEG, PNG, BMP) The image to rotate.
url String The URL of an image to rotate (instead of image).
encodeType String The type to encode the resulting image as.
distanceType String Distance type to use.
maskSize String Mask size to use

Distance Types

Type Equation
Manhattan Manhattan Distance
Euclidean (straight line distance) Euclidean Distance
Chess Chess Distance

Mask Sizes

HTTP Request

POST https://monocular.jemsoft.io/api/distance_transform

Greyscale

1 CREDIT

// Greyscale a canvas image
Monocular.greyscale(image, {
  'encodeType': 'PNG'
}).then((response) => {

}).catch((error) {
  // Handle errors here
});

// Greyscale an image from a URL
Monocular.greyscale(url, {
  'encodeType': 'PNG'
}).then((response) => {

}).catch((err) => {

});
# Greyscale a PIL image or an image at a path
greyscaleImage = Monocular.greyscale(
  image=path_or_PIL_image,
  encodeType='PNG')

# Greyscale an image from a URL
greyscaleImage = Monocular.greyscale(
  url='http://image.at.url.com/image.png',
  encodeType='PNG')
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "image=@image/path"
-F "encodeType=PNG"
"https://monocular.jemsoft.io/api/greyscale"

curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "url=image/url"
-F "encodeType=PNG"
"https://monocular.jemsoft.io/api/greyscale"

Applies a greyscale to the image. This is used to make an image monochromatic.

Query parameters

Parameter Type Description
image Image (JPEG, PNG, BMP) The image to apply the greyscale to.
url String The URL of an image to apply the greyscale to (instead of image).
encodeType String The type to encode the resulting image as.

HTTP Request

POST https://monocular.jemsoft.io/api/greyscale

Invert

1 CREDIT

// Invert a canvas image
Monocular.invert(image, {
  'encodeType': 'PNG'
}).then((response) => {

}).catch((error) {
  // Handle errors here
});

// Invert an image from a URL
Monocular.invert(url, {
  'encodeType': 'PNG'
}).then((response) => {

}).catch((err) => {

});
# Invert a PIL image or an image at a path
invertedImage = Monocular.invert(
  image=path_or_PIL_image,
  encodeType='PNG')

# Invert an image from a URL
invertedImage = Monocular.invert(
  url='http://image.at.url.com/image.png',
  encodeType='PNG')
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "image=@image/path"
-F "encodeType=PNG"
"https://monocular.jemsoft.io/api/invert"

curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "url=image/url"
-F "encodeType=PNG"
"https://monocular.jemsoft.io/api/invert"

Inverts the image.

Query parameters

Parameter Type Description
image Image (JPEG, PNG, BMP) The image to invert.
url String The URL of an image to invert (instead of image).
encodeType String The type to encode the resulting image as.

HTTP Request

POST https://monocular.jemsoft.io/api/invert

Blur

1 CREDIT

// Blur a canvas image
Monocular.blur(image, type, {
  'encodeType': 'PNG'
}).then((response) => {

}).catch((error) {
  // Handle errors here
});

// Blur an image from a URL
Monocular.blur(url, type, {
  'encodeType': 'PNG'
}).then((response) => {

}).catch((err) => {

});
# Invert a PIL image or an image at a path
blurredImage = Monocular.blur(
  image=path_or_PIL_image,
  encodeType='PNG')

# Invert an image from a URL
blurredImage = Monocular.blur(
  url='http://image.at.url.com/image.png',
  encodeType='PNG')
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "image=@image/path"
-F "encodeType=PNG"
-F "type=Mean"
"https://monocular.jemsoft.io/api/blur"

curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "url=image/url"
-F "encodeType=PNG"
-F "type=Mean"
"https://monocular.jemsoft.io/api/blur"

Blurs the image.

Query parameters

Parameter Type Description
image Image (JPEG, PNG, BMP) The image to invert.
url String The URL of an image to invert (instead of image).
encodeType String The type to encode the resulting image as.
type String The type of blur to apply. Different types require different parameters. (Mean, Median and Gaussian)

Mean

Parameter Type Description
kernelAnchor [Number, Number] [x, y] where x and y make up the center point of the filtering element. Both x and y must be odd.
kernelSize [Number, Number] [width, height] where width and height make up the size of the filtering element.

Median

Parameter Type Description
kernelSize Number The size of the filtering element. Only one number is required as it is a square.

Gaussian

Parameter Type Description
kernelSize [Number, Number] [width, height] where width and height make up the size of the filtering element.

HTTP Request

POST https://monocular.jemsoft.io/api/blur

Face Detection

5 CREDITS

Face and Landmark Detection

// Detect faces in an image and include the locations of facial landmarks.
Monocular.faceDetection(image, {
  'landmarks': true;
}).then((response) => {

}).catch((error) {
  // Handle errors here
});

// Detect faces in an image and do not include the locations of facial landmarks.
Monocular.faceDetection(image, {
  'landmarks': false;
}).then((response) => {

}).catch((error) {
  // Handle errors here
});
# Perform face detection on a PIL image or an image at a path and do not include landmarks.
results = Monocular.face_detection(landmarks=False, image=path_or_PIL_image)

# Perform face detection on an image from a URL and include landmarks
results = Monocular.face_detection(landmarks=True, url='http://...'))
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "image=@image/path"
-F "landmarks=true"
"https://monocular.jemsoft.io/api/face-detection"

curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "url=image/url"
-F "landmarks=true"
"https://monocular.jemsoft.io/api/face-detection"

The above command returns JSON structured like this:

[
  {
    "top": 229,
    "left": 80,
    "bottom": 675,
    "right": 526,
    "landmarks": [
      [
        122,
        375
      ],
      [
        126,
        428
      ],
      [
        136,
        481
      ],
      [
        146,
        535
      ],
      [
        163,
        585
      ],
      [
        195,
        628
      ],
      .
      .
      .
    ]
  },
  {
    "top": 129,
    "left": 8,
    "bottom": 575,
    "right": 460,
    "landmarks": [
      .
      .
      .
    ]
  }
]

Given an image it returns the bounding boxes of detected faces in the image. It would also return the estimated pose of a face (if landmarks are true). The pose takes the form of 68 landmarks.

Query Parameters

Parameter Type Description
image Image (JPEG, PNG, BMP) The image to detect faces in.
url String The URL of an image to detect faces in (instead of image).
landmarks Boolean Includes the locations of facial landmarks in the response.

HTTP Request

POST http://example.com/api/face-detection

Images

The Monocular API can store and process images under 50 megabytes, encoded as one of the formats listed below. An Image can be sent as a file or Monocular can retrieve them itself from a URL.

The Monocular SDKs handle images in particular ways that are native, or compatible with their languages.

// Generates a canvas from an image provided in an HTML input of type 'file'

fileInput = document.getElementById("imageInput");

fileInput.onchange = function(event) {
  imageFile = fileInput.files[0];
  imageURL = URL.createObjectURL(imageFile);
  var image = new Image();
  image.setAttribute('crossOrigin', 'Anonymous');

  image.onload = () => {
    var canvas = document.createElement('canvas');
    canvas.height = image.height;
    canvas.width = image.width;
    var ctx = canvas.getContext('2d');
    ctx.drawImage(image, 0, 0);

    document.body.appendChild(canvas);
  };

  image.src = imageURL;
}
# Creates a PIL image from a file on the host computer

from PIL import Images

# Generates a path using a relative path to a file
path = os.path.dirname(os.path.abspath(__file__)) + 'relative/path/to/file.png'

# Opens the path in a PIL image
imageFile = Image.open(path)

Create Image

Monocular.images.create(image, options).then((response) {
  // Process response here
}).catch((error) {
  // Handle errors here
});

import monocular

image = monocular.images.create(image, options)

# Process response here
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "label=newImage"
"https://monocular.jemsoft.io/api/images/"

The above command returns JSON structured like this:

{
  "fileName": "",
  "label": "Foo Bar",
  "id": "",
  "ownerId": "",
  "createdAt": "2016-01-01T12:00:00.000Z",
  "updatedAt": "2016-01-01T12:00:00.000Z"
}

Creates an image with the options provided. If the image is to be uploaded with the request, ensure the content-type is multipart/form-data.

Request Parameters

Parameter Type Description
image Image (JPEG, PNG, BMP) The image to store.
url String The URL of the image to store (instead of image).
boundingBoxes Array The bounding boxes of interest in the image, see formatting of Bounding Boxes.
ignoredBoundingBoxes Array The bounding boxes of to ignore in the image, see formatting of Bounding Boxes.
label String The label to apply to the image. (Optional)

HTTP Request

POST https://monocular.jemsoft.io/api/images/

Get All Images

Monocular.images.findAll().then((response) => {
  // Process the response here
}).catch((error) {
  // Handle errors here
});
import monocular

response = monocular.images.find_all()

# Process the response here
curl -X GET
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
"https://monocular.jemsoft.io/api/images/"

The above command returns JSON structured like this:

[
  {
    "fileName": "",
    "label": "Foo",
    "id": "",
    "ownerId": "",
    "createdAt": "2016-01-01T12:00:00.000Z",
    "updatedAt": "2016-01-01T12:00:00.000Z"
  },
  {
    "fileName": "",
    "boundingBoxes": [
      [
        20,
        40,
        20,
        40
      ]
    ],
    "ignoredBoundingBoxes": [],
    "label": "Bar",
    "id": "",
    "ownerId": "",
    "createdAt": "2016-01-01T12:01:00.000Z",
    "updatedAt": "2016-01-01T12:01:00.000Z"
  }
]

Returns all images.

Request Parameters

Parameter Type Description

HTTP Request

GET https://monocular.jemsoft.io/api/images/

Get Image

Monocular.images.findById(imageID).then((response) {
  // Process response here
}).catch((error) {
  // Handle errors here
});
import monocular

response = monocular.images.find_one(imageID)

# Process response here
curl -X GET
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
"https://monocular.jemsoft.io/api/images/<ID>"

The above command returns JSON structured like this:

{
  "fileName": "",
  "label": "Foo Bar",
  "id": "",
  "ownerId": "",
  "createdAt": "2016-01-01T12:00:00.000Z",
  "updatedAt": "2016-01-01T12:00:00.000Z"
}

Returns a specific image given an ID.

HTTP Request

GET https://monocular.jemsoft.io/api/images/<ID>/

URL Parameters

Parameter Description
ID The ID of the image to retrieve

Download Image

Monocular.images.download(imageID).then((image) {
  // Process image here
}).catch((error) {
  // Handle errors here
});
import monocular

response = monocular.images.download(imageID)

# Process response here
curl -X GET
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
"https://monocular.jemsoft.io/api/images/<ID>/download"

Returns a stream of the image file given an ID.

HTTP Request

GET https://monocular.jemsoft.io/api/images/<ID>/download

URL Parameters

Parameter Description
ID The ID of the image to download

Download Thumbnail

Monocular.images.thumbnail(imageID).then((thumbnail) {
  // Process thumbnail here
}).catch((error) {
  // Handle errors here
});
# Coming Soon
curl -X GET
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
"https://monocular.jemsoft.io/api/images/<ID>/thumbnail"

Returns a stream of the image’s thumbnail given an ID.

HTTP Request

GET https://monocular.jemsoft.io/api/images/<ID>/thumbnail

URL Parameters

Parameter Description
ID The ID of the image to download the thumbnail of

Delete Image

Monocular.images.del(imageID).then((response) {
  // Process response here
}).catch((error) {
  // Handle errors here
});
import monocular

response = monocular.images.delete(imageID)

# Process response here
curl -X DELETE
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
"https://monocular.jemsoft.io/api/images/<ID>"

The above command returns JSON structured like this:

{
  "fileName": "",
  "label": "Foo Bar",
  "id": "",
  "ownerId": "",
  "createdAt": "2016-01-01T12:00:00.000Z",
  "updatedAt": "2016-01-01T12:00:00.000Z"
}

Deletes a specific image given an ID.

HTTP Request

DELETE https://monocular.jemsoft.io/api/images/<ID>

URL Parameters

Parameter Description
ID The ID of the image to retrieve

Update Image

Monocular.images.update(imageID, options).then((response) {
  // Process response here
}).catch((error) {
  // Handle errors here
});
response = monocular.images.update(imageID, options)

# Process response here
curl -X PUT
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
"https://monocular.jemsoft.io/api/images/<ID>"

The above command returns JSON structured like this:

{
  "fileName": "",
  "boundingBoxes": [
    [
      20,
      40,
      20,
      40
    ]
  ],
  "ignoredBoundingBoxes": [],
  "label": "Bar",
  "id": "",
  "ownerId": "",
  "createdAt": "2016-01-01T12:01:00.000Z",
  "updatedAt": "2016-01-01T12:01:00.000Z"
}

This endpoint updates a specific image given an ID. This can be useful for adding or removing bounding boxes and changing the label.

HTTP Request

GET https://monocular.jemsoft.io/api/images/<ID>/download

URL Parameters

Parameter Description
ID The ID of the image to retrieve

Image Processing

Images that are stored on Monocular can have processing applied to them. There is very little difference between requesting processing on an image stored on Monocular and an image that is not stored on Monocular.

To process an image stored on Monocular using one of our SDKs, use the processing methods included under Monocular.image. There is also another parameter to consider. If the save parameter is set to true, then the result of the processing will also permanently replace the original image.

When saving the changes to an image the API will return the updated image metadata in JSON format. You can set the returnImage parameter to true to request the modified image back. However, we strongly recommend instead for you to redownload an image once changes have been applied to it.

// When processing a stored image using the Javascript SDK,
// use the processing methods included in monocular.image

// For Example:
Monocular.image.upscale(imageID, {
  'encodeType': 'PNG',
  'save': true
}).then((response) => {

}).catch((error) {

});
# When processing a stored image using the Python SDK,
# use the processing methods included in monocular.image

# For Example:
upscaledImage = Monocular.images.upscale(
  image_id='image_id',
  encodeType='PNG',
  save=True)
When processing a stored image using curl the only difference is the image/<ID> in the URL and the
save parameter.

curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "encodeType=PNG"
-F "save=true"
"https://monocular.jemsoft.io/api/images/<ID>/upscale"

Face Detection

5 CREDITS

Perform face detection on an image.

See Face Detection for more information regarding parameters and usage.

HTTP Request

POST https://monocular.jemsoft.io/api/images/<ID>/face-detection

Upscale

1 CREDIT

Scale the image by a ratio of 1:2 (Doubles the size of the image).

See Upscale for more information regarding parameters and usage.

HTTP Request

POST https://monocular.jemsoft.io/api/images/<ID>/upscale

Downscale

1 CREDIT

Scale a stored image by a ratio of 2:1 (Halves the size of the image).

See Downscale for more information regarding parameters and usage.

HTTP Request

POST https://monocular.jemsoft.io/api/images/<ID>/downscale

Resize

1 CREDIT

Resize a stored image to the given width and height.

See Resize for more information regarding parameters and usage.

HTTP Request

POST https://monocular.jemsoft.io/api/images/<ID>/resize

Rotate

1 CREDIT

Rotates a stored image by the given number of degrees.

See Rotate for more information regarding parameters and usage.

HTTP Request

POST https://monocular.jemsoft.io/api/images/<ID>/rotate

Flip

1 CREDIT

Flips an image horizontally, vertically or both horizontally and vertically.

See Flip for more information regarding parameters and usage.

HTTP Request

POST https://monocular.jemsoft.io/api/images/<ID>/flip

Crop

1 CREDIT

Crops an image to the given left-top, and right-bottom coordinates of a rectangle.

See Crop for more information regarding parameters and usage.

HTTP Request

POST https://monocular.jemsoft.io/api/images/<ID>/crop

Erode and Dilate

1 CREDIT

See Erode and Dilate for more information regarding parameters and usage.

HTTP Request

POST https://monocular.jemsoft.io/api/images/<ID>/erode

POST https://monocular.jemsoft.io/api/images/<ID>/dilate

Threshold

1 CREDIT

See Threshold for more information regarding parameters and usage.

A threshold transforms any pixel below or above a certain threshold to some value. The value it transforms it to depends on the type of threshold you are using.

HTTP Request

POST https://monocular.jemsoft.io/api/images/<ID>/threshold

Distance Transform

1 CREDIT

See Distance Transform for more information regarding parameters and usage.

HTTP Request

POST https://monocular.jemsoft.io/api/images/<ID>/distance_transform

Greyscale

1 CREDIT

See Greyscale for more information regarding parameters and usage.

Makes an image greyscale.

HTTP Request

POST https://monocular.jemsoft.io/api/images/<ID>/greyscale

Invert

1 CREDIT

See Invert for more information regarding parameters and usage.

Inverts an image.

HTTP Request

POST https://monocular.jemsoft.io/api/images/<ID>/invert

Blur

1 CREDIT

See Blur for more information regarding parameters and usage.

Blurs the image using one of three available blur types.

HTTP Request

POST https://monocular.jemsoft.io/api/images/<ID>/blur

Data Buckets

Data buckets are used to create collections of data for training. To train any of our models you will need to attach a Databucket to it before training.

Note In future Data Buckets will be able to hold various Data Types. At the moment we only have a single data type (images). So your databuckets will default to the image datatype.

Create A Data Bucket

Monocular.databucket.create(label).then((response) => {

});
response = monocular.databucket.create(label);
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "label=Workplace Team Members"
"https://monocular.jemsoft.io/api/databuckets/"

The above command returns JSON structured like this:

{
  "id":"cf758c57d6c1ce69001ce1c1",
  "label":"Workplace Team Members",
  "locked":false,
  "dataType":"image",
  "dataObjectIDs":[],
  "processingData": {
    "status":"READY",
    "progress":0
  },
  "ownerId":"b2f185579c64878e00fced92",
  "createdAt":"2016-07-18T06:23:11.070Z",
  "updatedAt":"2016-07-18T06:23:11.071Z"
}

Creates a new Data Bucket with the provided label.

Request Parameters

Parameter Type Description
label String The label of your Data Bucket.

HTTP Request

POST https://monocular.jemsoft.io/api/databuckets/

Get Data Bucket

Monocular.databucket.getDataBucket(dataBucketID).then((response) => {

}).catch((error) {
  // Handle errors here
})
response = monocular.databucket.find_one(dataBucketID)

# Process response here
curl -X GET
-H "Authorization: Bearer OAuthToken"
https://monocular.jemsoft.io/api/databuckets/<ID>

The above command returns JSON structured like this:

{
  "id":"cf758c57d6c1ce69001ce1c1",
  "label":"Workplace Team Members",
  "locked":false,
  "dataType":"image",
  "dataObjectIDs":[],
  "processingData": {
    "status":"READY",
    "progress":0
  },
  "ownerId":"b2f185579c64878e00fced92",
  "createdAt":"2016-07-18T06:23:11.070Z",
  "updatedAt":"2016-07-18T06:23:11.071Z"
}

Gets an individual Data Bucket.

Request Parameters

Parameter Type Description
ID String The ID of the Data Bucket.

HTTP Request

GET https://monocular.jemsoft.io/api/databuckets/<ID>

Get All Data Buckets

Monocular.databucket.getAll().then((response) => {

}).catch((error) {
  // Handle errors here
});
response = monocular.databucket.find_all()
curl -X GET
-H "Authorization: Bearer OAuthToken"
"https://monocular.jemsoft.io/api/databuckets/"

The above command returns JSON structured like this:

[
  {
    "id":"cf758c57d6c1ce69001ce1c1",
    "label":"Workplace Team Members",
    "locked":false,
    "dataType":"image",
    "dataObjectIDs":[],
    "processingData": {
      "status":"READY",
      "progress":0
    },
    "ownerId":"b2f185579c64878e00fced92",
    "createdAt":"2016-07-18T06:23:11.070Z",
    "updatedAt":"2016-07-18T06:23:11.071Z"
  },
  {
    "id":"cf758c57d6c1ce69001ce1c2",
    "label":"Workplace Volunteers",
    "locked":false,
    "dataType":"image",
    "dataObjectIDs":[],
    "processingData": {
      "status":"READY",
      "progress":0
    },
    "ownerId":"b2f185579c64878e00fced92",
    "createdAt":"2016-07-18T06:23:11.070Z",
    "updatedAt":"2016-07-18T06:23:11.071Z"
  }
]

Gets all Data Buckets.

HTTP Request

GET https://monocular.jemsoft.io/api/databuckets/

Delete Data Bucket

Deletes a Data Bucket.

Monocular.databucket.del(databucketID).then((response) => {

}).catch((error) {
  // Handle errors here
});
# Coming Soon
curl -X DELETE
-H "Authorization: Bearer OAuthToken"
"https://monocular.jemsoft.io/api/databuckets/<ID>"

The above command returns JSON structured like this:

{
  "count": 1
}

Request Parameters

Parameter Type Description
id String ID of the Data Bucket to delete.

HTTP Request

DELETE https://monocular.jemsoft.io/api/databuckets/<ID>

Add Data

Monocular.detector.addData(databucketId, data).then((response) => {

}).catch((error) {
  // Handle errors here
});
response = monocular.detectors.add_data(databucket_id, data)
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "data=[imageIDs]"
"https://monocular.jemsoft.io/api/databuckets/<ID>/objects"

The above command returns JSON structured like this:

{
  "success": true,
  "status": 200,
  "msg": "Successfully added."
}

Add data to the data bucket. Data ids must be valid IDs for the buckets data type.

Request Parameters

Parameter Type Description
id String ID of the Data Bucket to add data too.
data Array or String Array of Image IDs to add multiple images, or a single Image ID string to add a single image.

HTTP Request

POST https://monocular.jemsoft.io/api/detectors/<ID>/objects

Remove Data

Monocular.detector.removeData(databucketId, data).then((response) => {

}).catch((error) {
  // Handle errors here
});
response = monocular.detectors.remove_data(databucket_id, data)
curl -X DELETE
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "data=[imageIDs]"
"https://monocular.jemsoft.io/api/databuckets/<ID>/objects"

The above command returns JSON structured like this:

{
  "success": true,
  "status": 200,
  "msg": "Successfully removed."
}

Remove data from the data bucket. Data ids must match IDs in the bucket.

Request Parameters

Parameter Type Description
id String ID of the Data Bucket to remove data from.
data Array or String Array of Image IDs to remove multiple images, or a single Image ID string to remove a single image.

HTTP Request

DELETE https://monocular.jemsoft.io/api/detectors/<ID>/objects

Face Identifiers

Monocular allows users to create their own collection of faces to run Identification on.

Before training, Monocular will run your image through some simple pre-processing to optimise training, We run a Face Detection on the image and crop it to the first face found. If no faces are found, the image is discarded.

You will need a relatively large amount of training images for each face. We recommend 40-50 images for reasonable accuracy. Results will improve with more training data. We also recommend keeping a few images of each face to test against to find a confidence score threshold.

Create Face Identifier

Monocular.faceIdentifier.create(label).then((response) => {

});
response = monocular.face_identifiers.create(label);
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "label=Workplace Team Members"
"https://monocular.jemsoft.io/api/face-identifiers/"

The above command returns JSON structured like this:

{
  "label": "Workplace Team Members",
  "trainingData": {
    "status": "NOT_TRAINED"
  },
  "faces": {},
  "id": "a9da8157f27d581e00542775",
  "ownerId": "a7da8157f27d581e004c2775",
  "createdAt": "2016-07-10T05:18:33.325Z",
  "updatedAt": "2016-07-10T05:18:33.325Z"
}

Creates a new Face Identifier with the provided label.

Request Parameters

Parameter Type Description
label String The name of your Face Identifier.

HTTP Request

POST https://monocular.jemsoft.io/api/face-identifiers/

Get Face Identifier

Monocular.faceIdentifier.getFaceIdentifier(identifierID).then((response) => {

}).catch((error) {
  // Handle errors here
})
response = monocular.face_identifiers.find_one(identifierID)

# Process response here
curl -X GET
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
https://monocular.jemsoft.io/api/face-identifiers/<ID>

The above command returns JSON structured like this:

{
  "label": "Workplace Team Members",
  "trainingData": {
    "status": "NOT_TRAINED|QUEUED|TRAINING|SUCCESS|FAILED",
    "trainingError": {}
  },
  "faces": {},
  "id": "a9da8157f27d581e00542775",
  "ownerId": "a7da8157f27d581e004c2775",
  "createdAt": "2016-07-10T05:18:33.325Z",
  "updatedAt": "2016-07-10T05:18:33.325Z"
}

Gets an individual Face Identifier.

NOTE: that this is the endpoint you must poll to determine whether or not the Face Identifier has finished training.

Request Parameters

Parameter Type Description
ID String The ID of the Face Identifier.

HTTP Request

GET https://monocular.jemsoft.io/api/face-identifiers/<ID>

Get All Face Identifiers

Monocular.faceIdentifier.getAll().then((response) => {

}).catch((error) {
  // Handle errors here
});
response = monocular.face_identifiers.find_all()
curl -X GET
-H "Authorization: Bearer OAuthToken"
"https://monocular.jemsoft.io/api/face-identifiers/"

The above command returns JSON structured like this:

[
  {
    "label": "Workplace Team Members",
    "trainingData": {
      "status": "NOT_TRAINED|QUEUED|TRAINING|SUCCESS|FAILED"
    },
    "faces": {},
    "id": "a9da8157f27d581e00542775",
    "ownerId": "a7da8157f27d581e004c2775",
    "createdAt": "2016-07-10T05:18:33.325Z",
    "updatedAt": "2016-07-10T05:18:33.325Z"
  },
  {
    "label": "Workplace Volunteers",
    "trainingData": {
      "status": "NOT_TRAINED|QUEUED|TRAINING|SUCCESS|FAILED"
    },
    "faces": {},
    "id": "a9da8157f27d581e00542777",
    "ownerId": "a7da8157f27d581e004c2775",
    "createdAt": "2016-07-10T05:18:33.325Z",
    "updatedAt": "2016-07-10T05:18:33.325Z"
  }
]

Gets all Face Identifiers.

HTTP Request

GET https://monocular.jemsoft.io/api/face-identifiers/

Delete Face Identifier

Deletes a Face Identifier.

Monocular.faceIdentifier.del(identifierID).then((response) => {

}).catch((error) {
  // Handle errors here
});
# Coming Soon
curl -X DELETE
-H "Authorization: Bearer OAuthToken"
"https://monocular.jemsoft.io/api/face-identifiers/<ID>"

The above command returns JSON structured like this:

{
  "count": 1
}

Request Parameters

Parameter Type Description
id String ID of the Face Identifier to delete.

HTTP Request

DELETE https://monocular.jemsoft.io/api/face-identifiers/<ID>

Add Face

Add a new face to the identifier. Faces are linked to DataBuckets and the content of the databucket is used as Training Data for that face. The face label is used to indicate which face was found when running identification.

You will need to retrain your Face Identifier once adding a face to it.

Monocular.faceIdentifier.addFace(identifierId, dataBucketId, label).then((response) => {

}).catch((error) {
  // Handle errors here
});
response = monocular.face_identifiers.add_face(identifierId, databucket, label)
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "dataBucketId=dataBucketId"
-F "label=Daniel"
"https://monocular.jemsoft.io/api/face-identifiers/<ID>/faces"

The above command returns JSON structured like this:

{
  "success": true,
  "status": 200,
  "msg": "Successfully added face: Daniel"
}

Request Parameters

Parameter Type Description
ID String ID of the Face Identifier to use.
dataBucket String A single DataBucket ID string to use as training data.
label String A string used to label any result containing this face.

HTTP Request

POST https://monocular.jemsoft.io/api/face-identifiers/<ID>/faces

Remove Face

Monocular.faceIdentifier.removeFace(identifierId, label).then((response) => {

}).catch((error) {
  // Handle errors here
});
monocular.face_identifier.remove_face(identifier_id, label)
curl -X DELETE
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "label=daniel"
"https://monocular.jemsoft.io/api/face-identifiers/<ID>/images"

The above command returns JSON structured like this:

{
  "success": true,
  "status": 200,
  "msg": "Successfully removed face: Daniel"
}

Removes a face from the Face Identifier.

You will need to retrain your Face Identifier once removing a face from it.

Request Parameters

Parameter Type Description
label String Label of the face to remove

HTTP Request

DELETE https://monocular.jemsoft.io/api/face-identifiers/<ID>/faces

Train

20 CREDITS

Monocular.faceIdentifier.train(identifierId).then((response) => {

}).catch((error) {
  // Handle errors here
});
response = monocular.face_identifier.train(identifierId)
curl -X POST
-H "Authorization: Bearer OAuthToken"
"https://monocular.jemsoft.io/api/face-identifiers/<ID>/train"

The above command returns JSON structured like this:

{
  "success": true,
  "status": 200,
  "msg": "Successfully queued for training."
}

Begin training the Face Identifier. The time it takes is dependent on the number of images in the training sets (Faces) This process can take a significant amount of time when using large data sets.

Note that this endpoint is charged once per image for all images in your training set. For example, a Face Identifier of 3 faces with 50 images for each face will charge 3,000 credits against your subscription.

Request Parameters

Parameter Type Description
id String ID of the Face Identifier to queue for training.

HTTP Request

POST https://monocular.jemsoft.io/api/face-identifiers/<ID>/train

Upload and Identify

5 CREDITS

Runs your Face Identifier on an image that is not stored on Monocular.

Monocular.faceIdentifier.identify(identifierId, image).then((response) => {

}).catch((error) {
  // Handle errors here
});
response = monocular.face_identifier.identify(identifier_id, image=image)
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "image=@image/path" or "url=image/url"
"https://monocular.jemsoft.io/api/face-identifiers/<ID>/identify"

The above command returns JSON structured like this:

[
  {
    "label": "Daniel",
    "confidence": 100,
    "box": {
      "top": 20,
      "left": 20,
      "bottom": 120,
      "right": 120
    }
  }
]

Request Parameters

Parameter Type Description
id String ID of the Face Identifier to use.
image Image (JPEG, PNG, BMP) The image to run Identification on.
url String The URL of the image to run identification on.

HTTP Request

POST https://monocular.jemsoft.io/api/face-identifiers/<ID>/identify

Find and Identify

5 CREDITS

Runs your Face Identifier on an image that is stored on Monocular.

Monocular.faceIdentifier.identify(identifierId, imageId).then((response) => {

}).catch((error) {
  // Handle errors here
});
response = monocular.face_identifier.identify(identifier_id, image_id)
curl -X POST
-H "Authorization: Bearer OAuthToken"
"https://monocular.jemsoft.io/api/face-identifiers/<ID>/identify/<imageID>"

The above command returns JSON structured like this:

[
  {
    "label": "Daniel",
    "confidence": 100,
    "box": {
      "top": 20,
      "left": 20,
      "bottom": 120,
      "right": 120
    }
  }
]

Request Parameters

Parameter Type Description
ID String ID of the Face Identifier to use.
imageID Image (JPEG, PNG, BMP) The image to run Identification on.

HTTP Request

POST https://monocular.jemsoft.io/api/face-identifiers/<ID>/identify/<imageID>

Background Subtractors

Background Subtractors are dynamic background subtraction algorithms that learn from the images they are given to determine which sections of the image are background and which are foreground.

In more detail, background subtraction is performed by marking a foreground pixel any pixel that is more than sqrt(varThreshold) standard deviations away from from the first B distributions (B is determined within the algorithm).

Background Subtractor Types

Currently the only type of Background Subtractor available on Monocular is called MOG.

Each type has its own parameters which can be set either on creation, or after creation using update.

MOG Parameters

Parameter Type Description
bgRatio float Defines the ratio of the minimum amount of pixels that should be in the background.
history number The length of the history. That is, how many previous images affect the background model.
numMixtures number The maximum amount of mixtures to be used. A mixture models each background pixel as a gaussian distribution, where the different gaussians represent different colours. This should typically be small (3 to 5).
noiseSigma number The standard deviation of the brightness of each colour channel. 0 is a special value, which means it is learned automatically.
varThreshold float Defines a threshold for the variance (std dev squared) for the brightness of a pixel. Default is 2.5^2 (2.5 standard deviations away). That is, a pixel should be at most 2.5 standard deviations away from the modelled background to be classified as the background.

Create Background Subtractor

Monocular.backgroundSubtractor.create(label, options).then((response) => {

});
response = monocular.background_subtractors.create(label, type, type_options);
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "label=BackgroundSubtractor"
-F "<param>=<value>"
"https://monocular.jemsoft.io/api/background-subtractors/"

The above command returns JSON structured like this:

{
  "label": "BackgroundSubtractor",
  "id": "id",
  "type": "MOG",
  "bgRatio": 16,
  "history": 20,
  "numMixtures": 10,
  "noiseSigma": 10,
  "varThreshold": 0.2,
  "ownerId": "ownerID",
  "createdAt": "2016-05-04T08:07:14.254Z",
  "updatedAt": "2016-05-04T08:07:14.255Z"
}

Creates a new background subtractor with the provided characteristics.

Request Parameters

Parameter Type Description
label String The name of your background subtractor.
type String The type of algorithm your background subtractor uses. MOG is currently the only available type. (Default: MOG)

Each type has it’s own parameters that can be provided when the background subtractor is created.

HTTP Request

POST https://monocular.jemsoft.io/api/background-subtractors/

Get Background Subtractor

Monocular.backgroundSubtractor.getBackgroundSubtractor(id).then((response) => {

}).catch((error) {
  // Handle errors here
})
response = monocular.background_subtractors.find_one(id)

# Process response here
curl -X GET
-H "Authorization: Bearer OAuthToken"
https://monocular.jemsoft.io/api/background_subtractors/<ID>

The above command returns JSON structured like this:

{
  "label": "BackgroundSubtractor",
  "id": "id",
  "type": "MOG",
  "bgRatio": 16,
  "history": 20,
  "numMixtures": 10,
  "noiseSigma": 10,
  "varThreshold": 0.2,
  "ownerId": "ownerID",
  "createdAt": "2016-05-04T08:07:14.254Z",
  "updatedAt": "2016-05-04T08:07:14.255Z"
}

Gets an individual Background Subtractor.

Request Parameters

Parameter Type Description
ID String The ID of the background subtractor.

HTTP Request

GET https://monocular.jemsoft.io/api/background-subtractors/<ID>

Get All Background Subtractors

Monocular.backgroundSubtractor.getAll().then((response) => {

}).catch((error) {
  // Handle errors here
});
response = monocular.background_subtractors.find_all()
curl -X GET
-H "Authorization: Bearer OAuthToken"
"https://monocular.jemsoft.io/api/background-subtractors/"

The above command returns JSON structured like this:

[
  {
    "label": "BackgroundSubtractor",
    "id": "id",
    "type": "MOG",
    "bgRatio": 16,
    "history": 20,
    "numMixtures": 10,
    "noiseSigma": 10,
    "varThreshold": 0.2,
    "ownerId": "ownerID",
    "createdAt": "2016-05-04T08:07:14.254Z",
    "updatedAt": "2016-05-04T08:07:14.255Z"
  },
  {
    "label": "BackgroundSubtractor2",
    "id": "id",
    "type": "MOG",
    "bgRatio": 16,
    "history": 20,
    "numMixtures": 10,
    "noiseSigma": 10,
    "varThreshold": 0.2,
    "ownerId": "ownerID",
    "createdAt": "2016-05-04T08:07:14.254Z",
    "updatedAt": "2016-05-04T08:07:14.255Z"
  }
]

Gets all background subtractors.

HTTP Request

GET https://monocular.jemsoft.io/api/background-subtractors/

Delete Background Subtractor

Monocular.backgroundSubtractor.del(id).then((response) => {

}).catch((error) {
  // Handle errors here
});
monocular.background_subtractors.delete(id)
curl -X DELETE
-H "Authorization: Bearer OAuthToken"
"https://monocular.jemsoft.io/api/background-subtractors/<ID>"

The above command returns JSON structured like this:

{
  "count": 1
}

Deletes a background subtractor.

Request Parameters

Parameter Type Description
id String ID of the background subtractor to delete.

HTTP Request

DELETE https://monocular.jemsoft.io/api/background-subtractors/<ID>

Update and Changing Parameters

var bgSubData = {
  bgRatio: 20,
  history: 100,
  numMixtures: 16,
  noiseSigma: 4,
  varThreshold: 0.6
};

Monocular.backgroundSubtractor.update(bgSubData).then((response) => {

});
bgSubData = {
  bgRatio: 20,
  history: 100,
  numMixtures: 16,
  noiseSigma: 4,
  varThreshold: 0.6
};

response = monocular.background_subtractors.update(bgSubData);
curl -X PUT
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "<param-name>=<new-value>"
"https://monocular.jemsoft.io/api/background-subtractors/<ID>/"

The above command returns JSON structured like this:

{
  "label": "BackgroundSubtractor",
  "id": "id",
  "type": "MOG",
  "bgRatio": 20,
  "history": 100,
  "numMixtures": 16,
  "noiseSigma": 4,
  "varThreshold": 0.6,
  "ownerId": "ownerID",
  "createdAt": "2016-05-04T08:07:14.254Z",
  "updatedAt": "2016-05-04T08:07:14.255Z"
}

Request Parameters

Parameter Type Description
id String ID of the background subtractor to update.
parameter name type The parameter to update. (Specific to the type selected)

HTTP Request

PUT https://monocular.jemsoft.io/api/background-subtractors/<ID>

Upload and Add image

5 CREDITS

Monocular.backgroundSubtractor.addImage(id, image, options).then((response) => {

}).catch((error) {
  // Handle errors here
});
response = monocular.background_subtractors.add_image(id, image, learning_rate, encode_type)
response = monocular.background_subtractors.add_image_url(id, url, learning_rate, encode_type)
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "image=@image/path" or "url=image/url"
-F "learningRate=<learningRate>"
-F "encodeType=<encodeType>"
"https://monocular.jemsoft.io/api/background-subtractors/<ID>/add"

Adds an image to the background subtractor. Based on the learningRate parameter provided, the algorithm will either learn the image (1), not learn the image (0), or determine what to learn itself (-1).

Request Parameters

Parameter Type Description
id String ID of the background subtractor.
image Image (JPEG, PNG, BMP) The image to run add to the background subtractor.
url String The URL of the image to run add to the background subtractor.
learningRate String The rate at which the algorithm should learn the image. (Default: -1)
encodeType String The type of the foreground mask which is returned (PNG, JPEG or BMP) (Default: Original Type)

HTTP Request

POST https://monocular.jemsoft.io/api/background-subtractors/<ID>/add

Find and Add Image

5 CREDITS

Monocular.backgroundSubtractor.addImage(id, imageID, options).then((response) => {

}).catch((error) {
  // Handle errors here
});
response = monocular.background_subtractors.add_image_id(id, image_id, learning_rate, encode_type)
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
"https://monocular.jemsoft.io/api/background-subtractors/<ID>/add/<imageID>"

Adds an image to the background subtractor. Based on the learningRate parameter provided, the algorithm will either learn the image (1), not learn the image (0), or determine what to learn itself (-1).

Request Parameters

Parameter Type Description
id String ID of the background subtractor.
imageID String ID of the image to add to the background subtractor.
learningRate String The rate at which the algorithm should learn the image. (Default: -1)
encodeType String The type of the foreground mask which is returned (PNG, JPEG or BMP) (Default: Original Type)

HTTP Request

POST https://monocular.jemsoft.io/api/background-subtractor/<ID>/add/<imageID>

Detectors

Monocular allows users to create their own user trainable object detectors.

User trained object detectors are fixed-size sliding window classifiers utilizing HoG features. The algorithm works best when detecting semi-rigid objects. We’ll have other detectors, including a range of neural network based detectors, in coming releases!

Before training, depending on the object you wish to detect and images you are using, you may want to do some pre-processing.

A detector trains on a set of images from a Databucket, you must assign a Databucket to a detector for it to train on. The dataset used by the Detector is managed via the Databucket

For example:

It may be necessary to experiment with the parameters when training detectors as many of the parameters will depend on the object you wish to detect. This can easily be done within MonocularVTL.

Create Detector

Monocular.detector.create(label).then((response) => {

});
response = monocular.detectors.create(label);
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "label=Logo Detector"
"https://monocular.jemsoft.io/api/detectors/"

The above command returns JSON structured like this:

{
  "label":"Logo Detector",
  "dataBucketId":"",
  "trainingData": {
    "status": "NOT_TRAINED"
  },
  "id":"detectorID",
  "ownerId":"ownerID",
  "createdAt":"2016-07-19T03:32:53.301Z",
  "updatedAt":"2016-07-19T03:32:53.302Z"
}

Creates a new detector with the provided characteristics.

Request Parameters

Parameter Type Description
label String The name of your detector.

HTTP Request

POST https://monocular.jemsoft.io/api/detectors/

Get Detector

Monocular.detector.getDetector(detectorID).then((response) => {

}).catch((error) {
  // Handle errors here
})
response = monocular.detectors.find_one(detectorID)

# Process response here
curl -X GET
-H "Authorization: Bearer OAuthToken"
https://monocular.jemsoft.io/api/detectors/<ID>

The above command returns JSON structured like this:

{
  "label": "detector1",
  "dataBucketId":"",
  "id": "detectorID",
  "ownerId": "ownerID",
  "trainingData": {
    "status": "NOT_TRAINED|QUEUED|TRAINING|SUCCESS|FAILED"
  },
  "createdAt": "2016-05-04T08:07:14.254Z",
  "updatedAt": "2016-05-04T08:07:14.255Z"
}

Gets an individual detector.

NOTE: that this is the endpoint you must poll to determine whether or not the detector has finished training.

Request Parameters

Parameter Type Description
ID String The ID of the detector.

HTTP Request

GET https://monocular.jemsoft.io/api/detectors/<ID>

Get All Detectors

Monocular.detector.getAll().then((response) => {

}).catch((error) {
  // Handle errors here
});
response = monocular.detectors.find_all()
curl -X GET
-H "Authorization: Bearer OAuthToken"
"https://monocular.jemsoft.io/api/detectors/"

The above command returns JSON structured like this:

[
  {
    "label": "detector1",
    "id": "detectorID",
    "dataBucketId":"",
    "ownerId": "ownerID",
    "trainingData": {
      "status": "NOT_TRAINED|QUEUED|TRAINING|SUCCESS|FAILED"
    },
    "createdAt": "2016-05-04T08:07:14.254Z",
    "updatedAt": "2016-05-04T08:07:14.255Z"
  },
  {
    "label": "detector2",
    "id": "detectorID",
    "dataBucketId":"",
    "ownerId": "ownerID",
    "trainingData": {
      "status": "NOT_TRAINED|QUEUED|TRAINING|SUCCESS|FAILED"
    },
    "createdAt": "2016-05-04T08:07:14.254Z",
    "updatedAt": "2016-05-04T08:07:14.255Z"
  }
]

Gets all detectors.

HTTP Request

GET https://monocular.jemsoft.io/api/detectors/

Delete Detector

Monocular.detector.del(detectorId).then((response) => {

}).catch((error) {
  // Handle errors here
});
# Coming Soon
curl -X DELETE
-H "Authorization: Bearer OAuthToken"
"https://monocular.jemsoft.io/api/detectors/<ID>"

The above command returns JSON structured like this:

{
  "count": 1
}

Deletes a detector.

Request Parameters

Parameter Type Description
id String ID of the detector to delete.

HTTP Request

DELETE https://monocular.jemsoft.io/api/detectors/<ID>

Assigning a Databucket

var detectorData = {
  databucketId: 'databucketId'
};

Monocular.detector.update(detectorData).then((response) => {

});
response = monocular.detectors.update(detectorData);
curl -X PUT
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "databucketId=<databucketId>"
"https://monocular.jemsoft.io/api/detectors/<ID>/"

The above command returns JSON structured like this:

{
  "label":"Logo Detector",
  "dataBucketId":"databucketId",
  "trainingData": {
    "status": "NOT_TRAINED"
  },
  "id":"detectorID",
  "ownerId":"ownerID",
  "createdAt":"2016-07-19T03:32:53.301Z",
  "updatedAt":"2016-07-19T03:32:53.302Z"
}

For your detector model to train, you need to assign a databucket to the detector. The detector will train against all images in the Databucket.

You can assign a databucket to a detector with an update (PUT) request.

Note: You must retrain your detector after making changes to a Databucket, or changing the Databucket entirely.

Request Parameters

Parameter Type Description
id String ID of the detector to update.
databucketId String ID of the databucket to use.

HTTP Request

PUT https://monocular.jemsoft.io/api/detectors/<ID>

Train

20 CREDITS

Monocular.detector.train(detectorID).then((response) => {

}).catch((error) {
  // Handle errors here
});
response = monocular.detectors.train(detector_id)
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
"https://monocular.jemsoft.io/api/detectors/<ID>/train"

The above command returns JSON structured like this:

{
  "success": true,
  "status": 200,
  "msg": "Successfully queued for training."
}

Begin training the detector. The time it takes is dependent on the number of images in the training set and how many bounding boxes are in each image. This can take a significant amount of time with large data sets.

Note that this endpoint is charged once per image for all images in your training set (Databucket). For example, a detector with 50 images will charge 1,000 credits against your subscription.

Request Parameters

Parameter Type Description
id String ID of the detector to begin training.

HTTP Request

POST https://monocular.jemsoft.io/api/detectors/<ID>/train

Upload and Detect

5 CREDITS

Monocular.detector.detect(detectorID, image).then((response) => {

}).catch((error) {
  // Handle errors here
});
response = monocular.detectors.detect(detector_id, image=image)
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "image=@image/path" or "url=image/url"
"https://monocular.jemsoft.io/api/detectors/<ID>/detect"

The above command returns JSON structured like this:

[
  {
    "top": 20,
    "left": 20,
    "bottom": 120,
    "right": 120
  },
  {
    "top": 100,
    "left": 120,
    "bottom": 200,
    "right": 220
  }
]

Runs your detector on an image that is not stored on Monocular.

Request Parameters

Parameter Type Description
id String ID of the detector to begin training.
image Image (JPEG, PNG, BMP) The image to run the detector on.
url String The URL of the image to run the detectors on.

HTTP Request

POST https://monocular.jemsoft.io/api/detectors/<ID>/detect

Find and Detect

5 CREDITS

Monocular.detector.detect(detectorID, imageID).then((response) => {

}).catch((error) {
  // Handle errors here
});
response = monocular.detectors.detect(detector_id, image_id=image_id)
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
"https://monocular.jemsoft.io/api/detectors/<ID>/detect/<imageID>"

The above command returns JSON structured like this:

[
  [20, 30, 40, 50],
  [100, 120, 200, 220]
]

Runs your detector on an image that is stored on Monocular.

Request Parameters

Parameter Type Description
id String ID of the detector to begin training.
imageID String ID of the image to run the detector on.

HTTP Request

POST https://monocular.jemsoft.io/api/detectors/<ID>/detect/<imageID>

Combined Upload and Detect

5 CREDITS

Monocular.detector.detect(detectorIDs, image).then((response) => {

}).catch((error) {
  // Handle errors here
});
response = monocular.detectors.detect(detector_ids, image=image)
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "image=@image/path" or "url=image/url"
-F "detectors=["detectorID", "detectorID2"]"
"https://monocular.jemsoft.io/api/detectors/detect"

The above command returns JSON structured like this:

[
  { "id": "detectorId",
    "label": "detectorLabel",
    "success": "boolean",
    "results": [
      {
        "top": 20,
        "left": 20,
        "bottom": 120,
        "right": 120
      },
      {
        "top": 100,
        "left": 120,
        "bottom": 200,
        "right": 220
      }
    ]
  },
  { "id": "detectorId2",
    "label": "detectorLabel2",
    "success": "boolean",
    "results": [
      {
        "top": 20,
        "left": 20,
        "bottom": 120,
        "right": 120
      },
      {
        "top": 100,
        "left": 120,
        "bottom": 200,
        "right": 220
      }
    ]
  }
]

Test multiple existing detectors against a single image, uploaded in the call.

Note that this endpoint will charge the credit cost once per detector used. For example, testing an aquarium image for a combination of clownfish and anemone detectors will charge your subscription 10 credits.

Request Parameters

Parameter Type Description
detectors Array Array of IDs of detectors.
image Image (JPEG, PNG, BMP) The image to run the detectors on.
url String The URL of the image to run the detectors on.

HTTP Request

POST https://monocular.jemsoft.io/api/detectors/detect

Combined Find and Detect

5 CREDITS

Monocular.detector.detect(detectorIDs, imageId).then((response) => {

}).catch((error) {
  // Handle errors here
});
response = monocular.detectors.detect(detector_ids, image=imageId)
curl -X POST
-H "Authorization: Bearer OAuthToken"
-H "Content-Type: multipart/form-data;"
-F "detectors=["detectorID", "detectorID2"]"
"https://monocular.jemsoft.io/api/detectors/detect/<imageID>"

The above command returns JSON structured like this:

[
  { "id": "detectorId",
    "label": "detectorLabel",
    "success": "boolean",
    "results": [
      {
        "top": 20,
        "left": 20,
        "bottom": 120,
        "right": 120
      },
      {
        "top": 100,
        "left": 120,
        "bottom": 200,
        "right": 220
      }
    ]
  },
  { "id": "detectorId2",
    "label": "detectorLabel2",
    "success": "boolean",
    "results": [
      {
        "top": 20,
        "left": 20,
        "bottom": 120,
        "right": 120
      },
      {
        "top": 100,
        "left": 120,
        "bottom": 200,
        "right": 220
      }
    ]
  }
]

Test multiple existing detectors against a single image that exists in your library.

Note that this endpoint will charge the credit cost once per detector used. For example, testing an aquarium image for a combination of clownfish and anemone will charge your subscription 10 credits.

Request Parameters

Parameter Type Description
detectors Array Array of IDs of detectors.
imageID String ID of the image to run the detectors on.

HTTP Request

POST https://monocular.jemsoft.io/api/detectors/detect

Visual Training Lab

The Monocular Visual Training Lab (VTL) is an online resource which allows you to visually train your own Detectors and Face Identifiers.

You can access the VTL through the Monocular Dashboard.

Adding Images

Once you have loaded up the VTL, you will be presented with a list of the images you have uploaded. If you have not yet uploaded any images the list will be empty.

VTL Home

Begin by uploading an image by clicking the ‘Upload Image’ button or dragging it from your computer into the center box. You will then be asked to enter a label which allows you to easily filter your images.

You can upload multiple images at once, however the label you choose will be applied to every image alongside a number to keep the individual images identifiable. Note: Keep in mind that images can take some time to upload, and the larger the image the longer the upload will take.

If you upload the wrong image or you have finished with an image, hover over the image and click the red trashcan button.

VTL Upload

Data Buckets

You can create a Data Bucket to assist in organizing your data into sets. Data Buckets are also used with Detectors and Face Identification. Create a Data Bucket by entering a name and clicking the + button. If a Data Bucket is selected and you upload an image using the 'Upload’, 'Upload from Webcam’ or Drag and Drop methods, the images will be automatically added to the open Data Bucket.

VTL Data Bucket Upload

You can add an image to a Data Bucket by dragging it over the name of the Data Bucket in the list. View the contents of the Data Bucket by clicking on it, or you can see what images in the currently selected Data Bucket are also in another by hovering over it in the list.

VTL Drag Drop Bucket

You can return to the list containing all of your images by clicking 'All Data’.

If you accidentally put an image in the wrong bucket, you can remove it by hovering over the image and clicking the orange 'x’ button. This won’t delete the image from Monocular. You can delete an image from both the Data Bucket and Monocular by opening 'All Data’, hovering over the image and clicking the red trashcan button.

Preparing Your Images

If you wish to prepare an image for training, click on the first image you wish to prepare. You will be presented with a new screen which includes a full sized version of your image. This may take some time to load as the full image needs to be downloaded from the Monocular servers.

VTL Image View

To begin processing, select the Processing tab, you may wish to resize your image. The Upscale and Downscale buttons allow you to double and halve the size of your image.

We suggest for particularly large images, above 1000x1000 pixels in size, that you downscale the image. Similarly for small images, below 100x100 pixels in size we suggest that you upscale the image.

Depending on the orientation of the image, you may also want to rotate or flip your image horizontally or vertically.

The VTL allows you to interactively draw your bounding boxes directly onto the image.

To do this, begin by clicking and holding at the top left corner of the instance of the object you wish to detect in the image. Then, still holding the mouse button down, drag across the image to the bottom right corner of the object and release the mouse button.

The new bounding box will appear as a green rectangle on the image.

VTL Downscaled Image with Box

If you wish to specifically ignore a section of an image, tick the 'Ignore’ checkbox and then draw another box around the area you wish to ignore. Ignored checkboxes are used when there is something you want to explicitly skip in training. This is different to 'negative’ data which is everything that is not surrounded by a bounding box or ignored bounding box and tells the Detector what should be counted as the background or 'not the target’ of the Detector. An example if where you might use ignored bounding boxes could be if there was a slightly rotated version of the object which you don’t want the Detector to count as negative data.

You can edit any bounding box value should you make a mistake by clicking the number in the list of bounding boxes, changing the number and clicking the green checkbox. Alternatively if you wish to remove a checkbox click the red trashcan button. It’s good to note that the trashcan button at the top of the list will delete all bounding boxes.

Click 'Save and Close’ to stop editing the image, or click 'Undo Changes’ to remove your changes and return to the list of images.

Data Bucket Processing

Similarly to how you can process individual images, you can also process whole Data Buckets. On the Images page, when a Data Bucket is selected, click 'View Processing Options’. This will open a list of processing options that can be applied to the Data Bucket. The time it takes to process a whole Data Bucket depends on the images it contains, as a result the Data Bucket and the images will be locked during processing.

VTL Bucket Processing

Building a Detector

To begin making a Detector, click on the 'Detection’ tab at the top of the VTL. Type a name for your Detector in the space provided and click 'Create’.

Your new Detector will appear in the list below.

VTL Detector List

Click on the arrow to open the information panel for your Detector.

In this panel you can select a Data Bucket to use to train the Detector. Select one from the drop down list which contains your annotated data and click 'Train’ to begin training your Detector. You can see the current state of all of your Detectors in the list at a glance.

VTL Detector Open

Once your Detector has finished training, the green status bar will update to say 'Trained Successfully’.

At this point you can click 'Test’.

Testing a Detector

The VTL allows you to test your Detector, once it has been trained. It is important to test your Detector to ensure that the Detector is performing as expected. Once you have clicked 'Test Detector’, you will see a list of images and white output area.

VTL Testing Detector

To test your Detector on an image you have already uploaded, hover over the image and click the purple 'Test’ button. The image will appear in the output area, and if your Detector was successful in finding an object, a cyan coloured rectangle will be drawn around the object.

VTL Testing Detector

You can also test your Detector on a new image by dragging it from your computer into the output area or clicking 'Upload Image’. You can also use the camera button to run the Detector on a picture taken from your webcam. The image will appear in the output area with a cyan rectangle around any object that was detected. This doesn’t permanently upload the image to Monocular so you can test on any image you want without cluttering your data.

If after testing your Detector you find that it your Detector needs improvement, adding more images with relevant bounding boxes and clicking 'Retrain Detector’ may improve your results.

Using a Trained Detector

let detectorId;
let myDetectorLabel = 'Object Detector'
Monocular.detector.getAll().then((response) => {
  for (index in response) {
    if (response[index].label === myDetectorLabel) {
      detectorId = response[index].id;
    }
  }
}).catch((err) => {
    // Catch Error
});

Once you are happy with the performance of your Detector you should begin using it outside of the Virtual Training Lab. For this, you should build an application using one of our SDKs.

A good starting point may be the Face Finder with some small adjustments.

You can get a list of your Detectors from Monocular using the code on the right panel, and identify the Detector you wish to use by matching it to its label.





function detect(image) {
  Monocular.detector.detect(image).then((detections) => {
    resultElement.text('Detected ' + detections.length + ' ojects(s)');
    detections.forEach(object => crop(image, object));
  }).catch((err) => {
    resultElement.text('Something went wrong! Is that an image?');
  });
}

Once you have your Detector ID, modify the detect() method as shown to the right. Monocular.detectors.detect() is used with a Detector ID and an image and returns a list of object locations, see Upload and Detect.

All done! Now your application produces a list of cropped objects that your Detector has detected.

Building a Face Identifier

The VTL also provides support for training and testing your own Face Identifier.

Before you create Face Identifier we recommend preparing your data. Face Identifiers require at least two 'Faces’ which consist of a Data Bucket containing images and a label. It is essential that all of the images contain at least one face otherwise the training will fail. If you are unsure if we will find the face in the image, simply open the image and click 'Detect Faces’. If a bounding box appears around the face then you can be confident that the image is valid. For the best results, ensure that all of the images in each Data Bucket are of a single person and that you have at least 20 faces total across the Data Bucket. Use the crop tool to reduce the image to only the desired face if this is not the case.

To begin, select the Face Identification tab, create a new Face Identifier and open the information panel using the grey arrow button; the same as you would in the Detector list.

VTL Face Identifiers

Begin by selecting a bucket using the drop down box in the information panel. You may have noticed that we automatically filled in the label for you. If you would like to call the Face something different, simply change it to your desired label. Add the Face by clicking 'Add Face’. Once you have added at least two Faces, click train.

Similar to Detectors, Face Identifiers can take some time to train, however you can monitor the current status through the VTL. Once the Face Identifier is trained, the status will update to say 'Trained Successfully’.

VTL Face Identifier Trained

At this point you should test your identifier.

Testing a Face Identifier

Testing a Face Identifier is very similar to testing a Detector. You can test existing images by hovering over them an clicking 'Test’. You can also upload a new image by clicking 'Upload’ or dragging and dropping the image into the panel below it. You can also test on an image from your webcam using the camera button.

VTL Test Identifier

There is one key factor in testing an identifier and that is the 'confidence’. The Face Identifier returns a box for each face that it finds in the image, and includes a label and confidence. These labels match up to the labels of the Faces provided earlier and the confidence value tells you how confident the Face Identifier is that the label it has assigned is correct. The lower the confidence score, the more confident the algorithm is. A confidence score of zero (0) suggests that the image was used to train the Face Identifier and that it is 100% confident the image is the correct tag. The upper bound of the confidence value is arbitrary meaning that there is no hard limit, as such it may be worth testing on a face that doesn’t match any face it was trained on to get an approximate upper bound. You can then test using faces which the identifier should be confident of and see if you get better results.

VTL Test Identifier VTL Test Identifier

You can see above that the confidence scores vary greatly however the algorithm correctly identified each face. Another way of testing your results may be to test it on multiple faces in the same image. You can use the provided slider to change the threshold of what results are shown based on their confidence. Using this you can filter out the faces that the algorithm is least confident of (higher confidence values).

Tutorials

Face Finder Tutorial

This tutorial shows you how to create a simple web app that extracts human faces from an image using Monocular API.

You can access this tutorial on github here.

You can try the live version of the app here.

Python Face Detection Script

The app uses Monocular Python SDK and one of the Monocular API endpoints. We are going to use the endpoint Face Detection and the Python Pillow module to create an app which detects faces in an image and plots their locations visually over the image.

You can access this tutorial on github here.

Appendices

Bounding Boxes

Bounding Boxes should be formatted as follows:

[
  {
    "top": 200,
    "left": 200,
    "bottom": 320,
    "right": 340
  },
  {
    "top": 400,
    "left": 410,
    "bottom": 520,
    "right": 500
  }
]

Bounding boxes define a rectangle which provides metadata regarding an image.

When storing bounding boxes or ignored bounding boxes with an image, the boxes should always match this format otherwise detectors may fail to train correctly with those bounding boxes.

Landmarks

The following diagram shows 68 facial landmarks and approximately where they align to on a face: Landmarks of the Face

Errors

The Monocular API uses the following error codes:

Error Code Meaning
400 Bad Request – The request was invalid.
401 Unauthorized – You are not authorized to access this resource (your App ID, Secret or Token may be incorrect).
403 Forbidden – This endpoint is only accessible by administrators.
404 Not Found – The specified target could not be found.
406 Not Acceptable – You requested a format that isn’t JSON.
422 Unprocessable Entity – One or more parameters in your request are not processable.
423 Resource Locked – Another process is working on this resource right now.
429 Too Many Requests – You’re requesting too many kittens! Slow down!

If you persistently receive errors, or have received an error code when you believe you shouldn’t, have a look at the request and find your Support code. Email us at support@jemsoft.co with your Support code and some details on what you’re trying to do, and we will be happy to help out.