vmeta.proto

/**
 * Copyright (c) 2016 Parrot Drones SAS
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *   * Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *   * Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in the
 *     documentation and/or other materials provided with the distribution.
 *   * Neither the name of the Parrot Drones SAS Company nor the
 *     names of its contributors may be used to endorse or promote products
 *     derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE PARROT DRONES SAS COMPANY BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

syntax = "proto3";

package vmeta;

option java_package = "com.parrot.drone.groundsdk.protobuf";
option java_outer_classname = "VideoMetadata";

/**
 * Enums
 */

enum TrackingClass {
	/* Person */
	TC_PERSON = 0;

	/* Animal */
	TC_ANIMAL = 1;

	/* Bicycle */
	TC_BICYCLE = 2;

	/* Boat */
	TC_BOAT = 3;

	/* Car */
	TC_CAR = 4;

	/* Horse */
	TC_HORSE = 5;

	/* Motorbike */
	TC_MOTORBIKE = 6;

	/* Undefined (object not recognized).
	 * Value is kept at the highest 1byte varint for clarity,
	 * and to reserve space for future values */
	TC_UNDEFINED = 127;
}

enum TrackingState {
	/* Tracking */
	TS_TRACKING = 0;

	/* Searching */
	TS_SEARCHING = 1;
}

enum FlyingState {
	/* Landed state */
	FS_LANDED = 0;

	/* Taking off state */
	FS_TAKINGOFF = 1;

	/* Hovering state */
	FS_HOVERING = 2;

	/* Flying state */
	FS_FLYING = 3;

	/* Landing state */
	FS_LANDING = 4;

	/* Emergency state */
	FS_EMERGENCY = 5;

	/* User-takeoff state */
	FS_USER_TAKEOFF = 6;

	/* Motor-ramping state */
	FS_MOTOR_RAMPING = 7;

	/* Emergency-landing state */
	FS_EMERGENCY_LANDING = 8;
}

enum PilotingMode {
	/* Unknown/not available */
	PM_UNKNOWN = 0;

	/* Manual piloting */
	PM_MANUAL = 1;

	/* Automatic return home */
	PM_RETURN_HOME = 2;

	/* Automatic flight plan */
	PM_FLIGHT_PLAN = 3;

	/* Automatic tracking */
	PM_TRACKING = 4;

	/* Automatic move-to */
	PM_MOVETO = 5;

	/* Automatic "magic-carpet" test */
	PM_MAGIC_CARPET = 6;
}

enum Animation {
	/* None */
	ANIM_NONE = 0;

	/* Orbit */
	ANIM_ORBIT = 1;

	/* Boomerang */
	ANIM_BOOMERANG = 2;

	/* Parabola */
	ANIM_PARABOLA = 3;

	/* Dolly slide */
	ANIM_DOLLY_SLIDE = 4;

	/* Dolly zoom */
	ANIM_DOLLY_ZOOM = 5;

	/* Vertical reveal */
	ANIM_REVEAL_VERT = 6;

	/* Horizontal reveal */
	ANIM_REVEAL_HORIZ = 7;

	/* Horizontal panorama */
	ANIM_PANO_HORIZ = 8;

	/* Candle */
	ANIM_CANDLE = 9;

	/* Front flip */
	ANIM_FLIP_FRONT = 10;

	/* Back flip */
	ANIM_FLIP_BACK = 11;

	/* Left flip */
	ANIM_FLIP_LEFT = 12;

	/* Right flip */
	ANIM_FLIP_RIGHT = 13;

	/* Twist-up */
	ANIM_TWISTUP = 14;

	/* Position twist-up */
	ANIM_POSITION_TWISTUP = 15;
}

enum LinkType {
	/* Unknown */
	LINK_TYPE_UNKNOWN = 0;

	/* Reserved */
	LINK_TYPE_LO = 1;

	/* Reserved */
	LINK_TYPE_LAN = 2;

	/* Wlan (Wi-Fi) interface */
	LINK_TYPE_WLAN = 3;

	/* Cellular (4G) interface */
	LINK_TYPE_CELLULAR = 4;
}

enum LinkStatus {
	/* Interface is down */
	LINK_STATUS_DOWN = 0;

	/* Interface is up with IP connectivity */
	LINK_STATUS_UP = 1;

	/* Starfish session established on the link */
	LINK_STATUS_RUNNING = 2;

	/* Link is ready to connect or accept connections */
	LINK_STATUS_READY = 3;

