Initialize the project with the code from the ARF005 project, branch feature/worldanalysispose (71d87e0a) · Commits · ARF - Augmented Reality Framework / ARF

API/worldanalysis/worldanalysisopenapi.yaml

0 → 100644

+615 −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 collect poses of AR devices, Trackables and WorldAnchors from the World Analysis
		- name : Capabilities
		description : Operation to retrieves the supported capabilities of the World Analysis

		paths:
		## Default
		/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/configure/framerate:
		post:
		summary: Specify the a minimum frame rate for pose estimation for Trackable types
		operationId: configureFramerate
		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:
		$ref: '#/components/schemas/PoseConfiguration'
		responses:
		'200':
		description: Successful operation.
		'405':
		$ref: '#/components/responses/405_NotSupported'
		'default':
		$ref: '#/components/responses/4xx_UnexpectedError'

		/pose/{trackableOrAnchorUUID}:
		get:
		summary: Request the last pose of an AR device, an Anchor or a Trackable
		operationId: getLastPose
		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:
		- name: trackableOrAnchorUUID
		in: path
		description: UUID of the Trackable or Anchor to check support
		required: true
		schema:
		type: string
		format: uuid
		- name: deviceToWorldAnchor
		in: query
		description: a boolean representing the context of the Relocalization information (AR device to WorldAnchor/Trackable or WorldAnchor/Trackable to AR device)
		required: false
		schema:
		type: boolean
		default: false
		example: false
		responses:
		'200':
		description: Successful operation.
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/Pose'
		'400':
		$ref: '#/components/responses/400_InvalidUUID'
		'403':
		$ref: '#/components/responses/403_ForbiddenUUID'
		'404':
		$ref: '#/components/responses/404_NotFoundUUID'
		'405':
		$ref: '#/components/responses/405_NotSupported'
		'default':
		$ref: '#/components/responses/4xx_UnexpectedError'

		/pose/{trackableOrAnchorUUID}/subscribe:
		post:
		summary: Subscribe to collect the pose of an AR device, an Anchor or a Trackable
		operationId: subscribeToPose
		description: Subscription to collect 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). Notifications are sent either using a provided webhook or a dynamically generated websocket endpoints.
		tags:
		- Pose
		parameters:
		- name: token
		in: header
		schema:
		$ref: '#/components/schemas/Token'
		- name: trackableOrAnchorUUID
		in: path
		description: UUID of the Trackable or Anchor to subscribe
		required: true
		schema:
		type: string
		format: uuid
		- name: deviceToWorldAnchor
		in: query
		description: a boolean representing the context of the Relocalization information (AR device to WorldAnchor/Trackable or WorldAnchor/Trackable to AR device)
		required: false
		schema:
		type: boolean
		default: false
		example: false
		requestBody:
		required: false
		content:
		application/json:
		schema:
		properties:
		validity:
		description: Subscription validity delay in millisecond
		type: integer
		example: 20000
		webhookUrl:
		description: Optional URL of your listening webhook for collecting the poses
		type: string
		default: null
		example: http://mySceneManagementServer.com/Poses"
		responses:
		'200':
		description: Successful operation.
		content:
		application/json:
		schema:
		$ref: '#/components/schemas/Subscription'
		'400':
		$ref: '#/components/responses/400_InvalidUUID'
		'403':
		$ref: '#/components/responses/403_ForbiddenUUID'
		'404':
		$ref: '#/components/responses/404_NotFoundUUID'
		'405':
		$ref: '#/components/responses/405_NotSupported'
		'default':
		$ref: '#/components/responses/4xx_UnexpectedError'

		/pose/unsubscribe/{subscriptionUUID}:
		delete:
		summary: Remove a subscription to a given pose
		operationId: unSubscribeToPose
		description: End the subscription and the associated callback for collecting a given pose
		tags:
		- Pose
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		- name: subscriptionUUID
		in: path
		description: Subscription UUID to delete.
		required: true
		schema:
		type: string
		format: uuid
		responses:
		'200':
		description: OK, unbscription successful.
		content:
		text/plain:
		schema:
		type: string
		example: "Subscription succesfuly deleted"
		'400':
		$ref: '#/components/responses/400_InvalidUUID'
		'404':
		$ref: '#/components/responses/404_NotFoundUUID'

		/capabilities:
		get:
		summary: Get the supported 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:
		- Capabilities
		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'


		/capabilities/{TrackableOrAnchorUUID}:
		get:
		summary: For a given trackable or anchor, get its support information
		operationId: getSupport
		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:
		- Capabilities
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		- name: TrackableOrAnchorUUID
		in: path
		description: UUID of the Trackable or Anchor to check support
		required: true
		schema:
		type: string
		format: uuid
		responses:
		'200':
		description: Successful operation.
		content:
		application/json:
		schema:
		type: object
		properties:
		type:
		$ref: '#/components/schemas/TypeWorldStorage'
		capability:
		$ref: '#/components/schemas/Capability'
		'400':
		$ref: '#/components/responses/400_InvalidUUID'
		'403':
		$ref: '#/components/responses/403_ForbiddenUUID'
		'404':
		$ref: '#/components/responses/404_NotFoundUUID'
		'405':
		$ref: '#/components/responses/405_NotSupported'
		'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.

		Pose:
		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:
		uuid:
		description: UUID of the associated Anchor or Trackable
		type: string
		format: uuid
		example: "fa8bbe40-8052-11ec-a8a3-0242ac120002"
		estimationState:
		description: Extensible List of possible states of the pose estimation
		type: string
		enum: [OK, FAILURE]
		example: OK
		instructionInfo:
		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
		value:
		description: The pose value
		oneOf:
		- $ref: '#/components/schemas/MatrixPoseValue'
		- $ref: '#/components/schemas/VectorQuaternionPoseValue'
		- $ref: '#/components/schemas/GeodeticPoseValue'
		example:
		type: "MATRIX"
		transform: [ 1, 0, 0, 3,
		0, 1, 0, 3,
		0, 0, 1, 3,
		0, 0, 0, 1 ]

		PoseValue:
		description: Base type to define the pose value
		type: object
		properties:
		type:
		description: Encoding type of the Pose
		type: string
		enum: [MATRIX, VECTORQUATERNION, GEODETIC]

		MatrixPoseValue:
		description: A pose value that is described with a 4*4 matrix
		allOf: #inheritance
		- $ref: '#/components/schemas/PoseValue'
		properties:
		transform:
		description : Pose data
		$ref: '#/components/schemas/Transform3D'
		unit:
		description: Unit system of the pose
		$ref: '#/components/schemas/UnitSystem'

		VectorQuaternionPoseValue:
		description: A pose value that is described with a position and a rotation
		allOf: #inheritance
		- $ref: '#/components/schemas/PoseValue'
		properties:
		position:
		description : Pose Position
		$ref: '#/components/schemas/Vector3'
		rotation:
		description : Pose Rotation
		$ref: '#/components/schemas/Quaternion'
		unit:
		description: Unit system of the pose
		$ref: '#/components/schemas/UnitSystem'

		GeodeticPoseValue:
		description : A pose value in a geodetic coordinate system
		allOf: #inheritance
		- $ref: '#/components/schemas/PoseValue'
		properties:
		altitude:
		type: number
		example: 70.0
		longitude:
		type: number
		example: 7.013579
		latitude:
		type: number
		example: 43.57351
		rotation:
		description: Pose Rotation
		$ref: '#/components/schemas/Quaternion'
		geodeticsystem:
		description: Associated geodetic system of the pose
		type: string
		example: "WGS84"
		rotationTarget:
		description: Coordinate system of the rotation
		type : string
		enum: [EASTUPSOUTH, WESTUPNORTH]
		example: EASTUPSOUTH

		UnitSystem:
		description: Unit of length.
		type: string
		enum: [MM, CM, DM, M, DAM, HM, KM, INCH, FOOT, YARD, MILE]
		example: M

		Transform3D:
		description: Coordinate reference system of the world anchor, a 4*4 matrix (rowmajor) represented by a float vector.
		type: array
		minItems: 16
		maxItems: 16
		items:
		type: number
		format: float
		example: [ 1, 0, 0, 3,
		0, 1, 0, 3,
		0, 0, 1, 3,
		0, 0, 0, 1 ]

		Vector3:
		description: A 3 coordinates vector
		type: array
		minItems: 3
		maxItems: 3
		items:
		type: number
		format: float
		example: [ 1, 0, 0 ]

		Quaternion:
		description: A quaternion
		type: array
		minItems: 4
		maxItems: 4
		items:
		type: number
		format: float
		example: [ 0, 0, 0, 1 ]

		TypeWorldStorage:
		description: Trackable or Anchor
		type: string
		enum: [TRACKABLE, ANCHOR]
		example: ANCHOR

		Capability:
		description: An object representing a supported capability of the World Analysis and its associated metadata
		type: object
		uniqueItems: true
		properties:
		trackableType:
		type: string
		enum: [FIDUCIAL_MARKER, IMAGE_MARKER, MAP, GEOPOSE, OTHER]
		example: "FIDUCIAL_MARKER"
		encodingInformation:
		$ref: '#/components/schemas/EncodingInformationStructure'
		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

		PoseConfiguration:
		description: An object representing the framerate that the World Analysis 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"
		encodingInformation:
		$ref: '#/components/schemas/EncodingInformationStructure'
		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

		Subscription:
		description: Response when subscribing for pose update of a Trackable or a WorldAnchor
		type: object
		properties:
		uuid:
		description: UUID of the subscription
		type: string
		format: uuid
		example: "bdc83e6b-a89d-4b29-9c99-e9015d448b10"
		validity:
		type: integer
		example: 20000
		websocketurl:
		description: Optional dynamically generated websocket url in case of no webhook provided in the request body
		type: string
		example: wss://www.WorkdAnalysis.com/socketserver/bdc83e6b-a89d-4b29-9c99-e9015d448b10"
		required:
		- uuid

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

		# From World Storage
		EncodingInformationStructure:
		description: An object holding the info of a Trackable`'`s encoding information `:` the data format and the version.
		required:
		- dataFormat
		- version
		properties:
		dataFormat:
		description: Identifier of the target framework.
		type: string
		enum: [HOLOLENS, ARKIT, ARCORE, VUFORIA, ARUCO, OTHER]
		example : "HOLOLENS"
		version:
		description: The version of the format
		type: string
		example : "1.01"

		#-------------------------------
		# 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

		403_ForbiddenUUID:
		description: Not allowed to access this UUID
		content:
		text/plain:
		schema:
		type: string
		example: "Not allowed"

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

		405_NotSupported:
		description: Feature not supported.
		content:
		text/plain:
		schema:
		type: string
		example: "Not supported"

		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'

API/worldstorage/worldstorageopenapi.yaml

0 → 100644

+972 −0

File added.

Preview size limit exceeded, changes collapsed.