Middleware

Table of Contents

The middleware is the software component on the rig that is responsible for managing missions, coverage, etc. Essentially, the middleware is what makes UFS specific to aerial inspections.

During the planning stage, a mission file is created. This file contains all the information required to take the plane out and capture data. It contains the list of sites that need to be scanned and their geometry, list of contacts and other notes that might be relevant. This mission file is the first input to the middleware.

The middleware also allows the generation of flight lines, lines which will guide the pilot when flying, insuring the field of view of the camera correctly captures the site we are interested in.

REST API

GET /mw

This endpoint serves a very elementary HTML page that allows the most basic file upload. This is meant strictly as a testing facility.

POST /mw/upload & /mw/upload_json

This endpoint allows the user to upload a new mission to the middleware

Query parameters:

  • allow_delete
    • Type: boolean
    • Description: Without this flag, the upload and parsing process will never remove information from the database, setting the flag to true will allow the parser to remove sites from the database if they are removed from the mission file.
    • Optional: yes

Body: A file, either a legacy mission XML to the /mw/upload endpoint, or a flight group JSON file to the /mw/upload_json endpoint.

Return body: Mission created object

{
  "name": "",
  "uuid": ""
}

Notes:

  • This can be a new or an existing mission. Upon upload the file is validated against the schema then parsed. The attempts and associated metadata are stored in a database for future examination and retrieval. If a mission is already known, the database will be updated with the information contained in the file.
  • Uploading a file that does not list all the attempts known in the database without the allow_delete flag will return status code 409 Conflict to indicate the mismatch of deleted data and missing flag. In that case, the data in the file will be added/updated in the database but nothing will be deleted.

GET /mw/missions

This endpoint fetches the list of mission uploaded to the middleware in the past.

Return body: List of missions known.

[
  {
    "name": "",
    "uuid": ""
  }
]

GET /mw/missions/{mission_uuid}

This endpoint fetches the details of a specific mission.

Path parameters:

  • {mission_uuid}
    • Type: string
    • Description: UUID string of the mission.
    • Optional: no

Return body: Json object with the details of the mission

{
  "name": "",
  "uuid": "",
  "last_modified": "timestamp"
}

DELETE /mw/missions/{mission_uuid}

This endpoint deletes a mission from the database.

Path parameters:

  • {mission_uuid}
    • Type: string
    • Description: UUID string of the mission to delete.
    • Optional: no

Return body: None

Notes: All data associated with this mission will be removed from the database. This includes attempts, captures, telemetry, coverage, images, everything!

GET /mw/missions/{mission_uuid}/download

This endpoint downloads the latest description of a specific mission.

Path parameters:

  • {mission_uuid}
    • Type: string
    • Description: UUID string of the mission.
    • Optional: no

Return body: The XML file that was last uploaded for this particular mission.

POST /mw/load{mission_uuid}

This endpoint loads a mission without having to upload a file. The mission uuid given in the request should exist in the database prior to the call. Error code 404 will be returned otherwise.

Path parameters:

  • {mission_uuid}
    • Type: string
    • Description: UUID string of the mission uuid to load.
    • Optional: no

Return body: None

GET /mw/attempt_requests/{mission_uuid}

This endpoint will return the list of attempts associated with the mission selected. Additionally, requesting the details of a mission with this endpoint will cause this mission to be selected as the active mission. This will cause the zmq publisher to relay this mission selection to the telemetry processor.

Path parameters:

  • {mission_uuid}
    • Type: string
    • Description: UUID string of the mission uuid for which to fetch the attempt requests. If no UUID is provided, all requests are returned, regardless of the mission they are associated with.
    • Optional: yes

Return body: Array of objects representing the various attempts

[
  {
    "contacts": [
      {
        "email": "",
        "name": "",
        "phone": ""
      }
    ],
    "elevation": "",
    "estimatedTime": "",
    "geometry": {
      geo_json_object
    },
    "name": "",
    "notes": [
      ""
    ],
    "requiredScanAltitude": "",
    "uuid": ""
  }
]