	/* Connection in progress */
	LINK_STATUS_CONNECTING = 4;

	/* Link error */
	LINK_STATUS_ERROR = 5;
}

enum ThermalCalibrationState {
	/* OK/Done */
	TCS_DONE = 0;

	/* Requested */
	TCS_REQUESTED = 1;

	/* In progress */
	TCS_IN_PROGRESS = 2;
}


/**
 * Commonly used structures
 */

/* Unit quaternion */
message Quaternion {
	float w = 1;
	float x = 2;
	float y = 3;
	float z = 4;
}

/* Location on earth */
message Location {
	/* Latitude and longitude (degrees) */
	double latitude = 1;
	double longitude = 2;

	/* Altitude above the WGS84 ellipsoid (m) (zero means unknown) */
	double altitude_wgs84ellipsoid = 3;

	/* Altitude above the EGM96 geoid (AMSL) (m) (zero means unknown) */
	double altitude_egm96amsl = 7;

	/* Horizontal and vertical location accuracy (m), zero means unknown */
	float horizontal_accuracy = 5;
	float vertical_accuracy = 6;

	/* GPS Satellite vehicle count, only set if location comes at least
	 * partially from a GPS sensor */
	uint32 sv_count = 4;
}

/* Generic 2 component vector */
message Vector2 {
	float x = 1;
	float y = 2;
}

/* Generic 3 component vector */
message Vector3 {
	float x = 1;
	float y = 2;
	float z = 3;
}

/* 3 component vector, in NED frame */
message NED {
	float north = 1;
	float east = 2;
	float down = 3;
}

/* Bounding box for tracking and proposal */
message BoundingBox {
	/* Position [0; 1] in picture */
	float x = 1;
	float y = 2;

	/* Dimensions [0; 1] relative to picture */
	float width = 3;
	float height = 4;

	/* Type of tracked object */
	TrackingClass object_class = 5;

	/* Tracking confidence [0; 1] */
	float confidence = 6;

	/* Box unique identifier (UID). Multiple BoundingBox messages sharing
	 * the same UID refers to the same bounding box */
	uint32 uid = 7;
}

/* Thermal spot for thermal metadata */
message ThermalSpot {
	/* Position [0; 1] in picture */
	float x = 1;
	float y = 2;

	/* Temperature, in either Kelvin for radiometric sensors,
	 * or raw sensor unit for non-radiometric sensors */
	float temp = 3;
}


/**
 * Actual messages
 */

message DroneMetadata {
	reserved 6, 8;

	/* Drone quaternion */
	Quaternion quat = 1;

	/* Drone location */
	Location location = 2;

	/* Best ground distance estimation (m) */
	double ground_distance = 3;

	/* Estimated position of the drone in NED frame (m).
	 * The position is initialized at first take off. When this position may
	 * have drifted from the true position (for example when GPS signal is
	 * not available), this position jumps on the first absolute position
	 * measurement available. */
	NED position = 9;

	/* Estimated position of the drone in the local frame (m).
	 * The local frame is not NED: X and Y axis are arbitrary, but the Z
	 * axis is guaranteed to point down.
	 * The position is initialized at first take off. This position is
	 * guaranteed not to jump, even when a new absolute position (usually
	 * GPS) is available. Instead, the origin of the local frame jumps in
	 * order to ensure the continuity of the local position.
	 */
	Vector3 local_position = 10;

	/* Speed vector in NED (North-East-Down) (m/s) */
	NED speed = 4;

	/* Battery charge percentage */
	sint32 battery_percentage = 5;

	/* Flying state */
	FlyingState flying_state = 7;

	/* Animation in progreess */
	bool animation_in_progress = 11;

	/* Piloting mode */
	PilotingMode piloting_mode = 12;
}

