Bmetry solutions provide a frontend configuration for managing the running of sequences and delivery destination of the images. They also 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:
| Code Block |
|---|
{
"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:
| Code Block |
|---|
{
"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:
| Code Block |
|---|
{
"first": "<serial-of-remote>",
"second": [
{
"altitude": number,
"imageId": "string",
"lat": number,
"lon": number,
"time": "2024-05-14T14:11:16.839Z",
"uploadCount": number
},
.
.
.
]
} |
...
To familiarize yourself with the core concepts bmetry solutions are built on, please read the first chapter in the API documentation:
https://avisec.atlassian.net/wiki/x/AYDVtw
Configuration
The images sent by a bmetry solution take another path than images sent by other cameras. Bmetry images are not visible in the portal, as the content of individual images is rarely of interest. As such, the browse page of a bmetry camera will be empty, but you can still use it to configure your solution by clicking on the configure menu option:
We are working on replacing the empty browse page with a data summary for a quick overview over what the solution has been doing and what images are available, but at this point in time you will need to query the API to get that information.
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:
...
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 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.
Automatic upload: If active, all available images in a sequence from all remotes will immediately be uploaded once a sequence is finished. If you deactivate this, no images will be uploaded by default. They will remain on the camera until an upload command is sent through API. This is intended to provide an interface for upload autmation and pre-filtering of images and is the recommended way to manage uploads from bmetry solutions. However, if you have no automation in place, activating this option will serve as a (often wasteful) substitute.
Attention! Cameras will clean themselves and delete all stored images after midnight. If you do not upload your images, they will be gone the next day!
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 the 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:
| Code Block |
|---|
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.
| Code Block |
|---|
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.
| Code Block |
|---|
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.
| Code Block |
|---|
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
...
{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.
| Code Block |
|---|
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
...
{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.
| Code Block |
|---|
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.
| Code Block |
|---|
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.
| Code Block |
|---|
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:
| Code Block |
|---|
[
{
"first": "<remote-serial>",
"second": [
"<image-id>",
"<image-id>",
...
]
}
] |
response body: None
...
Endpoint configuration
As bmetry images are routed differently and never go through the usual post-processing steps as other images do, configuring a forwarding endpoint in a table configuration has no effect. Instead, you need to configure the endpoint you want the images forwarded to for processing here. If you do not configure an endpoint here, you will not receive any images!
Endpoint configuration otherwise is very similar as it is for table configurations:
Enabled: Use this checkbox to enable or disable the endpoint.
You can forward to either an FTP server, or to an AWS S3 bucket under your control. Do not configure both. If you do, the FTP server takes priority, the S3 bucket will receive nothing.
FTP configuration
Host: The fully qualified domain name of your FTP server.
Port: The port to send the request to. 21 by default, change if your server expects communication on another port.
User and Password: Credentials to log into the FTP server for the file transfer.
S3 configuration
Bucket: Name of the bucket to send to.
Key and Secret: Access key and Secret key of an AWS user that has putObject permission for the bucket.
Common configuration
These fields affect both FTP and S3 uploads the same:
Server folder: A subfolder to write to. In case of an FTP server, the user will need permission for that folder. In case of an S3 bucket, this value will be prepended to the object key with a /.
Filename: The filename (ftp) or object key (S3) the image will be uploaded as. You can name this whatever you like, but you should always include the template variable {T} which will be replaced with the images' timestamp. This is important as otherwise all images will be uploaded with the same name and will overwrite each other.
Time format: You can choose a format for the timestamp as it will be inserted into the filename. These include milliseconds, as for some bmetry-solutions a resolution of one second may not be enough. Choose whatever time format suits you best.
API Documentation
The API documentation has moved here: https://avisec.atlassian.net/wiki/x/AYDVtw