GET /mw/coverage/{attempt_uuid}

Get the area of a site that has been covered by the capture software so far during the attempt.

Path parameters:

  • {attempt_uuid}
    • Type: string
    • Description: the UUID of the attempt for which to fetch the coverage.
    • Optional: no

Query parameters:

  • review_status
    • Type: enum (string)
    • Values: unreviewed, approved, rejected
    • Description: compute the coverage by selecting only images that have been marked as a specific review status.
    • Optional: yes
  • spectrum
    • Type: string
    • Values: ir, rbg
    • Description: get coverage of images in the specific spectrum.
    • Default: 'ir'
    • Optional: yes

Return body: GeoJson object representing the geometry covered.

Notes: Coverage is estimated based on the telemetry received and the site geometry provided in the mission file, specifically the site elevation. The field of view of the cameras is projected onto that surface, and summed over time to build a unified geometry that represents the entire region covered under that attempt.

GET /mw/missing_coverage/{attempt_uuid}

Similar to get coverage but returns the region of a site that has not been covered by that attempt.

Path parameters:

  • {attempt_uuid}
    • Type: string
    • Description: the UUID of the attempt for which to fetch the coverage.
    • Optional: no

Query parameters:

  • review_status
    • Type: enum (string)
    • Values: unreviewed, approved, rejected
    • Description: compute the coverage by selecting only images that have been marked as a specific review status.
    • Optional: yes
  • spectrum
    • Type: string
    • Values: ir, rbg
    • Description: get coverage of images in the specific spectrum.
    • Default: 'ir'
    • Optional: yes

Return body: GeoJson object representing the geometry not covered during the attempt.

Notes: This value is basically site_geometry - coverage

GET /mw/flight_lines/{attempt_uuid}

Generate the flight lines to cover the region that is not covered by an attempt thus far.

Query parameters:

  • heading

    • Type: Double
    • Description: Which heading should the lines be oriented towards
    • Optional: yes
    • Default value: 180

  • altitude

    • Type: Double
    • Description: Altitude above the site at which you want to fly in feet
    • Optional: yes
    • Default value: 2000

  • pitch

    • Type: Double
    • Description: Angle off the vertical at which the camera is pointing
    • Optional: yes
    • Default value: 32

  • buildup

    • Type: Double
    • Description: Length of the approach line to generate before covering the site
    • Optional: yes
    • Default value: 1.0

  • overlap

    • Type: Double
    • Description: Percentage of the field of view that should overlap between two flight lines
    • Optional: yes
    • Default value: 0.40

  • side

    • Type: string
    • Description: Which side of the place is the camera mounted on. Can be left or right
    • Optional: yes
    • Default value: right

  • lens_angle

    • Type: Double
    • Description:
    • Optional: yes
    • Default value: 10.7

  • review_status

    • Type: enum (string)
    • Values: unreviewed, approved, rejected
    • Description: compute the missing coverage by selecting only images that have been marked as a specific review status.
    • Optional: yes

Path parameters:

  • {attempt_uuid}
    • Type: string
    • Description: the UUID of the attempt for which to generate the flight lines. If UUID is missing, this will return the last set of lines generated.
    • Optional: yes

Return body: GeoJson object representing the lines to fly.

Notes:

  • The algorithm starts by computing the missing coverage for an attempt. Then based on the flight parameters provided, it generates a list of lines that will place the field of view of the camera over the site assuming a straight and level flight.
  • Repeated calls may yield different results as the site gets scanned and coverage changes.

GET /mw/loaded_mission

Get the UUID of the mission currently loaded. A mission is loaded when calling the GET /attempt_requests/{mission_uuid}.

PUT /cache

This is a raw buffer where the web application can store a JSON object to be passed between instances of the user interface. The main use case for this is passing data from the operator UI to the pilot UI. Data stored in the cache can be retrieved using the GET method.

Body: A JSON object to be stored.

GET /cache

This is the retrival method for data stored using the PUT method.

Return body: The content of the cache with content_type: application/json headers.