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 to the solution are managed. The camera controller of a master is itself a normal remote. The master is really more of an abstract 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, except for the peripheral configuration of the remotes. 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.
GeoImageInfo
GeoImageInfo is an extension of ImageInfo. Like Image info, it is used to identify an image on the camera, but it also contains gps coordinates for that image. GeoImageInfo is not necessarily available for all images in a sequence. If interpolation is deactivated in the configuration, only the images taken by the master have gps data associated with them, and in case of a sensor failure, it may be that only some images in a sequence have coordinates available, or none at all.
GeoImageInfo has the following structure:
{
"first": "<serial-of-remote>",
"second": [
{
"altitude": number,
"imageId": "string",
"lat": number,
"lon": number,
"time": "2024-05-14T14:11:16.839Z",
"uploadCount": number
},
.
.
.
]
}
API Documentation
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.
200 OK
[
{
"id": "string",
"remotes": ["string"],
"start": "20240117T122423.156Z",
"end": "20240117T122503.091Z",
"state": "string" // EXPERIMENTAL! Shows either VALID or INVALID. Currently, a valid sequence has consists of at least 70% of the expected images, and has no more than 10% of its images missing at the end (per remote).
}
]
Read image info of 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: Contains info of all images in the relevant sequence, mapped to their remote.
200 OK
[
{
"first": "string",
"second": [
{
"imageId": "string",
"time": "2024-01-17T16:02:28.582Z",
"uploadCount": 0
}
]
}
]
Read geo image info of all images in a given sequence
path: sequence/{sequenceId}/geoimages/{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: Contains only the images of the sequence with geocoordinate available.
200 OK
[
{
"first": "string",
"second": [
{
"altitude": 0,
"imageId": "string",
"lat": 0,
"lon": 0,
"time": "2024-05-14T14:11:16.839Z",
"uploadCount": 0
}
]
}
]
Retrieve image info 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
}
]
}
]
Retrieve geo image info of all images captured by a solution in a given timespan
path: geoimage/{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: Contains only the images that have geocoordinates available.
200 OK
[
{
"first": "string",
"second": [
{
"altitude": 0,
"imageId": "string",
"lat": 0,
"lon": 0,
"time": "2024-05-14T14:11:16.839Z",
"uploadCount": 0
}
]
}
]
Upload requests (POST)
Request upload of all images in a specific sequence
path: sequence/{sequenceId}/upload/{code}/{maxUploadCount}
optional path extension: /{imageWidth}
{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.
{imageWidth}: An optional parameter specifying image width in pixel. If provided, all images will be scaled to this width (preserving aspect ratio) prior to upload. Intended to be used for prototype mappings of images before a final upload request.
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}
optional path extension: /{imageWidth}
{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.
{imageWidth}: An optional parameter specifying image width in pixel. If provided, all images will be scaled to this width (preserving aspect ratio) prior to upload. Intended to be used for prototype mappings of images before a final upload request.
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}
optional path extension: /{imageWidth}
{code}: Code of the master of the solution that captured the images.
{imageWidth}: An optional parameter specifying image width in pixel. If provided, all images will be scaled to this width (preserving aspect ratio) prior to upload. Intended to be used for prototype mappings of images before a final upload request.
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
0 Comments