Forge AR/VR Toolkit - the side project of our colleague Cyrille helping customers interested in bringing their designs from Forge into Unity - is still in beta, but for those of you living on the edge, let's take a fresh look at how this service can be used.
What you'll need
- Forge application with one or more 3D models already uploaded and translated, either in an OSS bucket, or in one of your hubs
- If these words don't make a lot of sense, check out our Learn Forge tutorial first!
- HTTP client such as Postman or cURL to communicate with the AR/VR Toolkit server
- Unity
- We'll be using version 2019.3.9f1 but you can use any version back to 2018.1
Authentication & Authorization
Instead of implementing its own authentication and authorization, the AR/VR Toolkit leverages the Forge Authentication service, so whenever working with the toolkit server or the Unity plugin, simply use access tokens generated by Forge. You can use either a 2-legged or a 3-legged token depending on where your designs are hosted.
Step 1: Create Scene
Before we can bring a 3D model from Forge into Unity, the AR/VR Toolkit first has to prepare it. This is done by creating and processing an "AR/VR scene". According to the API reference, the scene is used to specify:
- (required) URN of your input model in the Forge Model Derivative service,
- (optional) specific viewable of this model,
- (optional) project ID and version ID if the model sits in one of the Forge Data Management hubs,
- (optional) list of specific object IDs you want to include in the output,
- and other optional parameters
Let's take a look at two examples:
Creating a scene for a design in OSS
Let's say we have a model in an OSS bucket, already translated using the Forge Model Derivative service, and we want to create a new AR/VR scene called my-first-scene representing the entire design. We will use the PUT /arkit/v1/{urn}/scenes/{scene_id} endpoint with a 2-legged access token, and with a simple JSON body specifying the input model URN.
Note that the URN is specified twice: once in the request URL, and once in the request body.
# Replace $URN and $TOKEN with your values
curl --location --request PUT 'https://developer-api-beta.autodesk.io/arkit/v1/$URN/scenes/my-first-scene' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $TOKEN' \
--data-raw '{
"prj": {
"urn": "$URN"
}
}'
Creating a scene for a design in BIM360 Docs
Now, what if we want to create an AR/VR scene called my-other-scene from a design already hosted in a BIM360 project, and on top of that we want the scene to only include objects with the IDs 123 and 456? We use the same PUT /arkit/v1/{urn}/scenes/{scene_id} endpoint but this time with a 3-legged token, and with the BIM360 project ID and the version ID of our file (obtained from the Forge Data Management APIs) in the request body. We also include the (top-level) list property in the JSON body, specifying the only objects we want to include in the output:
# Replace $URN, $TOKEN, $PROJECT_ID, and $VERSION_ID with your values
curl --location --request PUT 'https://developer-api-beta.autodesk.io/arkit/v1/$URN/scenes/my-other-scene' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $TOKEN' \
--data-raw '{
"prj": {
"urn": "$URN"
"project_id": "$PROJECT_ID",
"version_id": "$VERSION_ID"
},
"list": [123, 456]
}'
Step 2: Processing Scene
With the AR/VR scene defined, we can now start the processing of its content using the POST /modelderivative/v2/arkit/job endpoint. In the payload of the request we specify the URN of the input model, and the AR/VR scene we want to process:
# Replace $URN, $TOKEN, and $SCENE with your values
curl --location --request POST 'https://developer-api-beta.autodesk.io/modelderivative/v2/arkit/job' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $TOKEN' \
--data-raw '{
"input": {
"urn": "$URN"
},
"output": {
"formats": [{
"type": "arkit",
"scene": "$SCENE"
}]
}
}'
Step 3: Check Scene Processing Status
Processing of the scene can take a while. Use the GET /modelderivative/v2/arkit/{urn}/manifest endpoint to retrieve a manifest similar to the one returned by the Model Derivative service, enriched with AR/VR Toolkit data:
# Replace $URN and $TOKEN with your values
curl --location --request GET 'https://developer-api-beta.autodesk.io/modelderivative/v2/arkit/$URN/manifest' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $TOKEN'
In the JSON output of the response, look for arkit to find the status of the AR/VR scene. It should be similar to the following:
...
{
"status": "success",
"outputType": "arkit",
"children": [
{
"view_id": "some-view-id",
"status": "success",
"type": "resource",
"name": "some-scene-id"
}
]
}
...
When the processing is done, you are ready to load the scene into your Unity application.
Step 4: Unity
First of all, let's include the AR/VR Toolkit plugin in our Unity project:
- Download https://github.com/wallabyway/ARVRToolkit/files/2602340/ForgeARKit-update-6-2018.1.unitypackage.zip, and rename the file to ForgeARKit-update-6-2018.1.unitypackage (the .zip extension is not needed)
- In Unity, use the Assets > Import Package > Custom Package... menu item, and import the entire folder structure of the .unitypackage file
Next, you'll want to insert a new "loader" - a special Unity prefab that can populate itself with a specific AR/VR scene - into your Unity scene:
- In the Project Explorer, navigate to Assets > Forge > Prefabs, and drag-and-drop the "Forge Loader" prefab into the scene
- Select the new loader object in the Hierarchy panel
- In the Inspector panel, locate the properties called Model URN, Access Token, and Scene ID, and fill them out with the values you used when setting up your AR/VR scene
And that's it! After running your Unity application, the loader object will use these configured properties to contact the AR/VR Toolkit server and start downloading individual geometries and textures building up your AR/VR scene.
Oh and btw, if you leave the Load Metadata property of the loader checked, the tree nodes of the loaded model will include the property metadata!
