Bmetry API documentation

A small subset of API functionality is available through the portal UI. Read here for more information on that: https://avisec.atlassian.net/wiki/x/D4Cuuw

It is still recommended to read through at least the core concepts here, so you get an idea of how things work.

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:

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.

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.

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.

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.

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.

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.

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.

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:

response body: None