Tours for Grouped Assets
Usage
Authenticated users can perform the following operations for grouped assets through the Reality Cloud Studio:
- create a tour
- edit a tour
- view a tour
- delete a tour
- record a tour
- add new keyframes to a tour
- delete keyframes from a tour
The dr-tour microservice provides an API with endpoints for performing all the above operations, excluding the recording functionality, which is exclusively available in the Reality Cloud Studio.
API
Type definitions
The following type definitions specify the inputs and outputs of the GraphQL requests that will be described later.
Properties marked with an exclamation mark (!) are mandatory; the rest are optional.
Vector3Output {
x: Float!,
y: Float!,
z: Float!
}
TourCameraViewpointOutput {
eyePosition: Vector3Output!,
forward: Vector3Output!,
up: Vector3Output!
}
GroupedAssetPropertiesOutput {
visibleAnnotations: [ID],
visibleMeasurementAnnotations: [ID],
selectedLimitingBoxAnnotation: ID,
visibleArtifacts: [ID!],
}
GroupedAssetTourKeyframeOutput {
id: ID!
cameraViewpoint: TourCameraViewpointOutput!
tension: Float!
durationFromTourStart: BigInteger!
properties: GroupedAssetPropertiesOutput
}
GroupedAssetTourKeyframeInput {
cameraViewpoint: TourCameraViewpointOutput!
tension: Float!
durationFromTourStart: BigInteger!
properties: GroupedAssetPropertiesOutput
}
GroupedAssetTourOutput {
id: ID! # grouped asset tour ID
name: String! # tour name
description: String # tour description
createdBy: SimpleUserProfileOutput! # user that created the tour
createdAt: DateTime! # date and time the tour was created at
modifiedAt: DateTime! # date and time the tour was last modified at
canEdit: Boolean! # is true if the user can edit the tour
tension: Float! # the smoothness of the tour path
closed: Boolean # if true, the path is cloded
duration: Float! # duration of the tour
thumbnailPath: String # thumbnail path for the tour
keyframes: [GroupedAssetTourKeyframeOutput!] # tour keyframes
}Available requests
The mutations and the query that are available for the grouped asset tours, with their input and available output properties are documented below. The requests can return a subset of the output properties, so, when writing a new request, feel free to select the ones that are interesting for you.
1. Creating a tour
To create a tour entity, replace the following fields:
[GROUPED_ASSET_ID]:ID![NAME]:String![DESCRIPTION]:String[TENSION]:Float![CLOSED]:Boolean[KEYFRAMES]:[GroupedAssetTourKeyframeInput!]!
mutation {
createGroupedAssetTour(
params: {
groupedAssetId: [GROUPED_ASSET_ID]
name: [NAME]
description: [DESCRIPTION]
tension: [TENSION]
closed: [CLOSED]
keyframes: [KEYFRAMES]
}
) {
...GroupedAssetTourOutput
}
}Response:
{
id: "10101010-0101-1010-0101-101010101010",
name: "tour 01",
description: "a simple tour",
createdAt: "2023-04-03T12:23:24.253Z",
createdBy: "John Smith",
modifiedAt: "2023-04-03T12:23:24.253Z",
canEdit: true,
duration: 10,
closed: false,
tension: 0.5,
keyframes: [
{
id: "10101010-0101-1010-0101-101010101011" ,
durationFromTourStart: 5,
tension: 0.5,
cameraViewpoint: {
eyePosition: {
x: 6378244.391169676,
y: 12.128182872735361,
z: 4.1012340293932234
},
forward: {
x: 421234.39116963476,
y: -3.128182872735361,
z: 12.1012340293932234
},
up: {
x: 123456.391169676,
y: -4.128182872735361,
z: 14.1012340293932234
},
},
properties: {
selectedLimitingBoxAnnotation: null,
visibleArtifacts: [],
visibleLabelAnnotations: [],
visibleMeasurementAnnotations: [],
}
},
{
id: "10101010-0101-1010-0101-101010101012" ,
durationFromTourStart: 10,
tension: 0.5,
cameraViewpoint: {
eyePosition: {
x: 1608244.391169676,
y: -2.128182872735361,
z: 9.1012340293932234
},
forward: {
x: 101234.39116963476,
y: 9.128182872735361,
z: 14.1012340293932234
},
up: {
x: 45612.391169676,
y: -14.128182872735361,
z: 40.1012340293932234
},
},
properties: {
selectedLimitingBoxAnnotation: null,
visibleArtifacts: [],
visibleLabelAnnotations: [],
visibleMeasurementAnnotations: [],
}
}
]
}2. Creating the tour keyframes
To create a tour keyframe, replace the following fields:
[GROUPED_ASSET_ID]:ID[TOUR_ID]:ID[CAMERA_VIEWPOINT]:TourCameraViewpointOutput,[DURATION]:BigInteger,[TENSION]:Float,[PROPERTIES]:GroupedAssetPropertiesOutput
mutation {
createGroupedAssetTourKeyframe(
params: {
groupedAssetId: [GROUPED_ASSET_ID]
tourId: [TOUR_ID]
keyframe: {
cameraViewpoint: [CAMERA_VIEWPOINT]
durationFromTourStart: [DURATION]
tension: [TENSION]
properties: [PROPERTIES]
}
}
) {
...GroupedAssetTourKeyframeOutput
}
}3. Updating the tour
To update a tour entity, replace the following fields:
[GROUPED_ASSET_ID]:ID[TOUR_ID]:ID[NAME]:String[DESCRIPTION]:String[DURATION]:Float[TENSION]:Float[CLOSED]:Boolean
mutation {
updateGroupedAssetTour(
params: {
groupedAssetId: [GROUPED_ASSET_ID]
tourId: [TOUR_ID]
name: [NAME]
description: [DESCRIPTION]
duration: [DURATION]
tension: [TENSION]
closed: [CLOSED]
}
) {
...GroupedAssetTourOutput
}
}4. Updating the tour keyframes
To update a tour keyframe, replace the following fields:
[GROUPED_ASSET_ID]:ID![TOUR_ID]:ID![KEYFRAME_ID]:ID![KEYFRAME]:KEYFRAME!
mutation {
updateGroupedAssetTourKeyframe(
params: { groupedAssetId: [GROUPED_ASSET_ID], tourId: [TOUR_ID], keyframeId: [KEYFRAME_ID], keyframe: [KEYFRAME] }
) {
...GroupedAssetTourKeyframeOutput
}
}5. Recalculating the tour keyframes
To get a tour entity, replace the following fields:
[GROUPED_ASSET_ID]:ID![TOUR_ID]:ID![NEW_DURATION]:Float[DISTRIBUTE_EQUALLY]:Boolean
mutation {
recalculateGroupedAssetTourKeyframes(
params: {
groupedAssetId: "[GROUPED_ASSET_ID]"
tourId: "[TOUR_ID]"
newDuration: "[NEW_DURATION]"
distributeEqually: "[DISTRIBUTE_EQUALLY]"
}
) {
...GroupedAssetTourOutput
}
}6. Retrieving a tour
To get a tour entity, replace the following fields:
[GROUPED_ASSET_ID]:ID![TOUR_ID]:ID!
query {
getGroupedAssetTour(params: { groupedAssetId: "[GROUPED_ASSET_ID]", tourId: "[TOUR_ID]" }) {
...GroupedAssetTourOutput
}
}7. Deleting a tour
To delete a tour entity, replace the following fields:
[GROUPED_ASSET_ID]:ID[TOUR_ID]:ID
mutation {
deleteGroupedAssetTour(params: { groupedAssetId: [GROUPED_ASSET_ID], tourId: [TOUR_ID] })
}The mutation will return true if the tour was successfully deleted, or false if it was not or if we tried to delete a non-existent tour.
8. Deleting the tour keyframes
To delete a tour keyframe, replace the following fields:
[GROUPED_ASSET_ID]:ID[TOUR_ID]:ID[KEYFRAME_ID]:ID
mutation {
deleteGroupedAssetTourKeyframe(
params: { groupedAssetId: [GROUPED_ASSET_ID], tourId: [TOUR_ID], keyframeId: [KEYFRAME_ID] }
)
}The mutation will return true if the tour was successfully deleted, or false if not.
9. Creating the thumbnail for the tour
To create a tour thumbnail, replace the following fields:
[GROUPED_ASSET_ID]:ID[TOUR_ID]:ID
mutation {
createGroupedAssetTourThumbnail(params: { groupedAssetId: [GROUPED_ASSET_ID], tourId: [TOUR_ID] }) {
uploadUrl
path
}
}10. Deleting the thumbnail for the tour
To delete a tour thumbnail, replace the following fields:
[GROUPED_ASSET_ID]:ID[TOUR_ID]:ID
mutation {
deleteGroupedAssetTourThumbnail(params: { groupedAssetId: [GROUPED_ASSET_ID], tourId: [TOUR_ID] })
}The mutation will return true if the tour was successfully deleted, or false if not.
Apollo federation
The dr-tour microservice implements the federation of the type GroupedAssetOutput, through the grouped asset ID. This federation inserts a new field to GroupedAssetOutput, named tours. This is a paginated result of all the tours that have been created for this grouped asset.
Therefore, we have an additional request that can be used for the grouped asset tours:
Retrieving all tours for a grouped asset
query {
asset(params: { id: [GROUPED_ASSET_ID] }) {
appliedFilters {
byName
}
orderBy
pageNumber
pageSize
total
contents {
...GroupedAssetTourOutput
}
}
}JS-SDK reference
Tours
Tour services