Merge branch 'feature/addWorldAnchorsAndWorldLinks' into develop (793e6e63) · Commits · ARF - Augmented Reality Framework / ARF005

API/openapi.yaml

0 → 100644

+491 −0

Original line number	Original line	Diff line number	Diff line
			openapi: "3.0.0"
			info:
			version: 0.0.4
			title: World Storage API
			description: API ensuring interoperability between an authoring tool and a World Storage service
			license:
			name: BSD-3-clause
			url: https://opensource.org/licenses/BSD-3-Clause
			servers:
			- url: http://localhost:8080
			paths:
			/ping:
			get:
			summary: Test the server availability
			responses:
			'200':
			description: OK
			/admin:
			get:
			summary: Get the version of the API
			operationId: getVersion
			responses:
			'200':
			description: OK world storage.
			content:
			text/plain:
			schema:
			type: string
			/trackables:
			post:
			summary: Create a trackable
			operationId: addTrackable
			tags:
			- trackables
			requestBody:
			description: the trackable to be added to the world storage
			required: true
			content:
			application/json:
			schema:
			$ref: '#/components/schemas/Trackable'
			application/xml:
			schema:
			$ref: '#/components/schemas/Trackable'
			responses:
			'200':
			description: OK returns the UUID of the Trackable defined by the world storage.
			content:
			text/plain:
			schema:
			type: string
			'201':
			description: Null response
			default:
			description: unexpected error
			content:
			application/json:
			schema:
			$ref: '#/components/schemas/Error'
			# Check 2xx, 4xx, 5xx...
			'401':
			$ref: '#/components/responses/UUID'
			get:
			summary: returns the list of all trackables defined by the world storage.
			operationId: getTrackables
			tags:
			- trackables
			responses:
			'200':
			description: OK returns all the Trackables defined by the world storage.
			content:
			application/json:
			schema:
			type : array
			items :
			$ref: "#/components/schemas/Trackable"
			'201':
			description: Null response
			default:
			description: unexpected error
			content:
			application/json:
			schema:
			$ref: "#/components/schemas/Error"

			/trackables/{trackableUUID}:
			get:
			summary: Find a trackable by its UUID
			operationId: getTrackableById
			tags:
			- trackables
			parameters:
			- name: trackableUUID
			in: path
			description: UUID of the trackable to retrieve
			required: true
			schema:
			type: string
			responses:
			'200':
			description: Successful operation
			content:
			application/json:
			schema:
			$ref: '#/components/schemas/Trackable'
			'400':
			description: Invalid UUID supplied
			'404':
			description: Trackable not found
			delete:
			summary: Deletes a trackable
			operationId: deleteTrackable
			tags:
			- trackables
			parameters:
			- name: trackableUUID
			in: path
			description: trackable UUID to delete
			required: true
			schema:
			type: string
			responses:
			'200':
			description: OK
			'400':
			description: Invalid UUID supplied
			'404':
			description: trackable not found
			/worldAnchors:
			post:
			summary: Create a world anchor
			operationId: addWorldAnchor
			tags:
			- world anchors
			requestBody:
			description: the world anchor to be added to the world storage
			required: true
			content:
			application/json:
			schema:
			$ref: '#/components/schemas/WorldAnchor'
			application/xml:
			schema:
			$ref: '#/components/schemas/WorldAnchor'
			responses:
			'200':
			description: OK returns the UUID of the World Anchor defined by the world storage.
			content:
			text/plain:
			schema:
			type: string
			'201':
			description: Null response
			default:
			description: unexpected error
			content:
			application/json:
			schema:
			$ref: '#/components/schemas/Error'
			get:
			summary: returns the list of all world anchors defined by the world storage.
			operationId: getWorldAnchors
			tags:
			- world anchors
			responses:
			200:
			description: OK returns all the world anchors defined by the world storage.
			content:
			application/json:
			schema:
			type : array
			items :
			$ref: "#/components/schemas/WorldAnchor"
			201:
			description: Null response
			default:
			description: unexpected error
			content:
			application/json:
			schema:
			$ref: "#/components/schemas/Error"
			/worldAnchors/{worldAnchorUUID}:
			get:
			summary: Find a world anchor by his UUID
			operationId: getWorldAnchorById
			tags:
			- world anchors
			parameters:
			- name: trackableUUID
			in: path
			description: UUID of the world anchor to retrieve
			required: true
			schema:
			type: string
			responses:
			'200':
			description: Successful operation
			content:
			application/json:
			schema:
			$ref: '#/components/schemas/WorldAnchor'
			'400':
			description: Invalid UUID supplied
			'404':
			description: World Anchor not found
			delete:
			summary: Deletes a world anchor
			operationId: deleteWorldAnchor
			tags:
			- world anchors
			parameters:
			- name: trackableUUID
			in: path
			description: world anchor UUID to delete
			required: true
			schema:
			type: string
			responses:
			'200':
			description: OK
			'400':
			description: Invalid UUID supplied
			'404':
			description: World anchor not found
			/worldLinks:
			post:
			summary: Create a link between world anchors and trackables
			operationId: addWorldLink
			tags:
			- world links
			requestBody:
			description: the link to be added to the world storage
			required: true
			content:
			application/json:
			schema:
			$ref: '#/components/schemas/WorldLink'
			application/xml:
			schema:
			$ref: '#/components/schemas/WorldLink'
			responses:
			'200':
			description: OK returns the UUID of the link defined by the world storage.
			content:
			text/plain:
			schema:
			type: string
			'201':
			description: Null response
			default:
			description: unexpected error
			content:
			application/json:
			schema:
			$ref: '#/components/schemas/Error'
			get:
			summary: returns the list of all links defined by the world storage.
			operationId: getWorldLinks
			tags:
			- world links
			responses:
			200:
			description: OK returns all the worldLinks defined by the world storage.
			content:
			application/json:
			schema:
			type : array
			items :
			$ref: "#/components/schemas/WorldLink"
			201:
			description: Null response
			default:
			description: unexpected error
			content:
			application/json:
			schema:
			$ref: "#/components/schemas/Error"
			/worldLinks/{worldLinkUUID}:
			get:
			summary: Find a link by his ID
			operationId: getWorldLinkById
			tags:
			- world links
			parameters:
			- name: worldLinkUUID
			in: path
			description: ID of the link to retrieve
			required: true
			schema:
			type: string
			responses:
			'200':
			description: Successful operation
			content:
			application/json:
			schema:
			$ref: '#/components/schemas/WorldLink'
			'400':
			description: Invalid ID supplied
			'404':
			description: World Link not found
			delete:
			summary: Deletes a worldLink
			operationId: deleteWorldLink
			tags:
			- world links
			parameters:
			- name: worldLinkUUID
			in: path
			description: link id to delete
			required: true
			schema:
			type: string
			responses:
			'200':
			description: OK
			'400':
			description: Invalid ID supplied
			'404':
			description: link not found
			components:
			schemas:
			Trackable:
			type: object
			required:
			- creatorUUID
			- trackableType
			- trackableEncodingInformation
			- trackablePayload
			- localCRS
			- unit
			- trackableSize
			- keyvalueTagList
			properties:
			UUID:
			description: A Universally Unique IDentifier identifying the trackable (RFC 4122)
			type: string
			format: uuid
			example: fa8bbe40-8052-11ec-a8a3-0242ac120002
			creatorUUID:
			description: A Universally Unique IDentifier identifying the creator of the trackable (a person, a team or a company)
			type: string
			format: uuid
			example: c75f6324-77a0-11ec-90d6-0242ac120003
			trackableType:
			description: Extensible list of trackable types possibly handled by complient World Storage implementation
			type: string
			enum: [FIDUCIAL_MARKER, IMAGE_MARKER, MAP, OTHER]
			example: FIDUCIAL_MARKER
			trackableEncodingInformation:
			$ref: '#/components/schemas/EncodingInformationStructure'
			trackablePayload:
			description: The data provided to create the trackable in a specific format handled by the World Storage service.
			type: string
			format: byte
			example: "10110101"
			localCRS:
			$ref: '#/components/schemas/Transform3D'
			unit:
			$ref: '#/components/schemas/UnitSystem'
			trackableSize:
			$ref: '#/components/schemas/Size'
			keyvalueTags:
			$ref: '#/components/schemas/KeyvalueTagList'
			WorldAnchor:
			type: object
			required:
			- creatorUUID
			- localCRS
			- unit
			- worldAnchorSize
			- keyvalueTagList
			properties:
			UUID:
			description: A Universally Unique IDentifier identifying the world anchor
			type: string
			format: uuid
			example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002
			creatorUUID:
			description: A Universally Unique IDentifier identifying the creator of the world anchor
			type: string
			format: uuid
			example: c75f6324-77a0-11ec-90d6-0242ac120003
			localCRS:
			$ref: '#/components/schemas/Transform3D'
			unit:
			$ref: '#/components/schemas/UnitSystem'
			worldAnchorSize:
			$ref: '#/components/schemas/Size'
			keyvalueTags:
			$ref: '#/components/schemas/KeyvalueTagList'
			WorldLink:
			type: object
			required:
			- creatorUUID
			- UUIDFrom
			- UUIDTo
			- transform
			- unit
			- linkSize
			- keyvalueTags
			properties:
			UUID:
			description: A Universally Unique IDentifier identifying the link
			type: string
			format: uuid
			example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002
			creatorUUID:
			description: A Universally Unique IDentifier identifying the creator of the link
			type: string
			format: uuid
			example: c75f6324-77a0-11ec-90d6-0242ac120003
			UUIDFrom:
			description: A Universally Unique IDentifier identifying a world anchor or trackable
			type: string
			format: uuid
			example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002
			UUIDTo:
			description: A Universally Unique IDentifier identifying a world anchor or trackable
			type: string
			format: uuid
			example: ce8ccd80-56ee-2a5c-a8a3-0242ac150d002
			transform:
			$ref: '#/components/schemas/Transform3D'
			unit:
			$ref: '#/components/schemas/UnitSystem'
			linkSize:
			$ref: '#/components/schemas/Size'
			keyvalueTags:
			description: List of additional parameters to be stored
			$ref: '#/components/schemas/KeyvalueTagList'
			example: { "LinkType" : ["Hierarchy"]}
			EncodingInformationStructure:
			required:
			- dataFormat
			- version
			properties:
			dataFormat:
			description: Identifier of the target framework
			type: string
			enum: [HOLOLENS, ARKIT, ARCORE]
			example : "HOLOLENS"
			version:
			description: The version of the format
			type: string
			example : "1.01"
			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: [-2, 1,-3, 4,
			4, 4, 4, 2,
			1, 0,-2, 1,
			-1,-2, 0, 0]
			UnitSystem:
			description: Unit of length
			type: string
			enum: [MM, CM, DM, M, DAM, HM, KM, INCH, FOOT, YARD, MILE]
			example: M
			Size:
			description: Size {width, length, depth}
			type: array
			items:
			type: number
			format: double
			minItems: 3
			maxItems: 3
			example: [1,5,0]
			KeyvalueTagList:
			description: List of additional parameters to be stored with the trackable.
			type: object
			additionalProperties:
			type: array
			items:
			type: string
			minItems: 1
			example: { "Place" : ["Museum 1"], "room" : ["B4"]}
			Error:
			required:
			- code
			- message
			properties:
			code:
			type: integer
			format: int32
			message:
			type: string

