Abstract Assets Specification¶
1. Introduction¶
This document describes the "Abstract Asset" format used by various ARGO systems and products to define augmentations for documents and AR scenes.
History:¶
The "Abstract Asset" format is an evolution of previous Asset and Aura formats, allowing more flexibility in asset types.
It separates the asset properties into common properties, that all asset types share, and custom properties and resources specific to one asset type.
Schemas describe the custom properties and resources for each asset type. They are stored in a common location, and can be accessed by every software unit (editor, renderers, api) to know which custom properties to expect.
The "abstract" denomination refers to this generic and dynamic aspect.
Definitions:¶
In the context of assets, the following terms are used: - a property is an option which can be described by a single numerical value, a true/false value, a character string, a color, or an array of such values. Examples: the transparency color for a video; whether a 3d animation should play as a loop. - a resource is implemented by a file of a specific type, or an array of such files. Examples: the mp3 of an audio asset, the images of a gallery. - an action can be run of the asset by the Interaction Engine. Examples: starting the video of a video asset, passing an html in full-screen. - an event is emitted by the asset and can command actions in the Interaction Engine. Examples: the video of a video asset is finished.
2. Specification¶
2.1. Asset version 3.0¶
'aura' object ¶
| property | type | importance | description |
|---|---|---|---|
| api | string | mandatory | version of the format |
| schema | string | mandatory | name of the schema defining the custom properties / resources |
| id | string | mandatory | system id |
| name | string | mandatory | human-friendly label |
| active | boolean | mandatory | inactive assets are ignored by renderers |
| hidden | boolean | optional | hidden assets are not normally displayed, but can still be controlled programmatically |
| fixedRatio | boolean | optional | whether the dimensions hidden auras are not normally displayed, but can still be controlled programmatically |
| immutable | boolean | optional | immutatble assets are locked and cannot be edited |
| responsiveVisibility | responsiveness | optional | mobile/destop...; if not defined: displayed in every context |
| layerId | number | optional | if layers are defined, the layer this asset is included in |
| order | number | optional | rendering order; if not defined, the order the assets are parsed will be used |
| position | coordinates | mandatory | position of the asset |
| angles | angles | optional | rotation of the asset on its center; if not defined: no rotation |
| dimensions | dimensions | mandatory | dimensions of the area covered by the asset; not applicable for assets with a 3d view |
| properties | map of property values keyed by property name | optional | property names and types are defined in the asset type schema |
| resources | map of resource objects keyed by resource name | optional | resource names and types are defined in the asset type schema |
| iconVisible | boolean | optional | is_transparent on apibear, other ways to do it on Argoflow |
| language | language code | optional | for multilingual projects, if defined, the asset will only appear in this language |
'responsiveness' object ¶
| property | type | importance | description |
|---|---|---|---|
| desktop | boolean | mandatory | augmentation visible in desktop environment |
| mobile | boolean | mandatory | augmentation visible in mobile environment |
If the object exists, all known environments should have a value.
To ensure backward compatibility for future environments, environments not defined can be assumed as having a true value.
'coordinates' object ¶
| property | type | importance | description |
|---|---|---|---|
| x | number | mandatory | |
| y | number | mandatory | |
| z | number | optional |
'angles' object ¶
| property | type | importance | description |
|---|---|---|---|
| alpha | number | optional | |
| theta | number | optional | |
| psi | number | optional |
'dimensions' object ¶
| property | type | importance | description |
|---|---|---|---|
| width | number | mandatory | |
| height | number | mandatory |
property value ¶
A value of one of the following types: - scalar properties, - array of scalar properties of the same type,
scalar property value ¶
A value of one of the following types: - boolean, - number, - string, - string representing a color,
resource object ¶
| property | type | importance | description |
|---|---|---|---|
| filename | string | mandatory | |
| mimetype | string | optional | |
| filesize | number | optional | |
| url | string | optional | |
| base64 | string | optional |
url and base64 are exclusive, and one must always be defined.
'language' value ¶
A string representing a language code, for instance "fr", "en"...
2.2. Asset type definition version 3.0¶
'schema' object ¶
| property | type | importance | description |
|---|---|---|---|
| name | string | mandatory | technical reference, must be unique |
| label | translation object | mandatory | full human-friendly name of the schema in various languages |
| shortLabel | translation object | mandatory | short human-friendly name of the schema in various languages |
| family | asset type family | mandatory | group in the list of asset types in the editor (and possibly other places, as needed) |
| position | number | mandatory | position in the list of asset types in the editor (and possibly other places, as needed) |
| defaultIcon | string | mandatory | reference to the corresponding icon used in parts of the editor (and possibly other places, as needed) |
| icon | string | mandatory | reference to the corresponding icon used in parts of the editor (and possibly other places, as needed) |
| char | string | mandatory | reference to the corresponding icon font character used in parts of the editor (and possibly other places, as needed) |
| cssClass | string | mandatory | reference to the corresponding css class used in parts of the editor (and possibly other places, as needed) |
| properties | array of property definitions | mandatory | definition of the custom properties for this asset type |
| resources | array of resource definitions | mandatory | definition of the custom resources for this asset type |
| actions | array of action definitions | mandatory | definition of the custom actions for this asset type |
| events | array of events definitions | mandatory | definition of the custom events for this asset type |
translation object ¶
An object where: - property names are language codes - property values are the translations in the corresponding language
Not all languages need to be present, software units using the translations are supposed to have a fallback mechanism.
asset type family ¶
Possible values:
| string value | numerical value |
|---|---|
| "MEDIA" | 0 |
| "LINK" | 1 |
| "CTA" | 2 |
| "OTHER" | 99 |
Family and position affect the order in which asset types are listed in the editor toolbar, and possibly other places.
property definition ¶
Property definitions can have different options depending on the type of the property: - boolean property definition - number property definition - string property definition - color property definition - array property definition
They all share the same basic structure.
base property definition ¶
| property | type | importance | description |
|---|---|---|---|
| type | property type | mandatory | type of the property |
| name | string | mandatory | technical reference, must be unique |
| label | translation object | mandatory | human-friendly name of the property |
| managed | boolean | optional | in the editor, whether the property has a generated value which should not be directly edited by the user |
| required | boolean | optional | in the editor, whether a value is required |
| position | number | mandatory | in the editor, position of the editable field |
| hideLabel | boolean | optional | in the editor, whether the label should not be shown |
| inputFormat | string | optional | in the editor, a custom format pipe to apply to the input element |
| inputSize | number | optional | in the editor, an option to give to the input element |
| inputMaxLength | number | optional | in the editor, an option to give to the input element |
| enum | array of enum definitions | optional | if the property only accepts a fixed set of values, this defines the possible values |
| default | a property value | optional | when a new asset of this type is created, the property should receive this value |
| conditions | array of property condition objects | optional | for the editor, in which context the property should be hidden or disabled; if empty, the property is always editable (unless managed) |
property type ¶
A string with one of the following values:
| value |
|---|
| "boolean" |
| "number" |
| "string" |
| "color" |
| "array" |
scalar property type ¶
A string with one of the following values:
| value |
|---|
| "boolean" |
| "number" |
| "string" |
| "color" |
enum value definition ¶
| property | type | importance | description |
|---|---|---|---|
| value | an enumerable property value | mandatory | |
| label | translation object | optional | human-friendly representation of this enum value for the editor; if not present, the value is used |
| conditions | array of enumerable property condition objects | optional | for the editor, in which context the enum value should be hidden; if empty, the value is always shown |
enumerable property value ¶
A value of one of the following types: - number, - string,
enumerable property condition ¶
Conditions for enumeration values can only be conditions on the target renderer product
property condition ¶
Conditions for properties can be either: - conditions on the target renderer product - conditions on the value of another property
condition on target product ¶
Some properties or enum values are only applicable in the context of Argoflow or AR. A condition can be associated to the property definition or enum value list to reflect that.
| property | type | importance | description |
|---|---|---|---|
| effect | a condition effect | mandatory | |
| type | "product" | mandatory | |
| product | "AR" or "SL" | mandatory | another value (such as "none") can be used to set a property which will never appear in the editor |
condition effect ¶
| value | description |
|---|---|
| "visibility" | in the editor, the property or enum value is not visible |
| "enability" | in the editor, the property or enum value is visible but disabled (cannot be edited) |
condition on the value of another property ¶
Some properties should only be editable when another property has a specific value. A condition can be associated to the property definition to reflect that.
| property | type | importance | description |
|---|---|---|---|
| effect | a condition effect | mandatory | only "enability" is appropriate |
| type | "property" | mandatory | |
| name | string | mandatory | the name of the other property this property's editability depends on |
| values | an array of scalar values | mandatory | the values for which this property is editable |
boolean property definition ¶
Boolean property definitions are identical to the base property definition with the following set value:
| property | value |
|---|---|
| type | "boolean" |
number property definition ¶
Number property definitions extend the base property definition with the following set value:
| property | value |
|---|---|
| type | "number" |
and the following extra options:
| property | type | importance | description |
|---|---|---|---|
| minimum | number | optional | >= comparison |
| maximum | number | optional | <= comparison |
| exclusiveMinimum | number | optional | > comparison |
| exclusiveMaximum | number | optional | < comparison |
| multipleOf | number | optional | 1 for integers, 2 for even values, 5 for a step of 5... |
string property definition ¶
String property definitions extend the base property definition with the following set value:
| property | value |
|---|---|
| type | "string" |
and the following extra options:
| property | type | importance | description |
|---|---|---|---|
| minLength | number | optional | >= comparison |
| maxLength | number | optional | <= comparison |
color property definition ¶
Color property definitions are identical to the base property definition with the following set value:
| property | value |
|---|---|
| type | "color" |
array property definition ¶
Array property definitions extend the base property definition with the following set value:
| property | value |
|---|---|
| type | "array" |
and the following extra options:
| property | type | importance | description |
|---|---|---|---|
| items | an array property item definition | mandatory | defines the nature of this array items |
| minLength | number | optional | >= comparison |
| maxLength | number | optional | <= comparison |
array property item definition ¶
| property | type | importance | description |
|---|---|---|---|
| type | a scalar property type | mandatory | |
| enum | array of enumerable property value | optional | if the array only accepts a fixed set of values, this defines the possible values |
resource definition ¶
Resource definitions can have different options depending on the type of resource: - simple resource definition - array resource definition
They all share the same basic structure.
base resource definition ¶
| property | type | importance | description |
|---|---|---|---|
| type | resource type | mandatory | type of the resource |
| name | string | mandatory | technical reference, must be unique |
| label | translation object | mandatory | human-friendly name of the resource |
| role | resource role | optional | to indicate the resource requires special treatment |
| mediaType | media type | optional | for interraction with the Media Library |
| managed | boolean | optional | in the editor, whether the property has a generated value which should not be directly edited by the user |
| position | number | mandatory | in the editor, position of the resource selector |
resource type ¶
A string with one of the following values:
| value |
|---|
| "image" |
| "audio" |
| "video" |
| "html" |
| "model3d" |
| "vcard" |
| "file" |
| "array" |
Resource types and associated data (mime types, extensions...) could be fully dynamic, repeated for each resource definition in the schema, but since the default types have to be known by the default renderer/editor, we can hard-code the ones we need for legacy asset types.
resource role ¶
A string with one of the following values:
| value | description |
|---|---|
| "icon" | indicates this image resource is a cover icon for legacy asset types |
Used to unambiguously identify resources with special behaviors (mainly for the editor). At the moment: only the cover icon.
media library type ¶
A string with one of the following values:
| value | description |
|---|---|
| 0 | unknown |
| 1 | image |
| 2 | video |
| 3 | _3dobject |
| 5 | avatar |
| 6 | audio |
| 7 | vcard |
| 8 | agenda |
| 9 | file |
| 10 | button |
This is to support backward compatibility with the Media Library, but does not support the flexibility aimed at with the abstract assets implementation, and may be replaced in the future.
simple resource definition ¶
Simple resource definitions are identical to the base resource definition with the following restriction:
| property | value |
|---|---|
| type | any resource type except "array" |
array resource definition ¶
Array resource definitions extend the base resource definition with the following set value:
| property | value |
|---|---|
| type | "array" |
and the following extra options:
| property | type | importance | description |
|---|---|---|---|
| items | a resource array item definition | mandatory | defines the nature of this array items |
| minLength | number | optional | >= comparison |
| maxLength | number | optional | <= comparison |
resource array item definition ¶
| property | type | importance | description |
|---|---|---|---|
| type | resource type | mandatory | type of the resource |
action definition ¶
| property | type | importance | description |
|---|---|---|---|
| name | string | mandatory | technical name, from the list of actions supported by the Interaction Engine |
| label | translation object | mandatory | human-friendly name of the resource to display in the editor |
event definition ¶
| property | type | importance | description |
|---|---|---|---|
| name | string | mandatory | technical name, from the list of events supported by the Interaction Engine |
| label | translation object | mandatory | human-friendly name of the resource to display in the editor |