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	Original line	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.

Admin message