Annotation
Description of the annotation field¶
interface AnnotationState {
annotations: Annotation[]
selectedAnnotationId: string | undefined
focusedAnnotation: AnnotationFocused | undefined
awaitForPicking: boolean
annotationLabels: AnnotationLabel[]
isCurrentAnnotationLocked: boolean
currentlyEditedAnnotation: TemporaryAnnotationData | undefined
}
annotations¶
Updated by: UI
List of the Annotations to show on the 3D model.
Data model¶
interface Annotation {
cameraX: number
cameraY: number
cameraZ: number
cameraTargetX: number
cameraTargetY: number
cameraTargetZ: number
name: string
content: string
lastUp file: string
author: string
permissions: {
delete: string[]
readDescription: string[]
readDiscussion: string[]
readTargets: string[]
readTitle: string[]
writeDescription: string[]
writeDiscussion: string[]
writeTargets: string[]
writeTitle: string[]
}
writePermissions: string[]
readPermissions: string[]
tags: string[]
targets: AnnotationTargetPoint[]
targetObjects: AnnotationTargetPoint[]
id: string
unreadComments: number
attributes: Attribute[]
attributeMetadata: AttributeMetaData[]
label?: string
color?: [number, number]
shape?: number
}
Examples¶
Show no Annotation on the 3D model¶
Show one Annotation on the 3D model¶
{
"annotation":{
...
"annotations":[
{
"attributeMetadata":[],
"attributes":[],
"author":"61e6d38393821b78651614ff",
"cameraTargetX":-0.78828,
"cameraTargetY":0.31148,
"cameraTargetZ":0.702585,
"cameraX":14.309849,
"cameraY":9.074514,
"cameraZ":15.800714,
"content":"",
"date":1643706589957,
"file":"61f8f80d5d3c8d000b021eaf",
"folders":[],
"id":"61f8f8dda3d924000949dcd2",
"lastUpdate":1643706589957,
"name":"example",
"permissions":{
"_id":"61f8f8dda3d924000949dcd1",
"delete":[],
"readDescription":[],
"readDiscussion":[],
"readFolders":[],
"readTargets":[],
"readTitle":[],
"writeDescription":[],
"writeDiscussion":[],
"writeFolders":[],
"writeTargets":[],
"writeTitle":[]
},
"readPermissions":[],
"tags":[],
"targetObjects":[],
"targets":[
{
"_id":"61f8f8dda3d924000949dcd3",
"id":"61f8f8dda3d924000949dcd3",
"node":"61f8f80e445b5a000d09ce2c",
"nodeName":"Cube 1",
"position":{
"x":2.000003,
"y":1.129715,
"z":2.971601
},
"subsurfaceId":0,
"surfaceNormal":{
"x":0.21172,
"y":0.311482,
"z":0.702585
},
"surfaceUuid":"5b6ddfd7-5db2-5170-7594-1ba27c3bb1b0"
}
],
"type":0,
"unreadComments":0,
"writePermissions":[]
}
]
...
}
}
selectedAnnotationId¶
Updated by: Player/UI
ID of the selected Annotation.
The outline of the hotspot of the selected Annotation takes the color of its center to show it's selected.
Data model¶
Examples¶
Select an Annotation¶
Deselect the currently selected Annotation¶
Operations done by the Player¶
When the user selects or deselects an Annotation in the 3D view, the Player updates the field:
focusedAnnotation¶
Updated by: UI/Player
Asks the Player to focus the camera on an Annotation.
annotationId: ID of the Annotation to focus the camera on.targetId(optional):ID of the specific target point or target object of the Annotation to focus the camera on.duration: Duration of the focus animation in seconds.
Data model¶
interface AnnotationFocused {
annotationId: string | undefined
targetId: string | undefined
duration: number
}
Examples¶
Focus on an Annotation during 0.5 seconds¶
{
"annotation":{
...
"focusedAnnotation": {
"annotationId":"61f8f8dda3d924000949dcd2",
"duration":0.5
}
...
}
}
Focus on a specific target of an Annotation during 0.5 seconds¶
{
"annotation":{
...
"focusedAnnotation": {
"annotationId":"61f8f8dda3d924000949dcd2",
"targetId":"61f8f8dda3d924000949dcd3",
"duration":0.5
}
...
}
}
Operations done by the Player¶
The Player acknowledges the operation by deleting the field entirely.
awaitForPicking¶
Updated by: UI
Enable the Annotation picking mode. When it's enabled, each time the user clicks on a Node, the Player updates the field /annotation/currentlyEditedAnnotation with a temporary Annotation placed where the user clicked.
Data model¶
Examples¶
Enable the Annotation picking mode¶
annotationLabels¶
Updated by: Player
Maintains a one-to-one relationship with /annotation/annotations.
The Player doesn't show the label of the Annotation next to its hotspot when an Annotation is selected. This field allows the UI to show the label of the Annotation in the 3D view when it's selected.
annotationId: ID of the Annotation described by thisAnnotationLabel.name: Name or label of the Annotation (if it's customized by anAnnotationMetadata).enabled:trueif the Annotation is currently selected.viewportPosition: Position of the Annotation in pixels in the space of the 3D viewport.
Data model¶
interface AnnotationLabel {
annotationId: string
name: string
enabled: boolean
viewportPosition: {
x: number
y: number
z: number
}
}
Operations done by the Player¶
The Player automatically updates the list to match /annotation/annotations and to update its values when the Annotations move on the screen:
{
"annotation": {
...
"annotationLabels": [
{
"annotationId": "61f8f80e445b5a000d09ce2c",
"name": "Annotation 2",
"enabled": true,
"viewportPosition": {
"x": 640.399,
"y": 390.37,
"z": 21.36
}
}
]
...
}
}
isCurrentAnnotationLocked¶
Updated by: UI
Prevents the Player from automatically deselecting the currently selected Annotation (see /annotation/selectedAnnotationId) when the user clicks elsewhere in the 3D view.
Data model¶
Examples¶
Prevent the Player from deselecting the selected Annotation¶
currentlyEditedAnnotation¶
Updated by: Player
Contains a temporary Annotation when the Annotation picking mode is enabled (see /annotation/awaitForPicking) and the user clicks on a Node in the 3D view.
Two use-cases are supported:
- Updating an existing Annotation: If there's an Annotation currently selected (see
/annotation/selectedAnnotationId), the fieldscamera{x|y|z}andcameraTarget{x|y|z}are not set. - Creating a new Annotation: If no Annotation is currently selected, all the fields are set.
AnnotationTargetPoint corresponds to a Target Point placed where the user clicked in the 3D view.
Data model¶
interface TemporaryAnnotationData {
name: string
content: string
cameraX: number | undefined
cameraY: number | undefined
cameraZ: number | undefined
cameraTargetX: number | undefined
cameraTargetY: number | undefined
cameraTargetZ: number | undefined
targets: AnnotationTargetPoint[]
}
interface AnnotationTargetPoint {
id: string
node: string
nodeName: string
position: {
x: number
y: number
z: number
}
surfaceNormal: {
x: number
y: number
z: number
}
subsurfaceId: number
surfaceUuid: string
}
Operations done by the Player¶
The Player always deletes and creates the field entirely. It never updates it:
{
"annotation": {
...
"currentlyEditedAnnotation": {
"cameraTargetX": -0.7882795333862305,
"cameraTargetY": 0.3114798069000244,
"cameraTargetZ": 0.7025842666625977,
"cameraX": 14.252565383911133,
"cameraY": 9.14390754699707,
"cameraZ": 15.817441940307617,
"content": "",
"name": "Annotation 2",
"targets": [
{
"id": "1",
"node": "61f8f80e445b5a000d09ce2c",
"position": {
"x": 0.9445915222167969,
"y": 0.6485381722450256,
"z": 3.892573356628418
},
"subsurfaceId": 0,
"surfaceNormal": {
"x": -0.7882797718048096,
"y": 0.3114820420742035,
"z": 1.702585220336914
},
"surfaceUuid": "5b6ddfd7-5db2-5170-7594-1ba27c3bb1b0"
}
]
}
}
...
}