This article describes the structure of the JSON object used for the contents description of an Augmented Reality scene. Depending on the SDK and the tool for creating the AR scene, the contents can be created in different formats for the SDKs and for Unity:
- JSON Contents for the Android and iOS SDKs and the phonegap/cordova plugin: contents for these SDKs can be created with the content creator web tool (see Adding AR content using the CraftAR Content Creation tool for more information).
- JSON Contents for the Unity SDK: AR items and their contents for the Unity SDK are created directly from Unity and uploaded to CraftAR. See Create and Publish items with Unity for more information.
JSON Contents for the Android and iOS SDKS and the phonegap/cordova plugin
This section describes the structure for the content JSON object that the CraftAR Augmented Reality SDKs for Android, iOS and phonegap/cordova can render as an Augmented Reality scene.
The CraftAR web content creator generates contents using this format so the SDKs are able to load the content assets and render the scene.
The content object consists of a list of content items. Each one of these content items represents one specific content (see the Adding AR content using the CraftAR Content Creation tool tutorial for more details). The content object format has the following structure:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
|
{
"version": 2,
"contents_v2": [
{
"id": "Image_Content_id",
"type": "image",
"image_url":"http://url_to_image"
. . .
},
{
"id": "Video_Content_id",
"type": "video",
"video_url":"http://url_to_mp4_file"
. . .
},
. . .
]
}
|
Common structure
This section describes the common attributes for all types of contents. Depending on the type, they will have other attributes which are explained in the following sections. Contents are by default placed in the center of the reference image. The CraftAR Augmented Reality SDKs can read different properties to modify a content’s position, rotation, scale and other attributes.
|
1
2
3
4
5
|
{
"id":"Image1",
"type":"image",
...
}
|
| Field name | Mandatory | Description | Type/Values |
|---|---|---|---|
| id | No | Identifier given to the content object being described. This field can be introduced to distinguish between two or more elements of the same type. It is intended for implementing custom visualization of the contents. | text |
| type | Yes | Defines the type of the content | text: image, video, 3dmodel, image_button |
| hyperlink_url | No | Destination url for the content | url |
| translation | No | Translation (x,y,z) using as unit the width of reference image. (Reference image width = 1) | Array[Float]: [0.0, 0.0, 0.0] |
| rotation_euler | No | [x, y, z], rotation angles in degrees | Array[Float]: [0.0, 0.0, 0.0] |
| rotation_matrix | No | 4×4 matrix transformation | Array[Float]: [1.0, 0.0, 0.0, 0.0, 0.0, 0.0, -1.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0] |
| scale | No | [x, y, z] proportion of reference image width. (ref image width = 1) | Array[Float]: [1.0, 1.0, 1.0] |
| wrap_mode | No | Defines how image, buttons and video contents are displayed over the reference, if set, it is incompatible with pose and scale attributes. | text: scale_fill, aspect_fit, aspect_fill |
| alpha | No | Defines a opacity level for the content. | 0.0-1.0 (clear-opaque) |
Content wrap modes
Flat contents (images, buttons and videos) may not have the same aspect ratio as the reference images. You can use the scale attribute to fit the image to the reference image. Alternatively, we provide an attribute to easily control how flat contents are adjusted to the dimensions of the reference image. Image contents represent an image to be shown in the AR scene. The image is not stored in the content itself, a URL to where the content is stored is provided through a mandatory attribute, image_url.Image contents
|
1
2
3
4
5
|
{
"id":"this image content id",
"type":"image",
"image_url":"http://url_to_image"
}
|
Image Button contents
Image Button contents represent a button that performs an action when clicked. Image buttons have two images, normal state and pressed state. The action taken from the hyperlink_url is to is show the URL contents in a browser window. This behaviour can be overridden in the SDKs to perform a different action when the buttons are clicked.
|
1
2
3
4
5
6
7
|
{
"id":"this button id",
"type":"image_button",
"button_url":"http://url_to_button_normal",
"button_pressed_url":"http://url_to_button_pressed",
“hyperlink_url”: “http://some_site”
}
|
Video contents
Video contents represent a video to be shown in the AR scene. The video is not stored in the content itself, a URL to where the content is stored is provided through a mandatory attribute, video_url. The video url must point to an mp4 file in the format supported by the SDKs.
|
1
2
3
4
5
6
|
{
"id":"this video id",
"type":"video",
"video_url":"http://url_to_mp4_file",
“uuid”: ”7b6...” // MANDATORY identifier for the content, used for caching the videos.
}
|
Other optional attributes for video contents:
|
1
2
3
4
5
6
7
|
{
…
"autoplay": true, // The video will be played at start (true by default)
"loop": true, // The video will start over again when finished
"muted": true, // The video will be played with no audio
"transparency_mask": true // use the lower half of the video as a transparency mask
}
|
The default behaviour in the AR mode will be that the video starts loading when the AR detects the reference, and plays as soon as it can start. When tracking is lost, the video will pause and start again when detected. When finished, it will keep the last frame until the tracking is lost, then it will seek to the start.
To know more about how we support videos with transparency in the CraftAR Service and in the SDKs, see how to add videos with transparency to Augmented Reality with CraftAR .
3D model contents
Although the CraftAR web content creator can only load Wavefront objects (OBJ), the SDKs can handle collada (.dae) models as well. Collada models can be set as contents for an AR item using a content object. See more on 3d models.
The format to specify 3D model content is as follows:
|
1
2
3
4
5
6
7
8
|
{
"id":"this 3d model id",
"type":"3dmodel",
"model_url":"http:/my_model_object_url",
"textures":{“model_texture_1”:"http:/my_model_texture_1_url"},..],
“mtl”: ”url”, // optional, for obj
“uuid”: ”7b6...” // MANDATORY identifier for the content, used for caching the models.
}
|
The model_url field is a link to the 3D model. Note that the extension is important to be able to import the model. The textures dictionary contains a list of key-values for the textures to be loaded for the model. The keys identify the texture inside the model file (name or path). The values specify the url from where the texture image has to be downloaded.
Custom content format
Some developers need to specify customized contents. The CraftAR Augmented Reality SDKs allow you to define custom content types and extend the AR content classes in order to extend the Augmented Reality experience. You can check the Augmented Reality SDK class documentation for iOS and Android for more information.
JSON Contents for the for Unity3d
The CraftAR Unity SDK uses a different format to load contents from the cloud. We use Unity’s Asset Bundles to export and upload unity assets into the apps at runtime. For this, we defined the following structure:
|
1
2
3
4
5
6
7
8
9
10
|
{
"contents_v2":[
{
"type":"unity_content",
"bundle_url_android":"http://url_to_my/android/assetbundle.unity3d",
"bundle_url_ios":"http://url_to_my/ios/assetbundle.unity3d"
}
],
"version":2
}
|