message CameraMetadata {
	/* Frame capture timestamp (us, monotonic) */
	uint64 timestamp = 1;

	/* Frame capture UTC timestamp (us since the Epoch) */
	uint64 utc_timestamp = 10;

	/* Frame capture UTC timestamp accuracy (us); zero means unknown,
	 * utc_timestamp must then be considered invalid */
	uint32 utc_timestamp_accuracy = 11;

	/* Frame base view quaternion (without user pan/tilt) */
	Quaternion base_quat = 2;

	/* Frame view quaternion */
	Quaternion quat = 3;

	/* Estimated position of the camera in the local frame (m).
	 * The local frame is not NED: X and Y axis are arbitrary, but the Z
	 * axis is guaranteed to point down.
	 * The position is initialized at first take off. This position is
	 * guaranteed not to jump, even when a new absolute position (usually
	 * GPS) is available. Instead, the origin of the local frame jumps in
	 * order to ensure the continuity of the local position.
	 * This position is not available on all cameras. If not available,
	 * the Drone.local_position metadata should be used instead.
	 */
	Vector3 local_position = 12;

	/* Camera location */
	Location location = 13;

	/* Camera principal point normalized coordinates in picture [0; 1] */
	Vector2 principal_point = 14;

	/* Frame exposure time (ms) */
	float exposure_time = 4;

	/* Frame ISO gain */
	uint32 iso_gain = 5;

	/* Frame AWB red gain */
	float awb_r_gain = 6;

	/* Frame AWB blue gain */
	float awb_b_gain = 7;

	/* Frame horizontal field of view (rad) */
	float hfov = 8;

	/* Frame vertical field of view (rad) */
	float vfov = 9;
}

message TrackingProposalMetadata {
	/* List of proposed bounding boxes */
	repeated BoundingBox proposals = 1;

	/* Processed frame capture timestamp (us, monotonic)
	 * note: may be different from the timestamp in CameraMetadata */
	uint64 timestamp = 2;
}

message TrackingMetadata {
	/* Tracking target */
	BoundingBox target = 1;

	/* Processed frame capture timestamp (us, monotonic)
	 * note: may be different from the timestamp in CameraMetadata */
	uint64 timestamp = 2;

	/* Tracking quality ([0; 255], 0 is worst, 255 is best) */
	uint32 quality = 3;

	/* Tracking state */
	TrackingState state = 4;

	/* Cookie value passed by the app when the tracking is started */
	uint32 cookie = 5;
}

message AutomationMetadata {
	/* Current destination */
	Location destination = 1;

	/* Tracking target location */
	Location target_location = 2;

	/* Follow-me enabled */
	bool follow_me = 3;

	/* Look-at-me enabled */
	bool lookat_me = 4;

	/* Angle-locked:
	 * false: NED (North-East-Down) absolute angle mode
	 * true: constant angle relative to the target movement */
	bool angle_locked = 5;

	/* Current animation */
	Animation animation = 6;
}

message WifiLinkMetadata {
	/* Wifi link goodput (throughput estimation) (kbit/s) */
	uint32 goodput = 1;

	/* Wifi link quality ([0; 5], 0 is worst, 5 is best) */
	uint32 quality = 2;

	/* Wifi link RSSI (dBm) */
	sint32 rssi = 3;
}

message StarfishLinkInfo {
	/* Type of link */
	LinkType type = 1;

	/* Link status */
	LinkStatus status = 2;

	/* Link quality indication: 1 (lower) to 5 (better),
	 * 0 if not available */
	int32 quality = 3;

	/* Link active status */
	bool active = 4;
}

message StarfishLinkMetadata {
	/* Links */
	repeated StarfishLinkInfo links = 1;

	/* Global link quality indication: 1 (lower) to 5 (better),
	 * 0 if not available */
	int32 quality = 2;
}

message LinkMetadata {
	oneof protocol {
		/* Wifi link metadata */
		WifiLinkMetadata wifi = 1;

		/* Starfish link metadata */
		StarfishLinkMetadata starfish = 2;
	}
}

message ThermalMetadata {
	/* Thermal calibration state */
	ThermalCalibrationState calibration_state = 1;

	/* Minimum temperature spot */
	ThermalSpot min = 2;

	/* Maximum temperature spot */
	ThermalSpot max = 3;

	/* Probe temperature spot */
	ThermalSpot probe = 4;
}

message LFICMetadata {
	/* Position of target [0; 1] in picture */
	float x = 1;
	float y = 2;

	/* Location of target */
	Location location = 3;

	/* Grid precision used for calculation (m) */
	double grid_precision = 4;
}

message TimedMetadata {
	/* Drone-related metadata */
	DroneMetadata drone = 1;

	/* Camera-related metadata */
	CameraMetadata camera = 2;

	/* Link-related metadata, one per available link */
	repeated LinkMetadata links = 3;

	/* Tracking metadata */
	TrackingMetadata tracking = 4;

	/* Tracking proposal metadata */
	TrackingProposalMetadata proposal = 5;

	/* Automation metadata */
	AutomationMetadata automation = 6;

	/* Thermal metadata */
	ThermalMetadata thermal = 7;

	/* Location From Image Coordinates (LFIC) metadata */
	LFICMetadata lfic = 8;
}