Overview
You may be required to use images as input for analysis, display them as evidence, or automate the collection of live video images; for these and other similar cases, the Arcules web application provides the option to retrieve a thumbnail image on a live stream through its API.
Prerequisites
Cameras added to the Arcules Camera-to-Cloud ("C2C") architecture must be online and connected to the internet.
Cameras added to an Arcules Gateway must be online (Gateway must have internet access as well).
Users must have the API User Role assigned in the portal.
How to
Use the /login API service to request a JWT token (the JWT token will be used in the subsequent calls of the API).
Obtain the identifier of the specific channel in the camera for which you wish to capture the thumbnail image. You can obtain the identifier of the channel (called channelId) from two sources:
Using the /devices endpoint from the Arcules API.
The Arcules Platform: Go to the Devices section, select the specific device, then go to the URL and copy the identifier that appears after the "selected=" parameter:
In the image above, the identifier is 69eb770a-269d-4dec-9c68-0a55a156723e
Use the /thumbnail/{channelId}/live service to request a live image of that channel.
/thumbnail/69eb770a-269d-4dec-9c68-0a55a156723e/live
In response, you will get the thumbnail image in binary format (format is always JPEG).
Note: Image quality is based on the camera's recording resolution settings.
Complete Example
In the steps below, a US dollar sign $ is used to denote a terminal prompt with a command following it. Lines without a leading $ indicate output from the terminal. Output containing an ellipsis ... indicates truncation. Actual output will be much longer.
First Step
Log in using email and password.
Expected output: Either an error message or a JWT token in JSON format.
$> curl -X POST "https://msapi.arcules.com/v1/login" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"email\":\"EMAIL_GOES_HERE@EMAIL_GOES_HERE.COM\",\"password\":\"PASSWORD_GOES_HERE\"}"
{"jwtToken":"eyJhbGciOi..."}
Second Step
Saving a JWT token to an environment variable for later use (e.g.: in a script).
This step assumes that the value returned by the curl command is indeed a valid JWT token.
Note: Production code should perform error checking here (omitted for brevity).
$> JWT_TOKEN=`curl -X POST "https://msapi.arcules.com/v1/login" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"email\":\"EMAIL_GOES_HERE@EMAIL_GOES_HERE.COM\",\"password\":\"PASSWORD_GOES_HERE\"}" 2>/dev/null`
$> JWT_TOKEN=${JWT_TOKEN:13:-2}
Third Step
Obtaining all devices for your organization.
This step assumes that the environment variable JWT_TOKEN contains a valid JWT token (see second step).
Expected output: Either an error message or a list of devices and pagination cursors in JSON format.
$> curl -X GET "https://msapi.arcules.com/v1/devices" -H "accept: application/json" -H 'Authorization: Bearer '$JWT_TOKEN
{"devices":[{"id":"ID_GOES_HERE","name":"NAME_GOES_HERE","type":"TYPE_GOES_HERE","locationId":"LOCATION_ID_GOES_HERE","gatewayId":"GATEWAY_ID_GOES_HERE"}],"page":{"previous":null,"current":"","next":null}}
Fourth Step
Saving a JPEG thumbnail from a channel.
This step assumes that the environment variable JWT_TOKEN contains a valid JWT token (see second step).
This step further assumes that the environment variable CHANNEL_ID contains the ID from a device with type video (see third step).
Expected output: Either an error message or a valid JPEG image.
Note: Production code should perform error checking here (omitted for brevity).
$> curl -X GET 'https://msapi.arcules.com/v1/thumbnail/'$CHANNEL_ID'/live' -H 'accept: image/jpeg' -H 'Authorization: Bearer '$JWT_TOKEN --output OUTPUT_FILE_NAME.jpg 2>/dev/null
More information about the Arcules API can be found here.