Userguide attached

------------------------------------------------------------



Vision 4K Design File Documentation

Documentation v. 1.0

Design file v.2.0


11-30-2017



Contents

  1. XML Layout1
  2. Sections2
  3. Configuration2
  4. Resolution2
  5. Orientation2
  6. Values2
  7. Assignment slots3
  8. Slot3
  9. Attributes3
  10. name3
  11. displayname3
  12. Elements4
  13. Element4
  14. Attributes4
  15. type (REQUIRED)4
  16. anchor (OPTIONAL, DEFAULT 0%,0%)5
  17. dimensions (OPTIONAL, DEFAULT 100%,100%)5
  18. z-index (OPTIONAL, DEFAULT 0)5
  19. valuetype (REQUIRED)6
  20. id (REQUIRED)6
  21. slot (OPTIONAL, DEFAULT NULL)6
  22. background (OPTIONAL, DEFAULT #00FFFFFF)7
  23. opacity (OPTIONAL, DEFAULT 100)7
  24. font (OPTIONAL, DEFAULT Arial)7
  25. fontsize (OPTIONAL, DEFAULT 12)7
  26. fontweight (OPTIONAL, DEFAULT normal)7
  27. fontstyle (OPTIONAL, DEFAULT normal)7
  28. fontcolor (OPTIONAL, DEFAULT #FF000000)7
  29. fonthalign (OPTIONAL, DEFAULT left)8
  30. fontvalign (OPTIONAL, DEFAULT top)8
  31. Sequences8
  32. Sequence8
  33. Attributes9
  34. type (OPTIONAL, DEFAULT normal)9
  35. assignment (OPTIONAL, DEFAULT NULL)9
  36. variable (OPTIONAL, DEFAULT NULL)9
  37. value (OPTIONAL, DEFAULT NULL)9
  38. looping (OPTIONAL, DEFAULT false)9
  39. length (OPTIONAL, DEFAULT -1)9
  40. Key9
  41. Attributes10
  42. start (REQUIRED)10
  43. element (REQUIRED)10
  44. assignment (OPTIONAL, DEFAULT NULL)10
  45. Actions11
  46. Anchor11
  47. Dimensions12
  48. ZIndex12
  49. Hidden12
  50. Opacity12
  51. Font12
  52. FontSize12
  53. FontColor13
  54. FontStyle13
  55. FontWeight13
  56. FontHAlign13
  57. FontVAlign13
  58. Background13
  59. VideoPlayback13
  60. ChangeSlot14
  61. Color format14


XML Layout

The XML file that makes out the design used in Vision 4K devices are divided into several subsections for ease of reading, and easy separation to be used in various parts of the Breece Cloud Enterprise platform.

The design XML file will always have a root element called Design:

<Design>

...

</Design>


In the following pages are descriptions of each section, as well as more in-depth descriptions of the various XML elements that each section can contain.

?

Sections


Configuration

The configuration section is framed by the Configuration XML elements:

<Configuration>

...

</Configuration>

The configuration section can contain the following child elements:


Resolution

The Resolution XML element is used to inform what resolution is meant to be used with the design contained in the design file. This element is only relevant when pixel values are used in Anchor (see anchor, page 5) and Dimensions elements (see dimensions, page 5) instead of percentage values.

The Resolution element MUST follow the architecture below, though the order of the child elements is irrelevant:

<Resolution>

<Width>3840</Width>

<Height>2160</Height>

</Resolution>

The Width element contains the intended pixel width of the screen the design is presented on.

The Height element contains the intended pixel height of the screen the design is presented on.


Orientation

The Orientation XML element is used to "rotate" the design orientation in relation to the screen in degrees. The value entered in the element will rotate the entire design clockwise in relation to the screen orientation.

<Orientation>0</Orientation>


Values

Possible values: 0, 90, 180 or 270

A value of 0 in Orientation will correspond to the "landscape" orientation as seen in other similar cases, i.e. the design will be orientated in the same way as the screen it is presented on.

A value of 90 in Orientation will rotate the design 90 degrees clockwise in relation to the screen and thus have the up vector of the design face the right side of the screen.

A value of 180 in Orientation will rotate the design 180 degrees clockwise in relation to the screen and thus have the up vector of the design face the bottom of the screen.

A value of 270 in Orientation will rotate the design 270 degrees clockwise in relation to the screen and thus have the up vector of the design face the left side of the screen.


Assignment slots

The assignment slots section is framed by the AssignmentSlots XML elements:

<AssignmentSlots>

...

</AssignmentSlots>

The assignment slots section can only contain Slot child elements (see below). There is no limit as to how many slots this section can contain.


Slot

The Slot XML element is used to create a "map" in which can be assigned a static value, such as a video link, an image link or a product number that the design can refer to when setting up Elements (see element, page 4).

<Slot name="VIDEO_1" displayname="Background video" slotType="video" />

This assignment is done through the GUI and is meant for the user to be able to "attach" or assign an image, video or a product to the design. For example for use as a common background video, a company logo or the like.

Possible slotTypes: "video", "image", "product".


Attributes

Attributes are used to set specific options for an element. Certain attributes are only relevant to certain types (see valuetype, page 6) of elements. If an attribute is irrelevant to the value type, it is simply ignored.

Below are descriptions for the attributes.


name

The name attribute is the label that the design can use to refer to the value assigned to the slot. (Mandatory)


displayname

The displayname attribute is an easy-to-read representation of the slot. Generally to make the name of the slot more readable to the user, for example for presentation in a GUI. (Mandatory)



Elements

The elements section is framed by the Elements XML elements:

<Elements>

...

</Elements>

The Elements section is where the initial design layout is set up. The elements section will contain only Element child elements (see below). This section can contain any number of child elements.


Element

<Element type="video" anchor="0%,0%" dimensions="100%,100%" z-index="0" valuetype="assignment" id="backgroundVideo" slot="VIDEO_1" />

The Element XML element is used to represent any type of display element, and can be thought of as a clear box meant to contain some sort of visual content.

An Element XML element is defined through the use of a range of attributes (see below for attribute descriptions), of which the type of Element (element type is determined through an attribute) determines are relevant. Attributes that are not relevant to a given element type will be ignored. Certain attributes are relevant to all types of elements (this will be noted in the attribute descriptions below).


Attributes

type (REQUIRED)

<Element type="video" />

Element types: all.


Indicates the type of element. The type of element determines the capabilities of the element.

This attribute is REQUIRED for each element, and the design will fail validation if it is not set.


At the time of writing, the supported element types are: Barcode_ean13, barcode_qr, Canvas, Image, Text and Video - more will be added continually. Refer below for further description of each type of element.

  • -Barcode_ean13: This type of element is meant to contain a pre-rendered barcode image, based on the value of the element, like for example a product number, usually through the use of variables (see valuetype, page 6). More types of barcodes are expected to be supported within a short period of time. These will be named Barcode_<EAN TYPE>.
  • -Barcode_qr: This type of element is meant to contain a pre-rendered QR code image, based on the value of the element, like for example a product number, usually through the use of variables.
  • -Canvas: This element type is meant to be a container for other elements. Whenever elements are contained in a canvas, their anchor and dimensions attributes are relative to the parent canvas, and not the screen itself, as they normally would be. Whenever a canvas element is referred to in the sequence, the child elements will undergo the same actions as the parent canvas, unless overridden specifically in the child element.

For example, if a canvas contains two child elements and the parent canvas is set to opacity 50, the child elements will go transparent as well.

  • -Image: This type of element is meant to hold an image to display on the screen. The link to the image can either be set in the value of the element statically, can be based on product data, by the use of variables, or through assignments (see valuetype, page 6)
  • -Text: This type of element is meant to hold a text of some sort. By default the background of the element will be transparent, enabling the element to be used as an overlay, but it doesn't have to be (see background, page 7). The text can be set in the element value statically or can be referred to through variables (see valuetype, page 6).
  • -Video: This type of element is meant to hold a video. Like with an image element, the link to the video can be set in the element value, can be referred to with variables or through assignments (see valuetype, page 6)


anchor (OPTIONAL, DEFAULT 0%,0%)

<Element anchor="0%,0%" />


Element types: all.

Anchor is the location of the top-left corner of an element. The anchor can be set using pixel values, or percentage values. The anchor consists of two numbers, separated by a comma. The first number is the horizontal position, the second number is the vertical position. The anchor location is in relation to the parent. If there is no parent, the screen is assumed to be the parent.

For example, an element with an anchor of 50%, 50% will have the top-left corner of the element located exactly in the middle of the parent. The anchor values are assumed to be in pixel-values unless the numbers are followed by a percentile sign (%). The default values are 0%,0%.


dimensions (OPTIONAL, DEFAULT 100%,100%)

<Element dimensions="100%,100%" />

Element types: all.


Dimensions are the physical dimensions of the element. The dimensions can be set using pixel values, or percentage values. The dimensions consists of two numbers, separated by a comma. The first number is the width of the element, the second number is the height. The dimensions has the origin set in the anchor, as described previously, and will extend right and down from the anchor. The dimensions is in relation to the parent. If there is no parent, the screen is assumed to be the parent.

 For example, an element with dimensions of 50%, 50% will take up space equivalent to one-half the width and one-half the height of the parent. The dimensions values are assumed to be in pixel-values unless the numbers are followed by a percentile sign (%).

z-index (OPTIONAL, DEFAULT 0)

<Element z-index="0"/>


Element types: all.

Z-index determines the layers of the elements. The higher the Z-index of the element, the more "on top" the element is. If drawing two overlapping elements, element 1 (z-index=2) and element 2 (z-index=1), element 1 will appear to be on top of element 2, as the Z-index is higher.

valuetype (REQUIRED)

<Element valuetype="assignment" />


Element types: image, text, video.


Valuetype indicates how to process the value of the element. There are three types of values available to the design: Assignment, Static and Variable.


This attribute is REQUIRED for each element, and the design will fail validation if it is not set.


See below for the differences between the types.


  • -Assignment: An assignment value means that the design should refer to the AssignmentSlots section to find the corresponding assignment with the name referred to in the value, and insert the assigned value in the element value. The element type and the assigned value must match each other, i.e. a text element cannot display an assigned image.
  • -Static: A static valuetype means that the value is hardcoded into the design. This could be a static background image, a label text or a background video that should never change through user interaction (Sequences can change the value of a static field (see sequence, page 8))
  • -Variable: a variable valuetype means that the element values will be collected, or compiled, from product data. Product data variables are encased in square brackets ( [ and ] ) A variable value can be from a product variable alone, or can be combined with a static text, with product variables injected into the text.

For example, the element value "Some test text, displaying [PRODUCTSAMPLEDATA] from product [PRODUCTNUMBER]" is a compiled value, using both static text and an injected variable. As can be seen in the example above, more than one variable can be referred to. In order to use product data variables, an assigned product MUST be set in the sequence (see sequence, page 8) referring to the element.


id (REQUIRED)

<Element id="backgroundVideo" />


Element types: all.

Id is a textual reference to the element that the sequence (see sequence, page 8) can use to refer to the element it is supposed to be working on.

This attribute is REQUIRED for each element, and the design will fail validation if it is not set.

slot (OPTIONAL, DEFAULT NULL)

<Element slot="VIDEO_1" />


Element types: image, text, video.

The slot attribute refers to the assignment slot that the user has assigned a value to, from which the element should retrieve its content/value. The element type and the assigned value in the assign slot must match each other, i.e. a text element cannot display an assigned image. If an element is set to type Assignment and the slot attribute is empty or not set, the design will not show the element.


background (OPTIONAL, DEFAULT #00FFFFFF)

<Element background="#00FFFFFF" />


Element types: canvas, text.

The background color of the element. For a description of the color format see color format, page 9.

opacity (OPTIONAL, DEFAULT 100)

<Element opacity="100" />


Element types: canvas, image, text, video.

Opacity sets the transparency of an element, including the content. Transparency is based on a value ranging from 0 (completely transparent) to 100 (completely opaque).

font (OPTIONAL, DEFAULT Arial)

<Element font="Arial" />


Element types: text.

The font attribute sets the name of the font family to use when rendering text. This value can be set to any font family that is installed in the host system running the Vision 4k software. If a value is set to a font family that is not installed in the system, the element will revert to its default value.

fontsize (OPTIONAL, DEFAULT 12)

<Element fontsize="12" />


Element types: text.

The fontsize attribute sets the scale of the font when rendering text. The fontsize can be set using pixel values (px postfix) or point (pt postfix) values. If no postfix is appended to the value, point values are assumed.

fontweight (OPTIONAL, DEFAULT normal)

<Element fontweight="normal" />


Element types: text.

The fontweight attribute sets the weight of the font. Possible values are: light, normal, bold.

fontstyle (OPTIONAL, DEFAULT normal)

<Element fontstyle="normal" />


Element types: text.

The fontstyle attribute sets the visual style of the font. Possible values are: normal, outline, italic, underline.

When fontstyle = "outline" then also use "fontoutlinecolor" e.g. fontoutlinecolor = "#FF00FF"

When fontstyle = "outline" then also possible to use "fontoutlinewidth" e.g. fontoutlinewidth = "2" (pxl)

Default fontcolor is #FF000000 but if a fontstyle = "outline" then the fontcolor is default transparent.


fontcolor (OPTIONAL, DEFAULT transparent)

<Element fontcolor="#FF000000" / >


Element types: text.

The fontcolor attribute sets the color of the font when rendering text. For a description of the color format see color format, page 9.

fonthalign (OPTIONAL, DEFAULT left)

<Element fonthalign="left" />


Element types: text.

The fonthalign attribute sets the horizontal alignment of text when rendering. Possible values are: left, center, right.

fontvalign (OPTIONAL, DEFAULT top)

<Element fontvalign="top" >


Element types: text.

The fonthalign attribute sets the vertical alignment of text when rendering. Possible values are: top, center and bottom.


Sequences

The sequences section is framed by the Sequences XML elements:

<Sequences>

...

</Sequences>

The Sequences section is where the visual result is compiled.

The sequences section will contain only Sequence child elements (see below). This section can contain any number of child elements.

If there are several sequences, the sequences will be played in the order they are entered in the configuration. If a sequence, that is not last in the list, is set to looping, the list of sequences will terminate there, and the list of sequences will start over at the end of the sequence that is set to looping. If a conditional sequence is in the list, where the condition is not met, the sequence is skipped and the next sequence is run.


Sequence

<Sequence type="conditional" assignment="PRODUCT_1" variable="PROMO" value="0" looping="true" length="30000">

</Sequence>

A sequence is a list of keys (see key, page 9) that can alter certain properties of an element at a specific point in time, thus creating effects, animations, value changes, etc. inside an element.

A sequence can be triggered from conditions, if so required. For example, it is possible to have a sequence that only runs if a certain product data value is set at a specific value.

A sequence can contain any number of keys, each key representing the state of a single element at a single point in time, during that sequence.


Attributes

A sequence has a number of attributes available to it, to configure it to perform a specific function or behavior:


type (OPTIONAL, DEFAULT normal)

The type of the sequence. At the time of writing, there are 2 types of sequences; normal and conditional.


If normal is set, the sequence will run no matter what.


If conditional is set, it is possible to set a certain condition that has to be met for the sequence to run. This could be a check if a certain field in the product data contains a specific value.


In order for a condition to work, the attributes assignment, variable and value must be set.


assignment (OPTIONAL, DEFAULT NULL)

The assignment attribute is used to indicate which assignment to refer to when checking to see if a condition is met. The assignment attribute should refer to one of the slots in the assignment slots section.


This attribute is only relevant if a conditional sequence type is chosen.


variable (OPTIONAL, DEFAULT NULL)

The variable attribute is used to indicate which field in the chosen assignment is used as a reference to see if a condition is met. The variable attribute should be set to an existing field in the assignment chosen.


This attribute is only relevant if a conditional sequence type is chosen.


value (OPTIONAL, DEFAULT NULL)

The value attribute is the value that the chosen assignment and variable field must be in order for the condition to trigger. If the chosen assignment and variable field matches the value in the value attribute, the condition is considered met, and the sequence will be chosen as the running sequence.


This attribute is only relevant if a conditional sequence is chosen.

looping (OPTIONAL, DEFAULT false)


The looping attribute indicates whether or not the sequence should start over when it has finished running its full length. Possible values are true and false.

length (OPTIONAL, DEFAULT -1)

The length attribute indicates the length of time that the sequence should run in milliseconds. If the attribute is set to -1, the sequence will run for the duration of the longest video, or to the last key in the sequence, whichever is longest.

For example, a value of 30000 will make the sequence run for 30 seconds, and then stop, regardless of remaining keys or video duration.


Key

<Key start="0" element="backgroundVideo">

A key is a description of an element's state at a given point in time.

It is a set of instructions for an element on properties to change, such as position, dimensions, text values or the like.

A key can contain child elements that indicate actions to be taken at the time associated to the key. These actions are meant to alter the properties or attributes of an element, such as move the element from one position to another.

As an example, element A is referred to by two keys: one at the beginning of the sequence, and one at the end.

The first key has no child elements, meaning that at the beginning of the sequence, the element A is unchanged from its default values, set in the elements section.

The second key has an anchor child element, indicating that at the end of the sequence, the element A will have changed position to the anchor position indicated in the child element.

When the sequence runs, it gradually moves the element from the original anchor position indicated as the default position to the anchor position indicated in the last key, interpolating the position of the element over time as the sequence runs.


Attributes

A key has a number of attributes available to it:


start (REQUIRED)

The start attribute indicates where in the sequence it is located, and when during that sequence's runtime it should perform its actions. The start attribute is in milliseconds. For example, if a sequence is required to perform some sort of action on an element after 5 seconds of running, a key would be added to the sequence with a start attribute of 5000.


element (REQUIRED)

The element attribute is where it is configured to which element the key belongs. This attribute refers to the element in the elements section that has the corresponding id attribute entered into the element attribute of the key.


assignment (OPTIONAL, DEFAULT NULL)

The assignment attribute is where a specific assignment is attached to an element. It is possible for assignments to change over time. The assignment attribute refers to the entries in the assignment slots section.


For example, it is required for an element to show the price of product A at the beginning of a sequence, and after 10 seconds change to the price of product B and after another 10 seconds, change to the price of product C. Three keys are required to perform this functionality.

The first key, tied to the element, set with a start attribute of 0 and assignment attribute of Product_A. No child elements are required, as the element already has the product data field mapped.

The second key, tied to the element, set with a start attribute of 10000 and assignment attribute of Product_B. No child elements are required, as the element already has the product data field mapped.

The third key, tied to the element, set with a start attribute of 20000 and assignment attribute of Product_C. No child elements are required, as the element already has the product data field mapped.

Optionally, if so required, a fourth key, tied to the element, could be added to the sequence with a start attribute of 30000 and no other attributes. This would indicate the end of the sequence, so that if the sequence is set to looping, it would restart the sequence, and perform all the actions over and over again. Alternative to the fourth key, the sequence length could be set to 30000, which would achieve the same result as having the fourth key.

If neither sequence length, nor the fourth key was set, but the sequence is a looping sequence, product C would only be showing for a fraction of a second before the sequence starts over, as there is no indication as to how long product C should be assigned to the element.

  • <Sequence looping="true" length="30000">
  • <Key start="0" element="productPrice" assignment="PRODUCT_A">
  • </Key>
  • <Key start="10000" element="productPrice" assignment="PRODUCT_B">
  • </Key>
  • <Key start="20000" element="productPrice" assignment="PRODUCT_C">
  • </Key>
  • <Key start="30000" element="productPrice">
  • </Key>
  • </Sequence>


Actions

Action are children to the keys. They indicate a state change, or action, to be performed on the element that the parent key refers to.


Actions refer to certain properties of an element that can be manipulated at the specific time set in the key.

<Key start="0" element="normalPriceContainer" assignment="PRODUCT_1">

<Hidden>false</Hidden>

</Key>

Certain actions are relevant only for certain types of elements.


The following action elements are available:

Anchor

<Anchor>25%,25%</Anchor>

Element types: all.

Changes the anchor attribute of an element to the value set in the action.


Dimensions

<Dimensions>15%,25%</Dimensions>

Element types: all.

Changes the dimensions attribute of an element to the value set in the action.


ZIndex

<ZIndex>3</ZIndex>

Element types: all.

Changes the z-index attribute of an element to the value set in the action.


Hidden

<Hidden>true</Hidden>

Element types: all.

Hides or shows the element. Possible values are true and false.


Opacity

<Opacity>80</Opacity>

Element types: all.

Changes the opacity attribute of the element to the value set in the action.


Font

<Font>Calibri</Font>

Element types: text.

Changes the font attribute of an element to the value set in the action.


FontSize

<FontSize>18</FontSize>

Element types: text.

Changes the fontsize attribute of an element to the value set in the action.


FontColor

<FontColor>#FFFF0000</FontColor>

Element types: text.

Changes the fontcolor attribute of an element to the value set in the action.


FontStyle

<FontStyle>Italic</FontStyle>

Element types: text.

Changes the fontstyle attribute of an element to the value set in the action.


FontWeight

<FontWeight>bold</FontWeight>

Element types: text.

Changes the fontweight attribute of an element to the value set in the action.


FontHAlign

<FontHAlign>center</FontHAlign>

Element types: text.

Changes the fonthalign attribute of an element to the value set in the action.


FontVAlign

<FontVAlign>bottom</FontVAlign>

Element types: text.

Changes the fontvalign attribute of an element to the value set in the action.


Background

<Background>#FFFFFFFF</Background>

Element types: canvas, text.

Changes the background attribute of an element to the value set in the action.


VideoPlayback

<VideoPlayback action="start" />

Element types: video.

Performs a given action on a video element. This can be to start, stop or pause the video playback.

Possible values are start, stop and pause.


ChangeSlot

<ChangeSlot>IMAGE_3</ChangeSlot>

Element types: any non-text static valuetype element with slot attribute set.

Changes the slot attribute of an element to the value set in the action.


Color format

The color format used when referring to a color in the design file will all be of the #ARGB format. Each channel consisting of a double-digit hexadecimal number. The first two digits is the Alpha channel. The second two digits is the Red channel. The third two digits is the Green channel and the last two digits are the Blue channel. The color format MUST be prefixed with a hash character (#).

Each pair can range from 00 to FF, and will indicate how pronounced that channel is in the final output of the color. The Alpha channel works as a transparency channel where 00 is completely transparent, and FF is completely opaque.

Example: #FFFF0000 is a fully opaque deep red color while #7F0000FF is a half-transparent deep blue color.