Extension of API World Storage : feature/relocalizationInformation (d8a6dbe4) · Commits · ARF - Augmented Reality Framework / ARF005

API/openapi.yaml

+201 −8

Original line number	Diff line number	Diff line
		@@ -28,6 +28,8 @@ servers:
		tags:
		- name: default
		description: Default operations to test the current server's state
		- name: RelocalizationInformation
		description: Operations to retrieve relocalization information of the real world, including trackables and world anchors.
		- name: Trackables
		description: Trackables are models of parts of the real world. <br>Trackables are elements of the real world of which features are available and/or could be extracted.<br> Trackables provide a Coordinate Reference System in which a pose can be expressed.
		- name: World Anchors
		@@ -35,6 +37,7 @@ tags:
		- name: World Links
		description: A World Link represents and defines the relative 3D position and orientation between elements (Trackables and/or World Anchors).


		paths:
		/ping:
		get:
		@@ -73,6 +76,74 @@ paths:
		type: string
		example: "1.0.0"


		#############################
		# RelocalizationInformation #
		#############################

		/relocalizationInformation:
		get:
		summary: Operation to retrieve all the relocalization information of one or severals WorldAnchors or Trackables.
		operationId: getRelocalizationInformation
		tags:
		- RelocalizationInformation
		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 World Anchors 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

		capabilities:
		description: the list of all trackables and his encoding structure associated representing the supported data of the User
		type: array
		items:
		$ref: '#/components/schemas/Capability'
		responses:
		'200':
		description: Successful operation.
		content:
		application/json:
		schema:
		type: object
		properties:
		RelocInfo:
		type: array
		items:
		$ref: '#/components/schemas/RelocalizationInformation'
		'400':
		$ref: '#/components/responses/400_InvalidUUID'
		'404':
		$ref: '#/components/responses/404_NotFoundUUID'
		'default':
		$ref: '#/components/responses/4xx_UnexpectedError'







		##############
		# TRACKABLES #
		##############
		@@ -80,9 +151,14 @@ paths:
		post:
		summary: Create a Trackable.
		operationId: addTrackable
		description: Create a new Trackable from a json object containing all the required informations and add it to the world storage. <br>As a result you will get the ID of the newly created Trackable.
		description: Create a new Trackable from a json object containing all the required information and add it to the world storage. <br>As a result you will get the ID of the newly created Trackable.
		tags:
		- Trackables
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		requestBody:
		description: The Trackable to be added to the world storage.
		required: true
		@@ -114,9 +190,14 @@ paths:
		put:
		summary: Modify a Trackable.
		operationId: modifyTrackable
		description: Modify an existing Trackable given a json object containing all the required informations. <br> Please note that ID of the object is required in the JSON
		description: Modify an existing Trackable given a json object containing all the required information. <br> Please note that ID of the object is required in the JSON
		tags:
		- Trackables
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		requestBody:
		description: The Trackable to be modified in the world storage.
		required: true
		@@ -144,6 +225,11 @@ paths:
		description: Get all the Trackables currently being stored in the world storage.
		tags:
		- Trackables
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		responses:
		'200':
		description: OK, return all the Trackables defined by the world storage.
		@@ -171,6 +257,10 @@ paths:
		tags:
		- Trackables
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		- name: trackableUUID
		in: path
		description: UUID of the Trackable to retrieve.
		@@ -196,6 +286,10 @@ paths:
		tags:
		- Trackables
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		- name: trackableUUID
		in: path
		description: Trackable UUID to delete.
		@@ -223,9 +317,14 @@ paths:
		post:
		summary: Create a World Anchor.
		operationId: addWorldAnchor
		description: Create a new World Anchor from a json object containing all the required informations and add it to the world storage. <br>As a result you will get the ID of the newly created World Anchor.
		description: Create a new World Anchor from a json object containing all the required information and add it to the world storage. <br>As a result you will get the ID of the newly created World Anchor.
		tags:
		- World Anchors
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		requestBody:
		description: The World Anchor to be added to the world storage.
		required: true
		@@ -257,9 +356,14 @@ paths:
		put:
		summary: Modify a World Anchor.
		operationId: modifyWorldAnchor
		description: Modify an existing World Anchor given a json object containing all the required informations. <br> Please note that ID of the object is required in the JSON
		description: Modify an existing World Anchor given a json object containing all the required information. <br> Please note that ID of the object is required in the JSON
		tags:
		- World Anchors
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		requestBody:
		description: The World Anchor to be modified in the world storage.
		required: true
		@@ -287,6 +391,11 @@ paths:
		description: Get all the World Anchors currently being stored in the world storage.
		tags:
		- World Anchors
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		responses:
		'200':
		description: OK, return all the World Anchors defined by the world storage.
		@@ -314,6 +423,10 @@ paths:
		tags:
		- World Anchors
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		- name: worldAnchorUUID
		in: path
		description: UUID of the World Anchor to retrieve.
		@@ -339,6 +452,10 @@ paths:
		tags:
		- World Anchors
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		- name: worldAnchorUUID
		in: path
		description: World Anchor UUID to delete.
		@@ -366,9 +483,14 @@ paths:
		post:
		summary: Create a World Link between elements (world anchors and/or trackables).
		operationId: addWorldLink
		description: Create a new World Link from a json object containing all the required informations and add it to the world storage. <br>As a result you will get the ID of the newly created World Link.
		description: Create a new World Link from a json object containing all the required information and add it to the world storage. <br>As a result you will get the ID of the newly created World Link.
		tags:
		- World Links
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		requestBody:
		description: The link to be added to the world storage.
		required: true
		@@ -400,9 +522,14 @@ paths:
		put:
		summary: Modify a World Link.
		operationId: modifyWorldLink
		description: Modify an existing World Link given a json object containing all the required informations. <br> Please note that ID of the object is required in the JSON
		description: Modify an existing World Link given a json object containing all the required information. <br> Please note that ID of the object is required in the JSON
		tags:
		- World Links
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		requestBody:
		description: The World Link to be modified in the world storage.
		required: true
		@@ -430,6 +557,11 @@ paths:
		operationId: getWorldLinks
		tags:
		- World Links
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		responses:
		'200':
		description: OK return all the World Links defined by the world storage.
		@@ -457,6 +589,10 @@ paths:
		tags:
		- World Links
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		- name: worldLinkUUID
		in: path
		description: UUID of the World Link to retrieve.
		@@ -482,6 +618,10 @@ paths:
		tags:
		- World Links
		parameters:
		- in: header
		name: token
		schema:
		$ref: '#/components/schemas/Token'
		- name: worldLinkUUID
		in: path
		description: World Link id to delete.
		@@ -502,6 +642,8 @@ paths:
		'404':
		$ref: '#/components/responses/404_NotFoundUUID'



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

		@@ -509,6 +651,34 @@ components:
		# Reusable schemas (data models)
		#-------------------------------
		schemas:


		RelocalizationInformation:
		description: An element representing all information needed in relation with a Trackable or a WorldAnchor.
		type: object
		properties:
		rootUUID:
		description: The UUID of the original WorldAnchor or the Trackable asked.
		type: string
		format: uuid
		example: 89b7e1f5-dd41-4746-9279-e1ef9284fe4d
		relocObjects:
		description: an array with trackables and their transforms linking them to the rootUUID element.
		type: array
		items:
		type: object
		properties:
		trackable:
		$ref : '#/components/schemas/Trackable'
		Transform3D:
		$ref : '#/components/schemas/Transform3D'
		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



		Trackable:
		description: An element representing a Trackable object in the real world.
		type: object
		@@ -557,6 +727,10 @@ components:
		$ref: '#/components/schemas/Size'
		keyvalueTags:
		$ref: '#/components/schemas/KeyvalueTagList'
		confidence:
		type: number
		example : 50.00


		WorldAnchor:
		description: An element describing a pose in the world graph.
		@@ -636,8 +810,22 @@ components:
		keyvalueTags:
		$ref: '#/components/schemas/KeyvalueTagList'

		Capability:
		description: An object representing an instance of the possible supported data
		type: object
		uniqueItems: true
		properties:
		trackableType:
		type: string
		enum: [FIDUCIAL_MARKER, IMAGE_MARKER, MAP, GEOPOSE, OTHER]
		example: "FIDUCIAL_MARKER"
		encodingInformation:
		$ref: '#/components/schemas/EncodingInformationStructure'



		EncodingInformationStructure:
		description: An object holding the info of a Trackable`'`s encoding informations `:` the data format and the version.
		description: An object holding the info of a Trackable`'`s encoding information `:` the data format and the version.
		required:
		- dataFormat
		- version
		@@ -697,6 +885,11 @@ components:
		minItems: 1
		example: { "Place" : ["Building 123"], "Room" : ["007"]}

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

		Error:
		required:
		- code