API/openapitools.json

0 → 100644

+7 −0

Original line number	Original line	Diff line number	Diff line
			{
			"$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
			"spaces": 2,
			"generator-cli": {
			"version": "5.3.0"
			}
			}

UseCases/Fraunhofer HHI/DTWIN-SEQ-AR17-AddTrackable.png

0 → 100644

+72.1 KiB

Loading image diff...

UseCases/Fraunhofer HHI/DTWIN-SEQ-AR17-AddTrackable.puml

0 → 100644

+96 −0

Original line number	Original line	Diff line number	Diff line
			@startuml

			participant "World Storage" as WS
			participant "Authoring Tool" as AT

			' THIS IS FOR SYSTEM A (3D-Reg)
			' -------------------------------

			WS <- AT: AR17-AddTrackable() - 3D-Registration (System B)

			rnote right AT
			Payload
			Creator UID (not possible, external app)
			+ Trackable Type (fiducial)
			+ Trackable Encoding Information (Aruco)
			+ Trackable Payload (no image saved)
			+ Local CRS (to the middle of the workbench)
			+ Unit System (mm)
			+ Trackable Scale
			+ KeyValue Tag List (table-id, end-device)
			end rnote

			activate WS

			WS -> WS : Extract features


			alt successful case
			rnote right WS
			Payload
			Unique Identifier
			end rnote
			WS -> AT: AR17-Trackable unique Identifier
			deactivate WS
			note right AT
			Stores the identifier with the Trackable in the scene graph
			end note
			else ERROR: Trackable all exceptions
			WS -> AT: AR17-Trackable return exception
			end

			' THIS IS FOR SYSTEM B (Unity)
			' -------------------------------
			WS <- AT: AR17-AddTrackable() - Unity (System B)

			rnote right AT
			Payload
			Creator UID (Unity Tag)
			+ Trackable Type (image)
			+ Trackable Encoding Information (Vuforia)
			+ Trackable Payload (png image of Vuforia marker, size)
			+ Local CRS (to the middle of the workbench)
			+ Unit System (meters)
			+ Trackable Scale
			+ KeyValue Tag List (linked to HoloLens space mapping)
			end rnote

			activate WS

			WS -> WS : Extract features


			alt successful case
			rnote right WS
			Payload
			Unique Identifier
			end rnote
			WS -> AT: AR17-Trackable unique Identifier
			deactivate WS
			note right AT
			Stores the identifier with the Trackable in the scene graph
			end note
			else ERROR: Trackable all exceptions
			WS -> AT: AR17-Trackable return exception
			end

			rnote left AT
			Registrated Nodes
			QUESTION:
			Is the 3d-pose (gridshell node) an object-trackable or a world anchor?

			Payload
			Unique Identifier
			+ Type = Node
			+ CAD-Identifier
			+ CAD-Name
			+ 3DT Position
			+ Bounding Box
			+ Ref to Gizmos Objects (position/rotation gizmos)
			+ Ref to annonations (info label)
			+ Logistic State (intern)
			+ Montage Seq
			+ Ticket State (public)

			end rnote
			@enduml

UseCases/Fraunhofer HHI/DTWIN-UseCases.png

0 → 100644

+76.4 KiB

Loading image diff...

Admin message