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 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
},
.
.
.
]
}
Configuration
Most properties of a bmetry solution must be configured through the master. To make a camera the master of a solution, activate the bmetry peripheral in its peripheral configuration:
This peripheral must be configured in addition to the webcam controller, and the tethering mode. The tethering mode must be activated for every remote in a bmetry solution, no matter whether they are a master or not.
Once the peripherals are configured for all cameras that should form the solution, you can configure the solution properties in the configuration page of the master (the camera that has the bmetry peripheral activated):
Capture duration: The length of the sequence to capture, in seconds. This serves as a timeout for the entire capture operation after cameras are tethered and ready.
Capture frequency: How many times per second the cameras in the solution should capture an image. Currently this is the same setting for the entire solution, without distinguishing individual remotes.
Capture control: If set to start on motion, cameras will only start capturing once they detect motion in the crane. In this case, capture duration serves as a timeout. If set to start on command, cameras will start to capture as soon as they are ready and do so until capture duration is up.
Remotes: Here you can configure the remotes belonging to a solution. Just enabling tethered mode for all remotes is not enough, you need to group them together to a solution here, otherwise they don’t know who may talk to whom. The identifier for the remote is the serial number of its camera controller, which is the same thing you use as a username in portal:
The serial of the master is added implicitly and does not need to be configured.
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
Add Comment