Photo Shooting

Photo Shooting Protocol

The communication protocol for photo shooting describes the format of a request for a photo shoot (also referred to as need) sent by a user, and the response (bid) sent by the photographer (can be a human controlled device or an autonomous one).

For example, an insurance company that wants to estimate the damage caused to a building's windows by a hail storm, might search for photo-shooting drones that can take HD photos at 80 meters high.

Need

curl "discovery_endpoint_here" \
  --data "{ \
    \"start_at\": \"1513005534000\", \
    \"end_at\": \"1513008000000\", \
    \"object_latitude\": \"32.787793\", \
    \"object_longitude\": \"-79.935005\", \
    \"object_altitude\": \"80\", \
    \"azimuth_angle\": \"15\", \
    \"elevation_angle\": \"-20\", \
    \"distance\": \"30\", \
    \"min_resolution\": \"1366,768\" \
  }"

const discoveryEndPoint = 'discovery_endpoint_here';

fetch(discoveryEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    start_at: '1513005534000',
    end_at: '1513008000000',
    object_latitude: '32.787793',
    object_longitude: '-79.935005',
    object_altitude: '80',
    azimuth_angle: '15',
    elevation_angle: '-20',
    distance: '30',
    min_resolution: '1366,768',
  }),
});

import requests
payload = {
    "start_at": "1513005534000",
    "end_at": "1513008000000",
    "object_latitude": "32.787793",
    "object_longitude": "-79.935005",
    "object_altitude": "80",
    "azimuth_angle": "15",
    "elevation_angle": "-20",
    "distance": "30",
    "min_resolution": "1366,768",
  }
requests.post("discovery_endpoint_here", data=payload)

In response, a drone owner might send back a bid with the drone type and model, the camera model, and the price for this task.

Bid

curl "bidding_endpoint_here" \
  --data "{ \
    \"need_id\": \"ae7bd8f67f3089c\", \
    \"expires_at\": \"1513005539000\", \
    \"price\": \"20000000000000000,4000000000000000\", \
    \"price_type\": \"flat,flat\", \
    \"price_description\": \"Total price,VAT\", \
    \"eta\": \"1513005534000\", \
    \"camera_model\": \"ZENMUSE X5S\", \
    \"photo_resolution\": \"2720,1530\", \
    \"camera_operator\": \"controlled_drone\", \
    \"operator_model\": \"DJI Matrice 210\" \
  }"

const biddingEndPoint = 'bidding_endpoint_here';

fetch(biddingEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    need_id: 'ae7bd8f67f3089c',
    expires_at: '1513005539000',
    price: '20000000000000000,4000000000000000',
    price_type: 'flat,flat',
    price_description: 'Total price,VAT',
    eta: '1513005534000',
    camera_model: 'ZENMUSE X5S',
    photo_resolution: '2720,1530',
    camera_operator: 'controlled_drone',
    operator_model: 'DJI Matrice 210',
  }),
});

import requests
payload = {
    "need_id": "ae7bd8f67f3089c",
    "expires_at": "1513005539000",
    "price": "20000000000000000,4000000000000000",
    "price_type": "flat,flat",
    "price_description": "Total price,VAT",
    "eta": "1513005534000",
    "camera_model": "ZENMUSE X5S",
    "photo_resolution": "2720,1530",
    "camera_operator": "controlled_drone",
    "operator_model": "DJI Matrice 210",
  }
requests.post("bidding_endpoint_here", data=payload)

Need

A statement of need for a photo shoot. Typically this will be sent by a user that is looking to photograph a certain object.

This request is sent to the decentralized discovery engine which responds with status 200 and a unique identifier for this request. The details of this request are then broadcasted to DAV entities that can provide this service. Bids are later received as separate calls.

Arguments

Post request to a local/remote discovery endpoint

curl "discovery_endpoint_here" \
  --data "{ \
    \"start_at\": \"1513005534000\", \
    \"end_at\": \"1513008000000\", \
    \"object_latitude\": \"32.787793\", \
    \"object_longitude\": \"-79.935005\", \
    \"object_altitude\": \"80\", \
    \"azimuth_angle\": \"15\", \
    \"elevation_angle\": \"-20\", \
    \"distance\": \"30\", \
    \"min_resolution\": \"1366,768\" \
  }"

const discoveryEndPoint = 'discovery_endpoint_here';

fetch(discoveryEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    start_at: '1513005534000',
    end_at: '1513008000000',
    object_latitude: '32.787793',
    object_longitude: '-79.935005',
    object_altitude: '80',
    azimuth_angle: '15',
    elevation_angle: '-20',
    distance: '30',
    min_resolution: '1366,768',
  }),
});

import requests
payload = {
    "start_at": "1513005534000",
    "end_at": "1513008000000",
    "object_latitude": "32.787793",
    "object_longitude": "-79.935005",
    "object_altitude": "80",
    "azimuth_angle": "15",
    "elevation_angle": "-20",
    "distance": "30",
    "min_resolution": "1366,768",
  }
requests.post("discovery_endpoint_here", data=payload)

