Annotations

Annotations

You (as a developer) have an option to augment the Reel scene with custom text & graphics features, which eventually is also synchronized with frames on the scene - annotations. These can be defined as members of annotations option of .reel(). It accepts a simple object defining all annotations.

.reel({
    annotations: {}
})

Annotations then get rendered as Reel image's siblings inside .reel-overlay container. Each annotation ultimately is an absolutely positioned <div> node containing image, link or a simple text.

Definiton of Annotation(s)

Pick a name for the annotation. It will further be used as DOM id for the annotation, so make sure it is document-wide unique. For example let's use "copyright":

    annotations: {
        "copyright": {}
    }

Express the desired position of the absolutely positioned annotation node as X and Y coorditates in x and y. For example, let's place its upper-left corner exactly in half horizontaly and 6 pixels from the top edge:

        "copyright": {
            x: "50%",
            y: 6
        }

Ultimately, x and y are all you need to get the annotation node drawn and displayed. However, it's still empty.

Content

Image

Sometimes words aren't enough and you need an image. Using the image attributes property you can inject an <img> tag. Attributes property is a map of attributes and their values exactly like the one jQuery's .attr() would accept. For example, a 100 x 50 PNG image file:

            image: {
               src:    "path/to/my_image.png",
               width:  100,
               height: 50
            }

Link

Sometimes you will want the annotation be a link somewhere else or to another Reel. There's a link attributes property for just that, which translates to <a> tag. For example, let's create a working half opaque link to image author's e-mail:

            link: {
                href:  "mailto:mailbox@example.org",
                text:  "mailbox@example.org",
                style: {
                    opacity: 0.5
                }
            }

Image Link

Combining both image, and link properties results in <img> tag (defined by image) wrapped tightly into <a> tag (defined by link). For example, let's have a clickable image:

            image: {
                src:  "path/to/my_image.png"
            },
            link: {
                href: "pointer/to/some/location/"
            }

Text

For simple text annotation the node attributes property resulting in a <div> tag is used. Annotation node is rendered for each and every annotation and wraps the image and/or link eventually. Using text (or html) attributes you can add content. For example, let's make it hold simple copyless text with a mouse over hint title and a custom class for some groovy CSS:

            node: {
                html:    "© 1961 John Doe",
                'class': "my_groovy_copy",
                title:   "Some rights reserved"
            }

Eventual id attribute is excluded from the node attributes property as it is automatically filled with the annotation name.

Outside World Node

In special cases you may also want the annotation to appear outside the Reel image "world". For that the node property can also accept jQuery object pointing to any DOM element(s) of the page. For example, let's say we want to use DOM element with id attribute equal to "any_node_anywhere":

            node: $('#any_node_anywhere')

Style

You can very easily customize annotation's looks with regular CSS by referencing to it's DOM elements using their ids (annotation names) in your stylesheet. For example let's make our "copyright" annotation bold white text on red background:

#copyright {
    font-weight: bold;
    color: white;
    background: red;
}

Synchronization With Frames

Visibility

Generally you don't get everything visible within one angle in a 360° scene. To specify on which frame the annotation subject enters and exits the visible span use start and end - they mark first and last frame with the annotation visible. For example, let's have the annotation visible only on frames 4, 5, 6, 7 and 8:

            start: 4,
            end:   8

Placement

During "reeling" the annotated subject moves around the stage, changing one or both its dimensions. Frame-based definition of position is desirable to accurately track the subject as it travels through the stage. For this matter, both x and y members can instead of number/string be Arrays of numbers/strings. The first value from the array would be used for the start and the last for the end frame. For example, let's track something travelling east-bound and maintaining vertical position for 4 frames:

            x: [ 5, 25, 50, 80 ],
            y: 100

Style

Actual frame is propagated to the wrapping node via class name attribute frame-X, where X is the number of the frame. For example, to fade the #copyright annotation 50% just for the 8th frame put this into your stylesheet:

.frame-8 #copyright {
    opacity: 0.5;
}

Advanced Synchronization

Visibility via Placement

Unless both X and Y annotation coordinates are defined for a frame, the annotation is hidden. You can do this intentionaly by using undefined positions. First array item represents frame 1. For example, let's have the annotation fly right and left and skip being visible at frames 4, 5, 9 and 10:

            x: [ 5, 10, 15, undefined, undefined, 15, 10, 5, undefined, undefined ]

You can always just skip a value in the Array to have the value undefined. The Array below is the shorter equivalent of the above:

            x: [ 5, 10, 15, , , 15, 10, 5 ]

Visibility Switching

To control visibility of a positionaly static annotation, you can use the at option. It accepts a string where each character (+ or -) represents a frame and switches the annotation on/off for that frame. For example, let's show the annotation on frames 1, 3, 6 and 8:

            at: '+-+--+-+'