Bmetry solutions provide an API in order to facilitate 3rd-party automation of image delivery. It is in development and will be extended in the future, but these endpoints should remain mostly stable.
Core concepts
There are a few key concepts that should be understood in order to use the API effectively.
Bmetry solution
A bmetry solution is a solution of 2 coupled cameras mounted on a crane intended for spectroscopic imaging of a construction site. A solution can function with only 1 or more than 2 cameras, though that is highly unusual.
Bmetry remote
A camera controller in a bmetry solution is called a remote. Thus, a bmetry solution usually has 2 remotes. Remotes in a Bmetry-solution are identified by their serial numbers, which is identical to the username that you enter for a camera when configuring it in the portal (for example 240116-5).
Remotes of a bmetry-solution must have the Tethering Mode peripheral to function properly.
Bmetry master
The master of a bmetry solution is the camera through which configuration and access are managed. The camera controller of a master is itself a normal remote. The master is really more of an organisational tool than it is a technical distinction. The master is identified by its portal code (for example, E240102), that is, the primary identifier under which it is listed in the portal.
Bmetry masters must have the Bmetry peripheral to be recognised as such. All configuration of the system can be handled on the configuration page of the master. The masters controller is automatically a remote and does not need specific configuration.
ImageSequence
A Bmetry image sequence is a collection of image metadata that bundles together images that were captured during a run of the crane. A valid sequence should contain an image set that can be combined to a spectroscopic image, though it may contain more images than are strictly required.
Image sequences contain an ID, a start time, an end time, a result, and the remotes that captured the images in the sequence, like so:
{
"id":"2605684670271962334",
"remotes":["230726-13","220715-05"],
"start":"20240117T122423.156Z",
"end":"20240117T122503.091Z",
"state":"VALID"
}
ImageInfo
Bmetry image info is a short set of metadata describing an image that was captured in a sequence and is stored on the camera. This is important to realise: The image ID in the image info has no relation to the name and timestamp of an image in the portal. It is used to identify and retrieve a specific image directly from the camera.
The image info further consists of a timestamp that is accurate to within about 0.3 seconds (a more accurate timestamp will be contained in the exif data of the actual image), as well as a counter for how many times it has been uploaded. It will usually be delivered associated to the serial number of the remote that captured it, in a structure like this:
{
"first": "<serial-of-remote>",
"second": [
{
"time": "20240117T122442.322Z",
"imageId": "/store_00020001/DCIM/100CANON/IMG_7528.JPG",
"uploadCount": 1
},
{
"time": "20240117T122443.487Z",
"imageId": "/store_00020001/DCIM/100CANON/IMG_7529.JPG",
"uploadCount": 1
},
]
}
Also, do note that all images are purged from a camera around midnight in the cameras configured timezone.
API
In general there’s two types of endpoints in the API: One type is used to get information, the other is used to order the upload of images.
In general, for any of these endpoints you will need an HTTP client (such as for example curl), and you will need a user of at least power user level that has permissions for the master of the solution you want to send requests to. You can use HTTP basic-auth to authenticate.
Base URL
The base url for all requests is:
https://api.yellow.camera/bmetry/
Data requests (GET)
Read all available sequences that a given solution has captured since last purge
path: sequence/all/{code}
{code}: Portal code of the master of the solution.
request body: None
response body: ImageInfos mapped to their respective remotes.
[
{
"id": "string",
"remotes": ["string"],
"start": "20240117T122423.156Z",
"end": "20240117T122503.091Z",
"state": "string"
}
]
Read metadata on all images in a given sequence
path: sequence/{sequenceId}/images/{code}
{sequenceId}: ID of the sequence to retrieve the ImageInfo of.
{code}: Portal code of the master of the solution.
request body: None
response body: A list of
200 OK
[
{
"first": "string",
"second": [
{
"imageId": "string",
"time": "2024-01-17T16:02:28.582Z",
"uploadCount": 0
}
]
}
]
Retrieve metadata on all images captured by a solution in a given timespan
path: image/{code}/{since}/{until}
{code}: Portal code of the master of the solution.
{since}: Start time of the retrieval window, ISO 8601 standard (e.g. 2024-01-17T15:48:45.580). Will be interpreted as UTC.
{until}: End time of the retrieval window, ISO 8601 standard. Will be interpreted as UTC.
request body: None
response body: ImageInfos mapped to their respective remotes.
200 OK
[
{
"first": "string",
"second": [
{
"imageId": "string",
"time": "2024-01-17T15:48:45.580Z",
"uploadCount": 0
}
]
}
]
Upload requests (POST)
Request upload of all images in a specific sequence
path: sequence/{sequenceId}/upload/{code}/{maxUploadCount}
{sequenceId}: ID of the sequence to upload.
{code}: Code of the master of the solution that captured the sequence.
{maxUploadCount}: Images that were already uploaded more times than this number will be excluded. Pass -1 to upload all.
request body: None
response body: Returns a list of images that will be uploaded.
202 ACCEPTED
[
{
"first": "string",
"second": [
{
"imageId": "string",
"time": "2024-01-17T16:22:40.502Z",
"uploadCount": 0
}
]
}
]
Request upload of all images captured by a solution in a given timespan
path: image/upload/{code}/{since}/{until}/{maxUploadCount}
{code}: Portal code of the master of the solution that should upload images.
{since}: Start time of the retrieval window, ISO 8601 standard (e.g. 2024-01-17T15:48:45.580). Will be interpreted as UTC.
{until}: End time of the retrieval window, ISO 8601 standard. Will be interpreted as UTC.
{maxUploadCount}: Images that were already uploaded more times than this number will be excluded. Pass -1 to upload all.
request body: None
response body: Returns a list of images that will be uploaded.
202 ACCEPTED
[
{
"first": "string",
"second": [
{
"imageId": "string",
"time": "2024-01-17T16:22:40.502Z",
"uploadCount": 0
}
]
}
]
Request upload of an arbitrary set of images from a solution
path: /bmetry/image/upload/{code}
{code}: Code of the master of the solution that captured the images.
request body: List of the image ids to upload, mapped to the serials of the remote that captured them:
[
{
"first": "<remote-serial>",
"second": [
"<image-id>",
"<image-id>",
...
]
}
]
response body: None
202 ACCEPTED
Add Comment