`start_at` optional	The earliest time at which the photo shoot can start (if undefined, photo shoot can start immediately). Specified as time in seconds since Epoch/Unix Time
`end_at` required	The latest time at which the photo shoot should end. Specified as time in seconds since Epoch/Unix Time
`object_latitude` required	The latitude coordinate of the object that needs to be photographed
`object_longitude` required	The longitude coordinate of the object that needs to be photographed
`object_altitude` required	The altitude of the object that needs to be photographed. Specified as meters above sea level. For example, if the object is located 50 meters above sea level, the `object_altitude` will be `50`
`azimuth_angle` required	The horizontal angle of the camera pointing at the object. Specified as an integer representing degrees. For example, if the camera should be directly south of the photographed object, the `azimuth_angle` will be `0`
`elevation_angle` required	The vertical angle of the camera pointing at the object. Specified as an integer representing degrees, positive above the horizon, and negative below the horizon. For example, to photograph a rooftop from above, the `elevation_angle` might be `-90`
`distance` required	The distance of the camera from the photographed object. Specified as an integer representing meters
`min_resolution` optional	The minimum required dimensions for the photos. Specified as integers representing pixels, in a comma separated list of two integers (e.g., `1366,768` for HD photos)

Bid

A bid to provide a photo shoot service. Typically sent by a camera owner such as a human photographer or a drone with an integrated camera. The bid arrives with the price for the service, the type of camera, the operator (e.g., human, autonomous drone), and the estimated time of arrival.

Arguments

Post request to a local/remote bidding endpoint

curl "bidding_endpoint_here" \
  --data "{ \
    \"need_id\": \"ae7bd8f67f3089c\", \
    \"expires_at\": \"1513005539000\", \
    \"price\": \"20000000000000000,4000000000000000\", \
    \"price_type\": \"flat,flat\", \
    \"price_description\": \"Total price,VAT\", \
    \"eta\": \"1513005534000\", \
    \"camera_model\": \"ZENMUSE X5S\", \
    \"photo_resolution\": \"2720,1530\", \
    \"camera_operator\": \"controlled_drone\", \
    \"operator_model\": \"DJI Matrice 210\" \
  }"

const biddingEndPoint = 'bidding_endpoint_here';

fetch(biddingEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    need_id: 'ae7bd8f67f3089c',
    expires_at: '1513005539000',
    price: '20000000000000000,4000000000000000',
    price_type: 'flat,flat',
    price_description: 'Total price,VAT',
    eta: '1513005534000',
    camera_model: 'ZENMUSE X5S',
    photo_resolution: '2720,1530',
    camera_operator: 'controlled_drone',
    operator_model: 'DJI Matrice 210',
  }),
});

import requests
payload = {
    "need_id": "ae7bd8f67f3089c",
    "expires_at": "1513005539000",
    "price": "20000000000000000,4000000000000000",
    "price_type": "flat,flat",
    "price_description": "Total price,VAT",
    "eta": "1513005534000",
    "camera_model": "ZENMUSE X5S",
    "photo_resolution": "2720,1530",
    "camera_operator": "controlled_drone",
    "operator_model": "DJI Matrice 210",
  }
requests.post("bidding_endpoint_here", data=payload)

`need_id` required	The unique identifier of the 'need' this bid is for. This ID arrives as part of the 'need' request
`expires_at` required	This bid will expire at this time. Specified as time in seconds since Epoch/Unix Time
`price` required	A comma separated list of prices. Each price is specified as an integer representing Vinci 1 DAV == 1e18 Vinci == 1000000000000000000 Vinci
`price_type` required	A list of price types describing the `price` parameter(s). Specified as a comma separated list. Currently the only supported price type is `flat`
`price_description` required	A comma separated list of strings describing the `price` parameter(s) in human readable terms
`eta` required	The estimated time of arrival at the photo shoot location. Specified as time in seconds since Epoch/Unix Time
`camera_model` required	A human readable name/description of the camera used for the photo shooting (e.g., `DJI ZENMUSE X5S`)
`photo_resolution` required	The dimensions of the photos that will be taken. Specified as integers representing pixels, in a comma separated list of two integers (e.g., `1366,768` for HD photos)
`camera_operator` required	The operator of the camera during the photo shoot (e.g., `human`, `drone`) See full list of options here
`operator_model` optional	A human readable name/description of the vehicle that may be used to carry the camera and perform the photo shoot (e.g., `DJI Matrice 210`)

Camera Operator

The operator of the camera during the photo shoot.

Camera Operator	Description
`handheld`	Good ol' human photographer
`uav`	Unmanned aerial vehicle, commonly known as a drone. An aircraft without a human pilot aboard
`usv`	Unmanned surface vehicle. A vehicle that operates on the surface of the water (watercraft) without a crew
`uuv`	Unmanned underwater vehicle, sometimes known as underwater drones. Any vehicles that are able to operate underwater without a human occupant
`ugv`	Unmanned ground vehicle. A vehicle that operates while in contact with the ground and without an on board human presence