Developer Guide

CraftAR Augmented Reality JSON Contents description

icon Date Developer Guide

icon Date Dec 22, 2020

icon author Catchoom Team

icon folder

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

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 tooltutorial for more details). The content object format has the following structure:

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.

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:

scale_fill aspect_fit aspect_fill
Image contents

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 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.

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.

Other optional attributes for video contents:

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:

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:

Related Posts in Developer Guide