add worldanalysis api first version (f1218ef4) · Commits · ARF - Augmented Reality Framework / ARF005

API/worldanalysisapi.yaml

0 → 100644

+336 −0

Original line number	Diff line number	Diff line
		openapi: "3.0.0"

		info:
		version: 1.0.0
		title: World Analysis API
		description: API ensuring interoperability between Scene Management and a World Analysis service
		license:
		name: BSD-3-clause
		url: https://opensource.org/licenses/BSD-3-Clause
		servers:
		- url: http://localhost:8080

		tags:
		- name: default
		description: Default operations to test the current server's state
		- name : Pose
		description : Operations to retrieve poses of AR devices, Trackables and WorldAnchors

		paths:
		/ping:
		get:
		summary: Test the server availability.
		operationId: getPing
		responses:
		'200':
		description: Ok, returns a string message.
		content:
		text/plain:
		schema:
		type: string
		example: "pong"
		/admin:
		get:
		summary: Get the state of the server.
		operationId: getAdmin
		responses:
		'200':
		description: OK, world storage server ready.
		content:
		text/plain:
		schema:
		type: string
		example: "Server up and running"
		/version:
		get:
		summary: Get the version of the ARF API.
		operationId: getVersion
		responses:
		'200':
		description: Current version.
		content:
		text/plain:
		schema:
		type: string
		example: "1.0.0"
		/pose:
		post:
		summary: Request the pose of an AR device and/or one or several Trackables and WorldAnchors
		operationId: RequestPose
		description: Operation to retrieve the pose of an AR device in relation to a WorldAnchor or a Trackable (AR device pose), or conversely a Trackable or WorldAnchor in relation to the AR device (object pose).
		tags:
		- Pose
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		requestBody:
		required: true
		content:
		application/json:
		schema:
		properties:
		uuids:
		description: List of pairs consisting of UUIDs of requested WorldAnchor or Trackables and a boolean representing the context of the requested information
		type: array
		uniqueItems: true
		items:
		type: object
		properties:
		uuid:
		type: string
		format: uuid
		example: "fa8bbe40-8052-11ec-a8a3-0242ac120002"
		deviceToWorldAnchor:
		description: a boolean representing the context of the Relocalization information (AR device to WorldAnchor/Trackable or WorldAnchor/Trackable to AR device)
		type: boolean
		example: false
		responses:
		'200':
		description: Successful operation.
		content:
		application/json:
		schema:
		type: object
		properties:
		RelocInfo:
		type: array
		items:
		$ref: '#/components/schemas/EstimatedPose'
		'400':
		$ref: '#/components/responses/400_InvalidUUID'
		'404':
		$ref: '#/components/responses/404_NotFoundUUID'
		'default':
		$ref: '#/components/responses/4xx_UnexpectedError'
		/pose/config:
		post:
		summary: Specify the a minimum frame rate for pose estimation for Trackable types
		operationId: setPoseConfig
		description: Operation to set the minimum frame rate for pose estimation required for the different Trackable Types
		tags:
		- Pose
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		requestBody:
		required: true
		content:
		application/json:
		schema:
		type: object
		properties:
		PoseConfig:
		type: array
		items:
		$ref: '#/components/schemas/PoseConfigItem'
		responses:
		'200':
		description: Successful operation.
		content:
		application/json:
		schema:
		type: object
		properties:
		PoseConfig:
		type: array
		items:
		$ref: '#/components/schemas/PoseConfigItem'
		# same object type in answer : return PoseConfigItem for a given Trackable Type if supported with the minimum frame rate required the or the maximum frame rate that the World Analysis can reach
		'default':
		$ref: '#/components/responses/4xx_UnexpectedError'
		/capabilities:
		get:
		summary: Get the capabilities of the World Analysis
		operationId: getCapabilities
		description: Operation to retrieve information the capabilities of the World Analysis for pose estimation ( (e.g. frame rate, latency, accuracy or Trackable types supported for the pose estimation)
		tags:
		- Pose
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		responses:
		'200':
		description: Successful operation.
		content:
		application/json:
		schema:
		type: object
		properties:
		Capabilities:
		type: array
		items:
		$ref: '#/components/schemas/Capability'
		'default':
		$ref: '#/components/responses/4xx_UnexpectedError'


		# COMPONENTS ###############################################
		components:

		#-------------------------------
		# Reusable schemas (data models)
		#-------------------------------
		schemas:

		Token:
		type: string
		example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2V4YW1wbGUuYXV0aDAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLmV4YW1wbGUuY29tL2NhbGFuZGFyL3YxLyIsInN1YiI6InVzcl8xMjMiLCJpYXQiOjE0NTg3ODU3OTYsImV4cCI6MTQ1ODg3MjE5Nn0.CA7eaHjIHz5NxeIJoFK9krqaeZrPLwmMmgI_XiQiIkQ
		description: A string representing the token of the User.

		Error:
		required:
		- code
		- message
		properties:
		code:
		type: integer
		format: int32
		example: 406
		message:
		type: string
		example: "Error 406"

		#missing : pose payload
		EstimatedPose:
		description: An element representing the result of the pose estimation of an AR device, a Trackable or a WorldAnchor by the World Analysis
		type: object
		properties:
		estimationState:
		description: Extensible List of possible states of the pose estimation
		type: string
		enum: [OK, FAILURE , NOT_AUTHORIZED, OTHER]
		example: OK
		estimationInfo:
		description: A message detailing the context of the pose estimation
		type: string
		example: Lighting is toom dim
		timestamp:
		description: Capture time of the pose as number of milliseconds since unix epoch
		type: integer
		example : 1704812114841
		confidence:
		description: A score representing the confidence concerning the accuracy of the pose estimated
		type: number
		example : 50.00
		deviceToWorldAnchor:
		description: A boolean representing the context of the estimated pose (AR device to WorldAnchor/Trackable or WorldAnchor/Trackable to AR device)
		type: boolean
		example: false


		Capability:
		description: An object representing the support information about a given trackable type
		type: object
		uniqueItems: true
		properties:
		trackableType:
		type: string
		enum: [FIDUCIAL_MARKER, IMAGE_MARKER, MAP, GEOPOSE, OTHER]
		example: "FIDUCIAL_MARKER"
		supported:
		description: A boolean representing the support for this type of trackable by the World Analysis
		type: boolean
		example: true
		framerate:
		description: Number of frames per second the tracking of this type of trackable is performed by the World Analysis
		type: number
		example : 30.0
		latency:
		description: Mean tracking latency in milliseconds for this type of trackable
		type: number
		example: 10.0
		accuracy:
		description: Accuracy score for the detection of this type of Trackable by the World Analysis
		type: number
		example: 50.0


		PoseConfigItem:
		description: An object representing the framerate that the World Analysis can or needs to reach for a given Trackable Type
		type: object
		uniqueItems: true
		properties:
		trackableType:
		type: string
		enum: [FIDUCIAL_MARKER, IMAGE_MARKER, MAP, GEOPOSE, OTHER]
		example: "FIDUCIAL_MARKER"
		framerate:
		description: Number of frames per second the tracking expected for this type of trackable is performed by the World Analysis
		type: number
		example : 30.0



		#-------------------------------
		# Reusable responses
		#-------------------------------
		responses:
		#######################
		# 1xx : Informational #
		#######################

		#################
		# 2xx : Success #
		#################

		#####################
		# 3xx : Redirection #
		#####################

		#######################
		# 4xx : Client Errors #
		#######################
		400_BadRequest:
		description: Bad request.
		content:
		text/plain:
		schema:
		type: string
		example: "Bad request"

		400_InvalidUUID:
		description: Invalid UUID supplied.
		content:
		text/plain:
		schema:
		example: "The format of the UUID is incorrect"
		type: string

		404_NotFoundUUID:
		description: Not found, could not find UUID in database.
		content:
		text/plain:
		schema:
		type: string
		example: "Element not found"

		409_NotEmptyUUID:
		description: Invalid UUID, id must be a Nil value.
		content:
		text/plain:
		schema:
		type: string
		example: "The element you sent has already a value and can't be sent to the world storage"

		4xx_UnexpectedError: # Can be referenced as '#/components/responses/GenericError'
		description: Unexpected error.
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/Error'

		########################
		# 5xx : Server Errors #
		########################
		5xx_UnexpectedError:
		description: Unexpected server error.
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/Error'