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

API/openapi.yaml

0 → 100644

+491 −0

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