Extensible 3D (X3D)
Part 1: Architecture and base components

X. Annotation Component (Extension Proposal)

--- X3D separator bar ---

cube X.1. Introduction

1.1 Name

The name of this component is "Annotation". This name shall be used when referring to this component in the COMPONENT statement (see ISO FDIS 19775-1:200x 7.2.5.4 Component statement).

1.2 Overview

This clause describes the Annotation component of this part of ISO/IEC 19775. This includes how to include additional information as part of an X3D file that is beyond basic metadata, and may be displayed externally to the scene. Table X.1 provides links to the major topics in this clause.

Table X.1 — Topics

cube X.2 Concepts

X.2.1 Overview

Annotations occupy the information space between metadata provided by the core specification and the rendered visuals presented by the rest of the X3D specification. The goal is to provide the ability to include or give reference to large amounts of information that may be available in scene or, optionally at the browser implementer's choice, externally to the scene. Another term for annotations is "labelling" which implies purely in-scene information, where this specification seeks to provide both in and out of scene information display capabilities.

X.2.2 Representing Annotations

X.2.2.1 Parts of an Annotation

An annotation comes in three parts:

  1. The object that is being annotated
  2. The information to be associated with that object
  3. A visual connection between the two, such as a line

The line and information may be optionally presented by the browser. For example, a hide-away panel may be used to display annotations that are available for currently visible objects. In addition, the user is provided with an ability to describe the prefered policy for the browser to show annotations that are not currently visible, such as when they are behind the current viewpoint.

X.2.2.2 Coordinate System

The object that is being annotated will have the AnnotationTarget associated with the containing grouping node. This node is not renderable, but provides a point in the local coordinate system that forms the end point of the label's leader line on that object.

Annotations themselves are not part of the renderable scene graph. They may, optionally, exist anywhere and are not effected by the parent transformation heirarchy, such as switch or level of detail nodes. The AnnotationTarget node is effected by parent transformation heirarchy changes, including those that disable parts of the visible scene graph. When the parent heirarchy hides the renderable parts, the target and any associated lines are also hidden.

cube X.3 Abstract Types

X.3.1 X3DAnnotationNode

X3DAnnotationNode : X3DChildNode {
  SFString [in,out] annotationGroupID ""
  SFString [in,out] displayPolicy     "NEVER"  ["POINTER_OVER", "POINTER_ACTIVATE", "ALWAYS", "WHEN_VISIBLE", "NEVER"]
  SFBool   [in,out] enabled           TRUE
  SFNode   [in,out] metadata          NULL     [X3DMetadataObject]
}

This abstract node type is the base type for all node types that contain annotation information. The abstract type provides the facility to control the policy of when the annotation should be displayed to the user through the displayPolicy field. Additionally, a grouping label can be assigned to each annotation through the use of the annotationGroupID field.

Large files with many annotations can become unwieldy to view. Two options are available to control how and when annotations are to be made visible. The first option is to create a global filter list through the use of the annotationGroupID field. This is a text string that can be used to group sets of similar annotations together. It is recommended that plain, readable text is used for this field as a browser may make use of this for presenting in a list of filter options. The second option controls when an individual annotation will show based on user actions. These provide basic shortcuts without the user needing to use combinations of touch sensors and scripting. Several basic behaviours are available:

cube X.4 Node reference

X.4.1 AnnotationLayer

AnnotationLayer : X3DLayerNode {
  SFBool   [in,out] isPickable   TRUE
  SFNode   [in,out] metadata     NULL [X3DMetadataObject]
  SFNode   [in,out] viewport     NULL [X3DViewportNode]
  MFString [in,out] shownGroupID []
  MFString [in,out] layoutPolicy ""    [ "CIRCULAR", "DISPLAY_EDGE", ...]
}

A custom layer version that will provide automated layout of currently visible annotations and display them within the currently running scene.

The layer shows annotations directly in the scene and lays them out around the target object's reference point according to one of the pre-defined layout policies that are defined in the layoutPolicy field. This field contains a list of policies in priority order based on what the browser implementation supports. Browsers may also define implementation-specific policies in addition to the required policies. The reference point is projected into the layer's space and used as the location to base the annotations around. The defined policies are:

X.4.2 AnnotationTarget

AnnotationTarget : X3DChildNode {
  MFNode  [in,out] annotations    []       [X3DAnnotationNode]
  SFNode  [in,out] leadLineStyle  NULL     [X3DLinePropertiesNode]
  SFNode  [in,out] metadata       NULL     [X3DMetadataObject]
  SFVec3f [in,out] referencePoint 0, 0, 0  (-∞,∞)
  SFNode  [in,out] marker         NULL     [X3DShapeNode]
} 

Defines the target that annotations are associated with. A target applies to all siblings of the parent grouping node. If the parent or target has more than one parent transformation hierarchy, each shall be rendered individually, including leader lines and markers to each visual object.

Each target can have zero or more annotation nodes associated to it through the annotations field. All nodes referenced in this field are effected the position of this node's parent group in the world coordinates.

A grouping node may have more than one AnnotationTarget defined, each with different sets of Annotations.

Annotations are visually connected to the target through the use of a lead line if a node is defined for the leadLineStyle field. If no style is defined, a lead line is not shown then the annotation is shown with no connecting line. When a LineProperties node is provided and line ends are defined, the source end will be the target and the destination will be the annontation.

X.4.3 IconAnnotation

IconAnnotation : X3DAnnotationNode, X3DURLObject {
  SFString [in,out] annotationGroupID ""
  SFString [in,out] displayPolicy     "NEVER"  ["POINTER_OVER", "POINTER_ACTIVATE", "ALWAYS", "WHEN_VISIBLE", "NEVER"]
  SFBool   [in,out] enable			  TRUE
  SFNode   [in,out] metadata          NULL     [X3DMetadataObject]
  MFString [in,out] url               []
}

An annotation that is just iconic in form, using an image provided by the user.

The icon to be displayed is read from the url. When the URL field contains no values, the browser implementation may substitute a default icon, it its place. Browsers shall support the JPEG (see 2. [JPEG]) and PNG (see 2.[I15948]) image file formats. Details on the url field can be found in 9.2.1 URLs.

X.4.4 TextAnnotation

TextAnnotation : X3DAnnotationNode {
  SFString  [in,out] annotationGroupID ""
  SFString  [in,out] displayPolicy  "NEVER"  ["POINTER_OVER", "POINTER_ACTIVATE", "ALWAYS", "WHEN_VISIBLE", "NEVER"]
  SFBool    [in,out] enable			TRUE
  SFNode    [in,out] metadata       NULL     [X3DMetadataObject]
  SFString  [in,out] text           ""
  SFString  [in,out] contentType    "text/plain"
}

An annotation that contains inlined formatted text. The text may be one of several formats based on the defined MIME type in the contentType field. All browsers shall support the default plain text, and may support other content types (eg HTML).

X.4.4 URLAnnotation

URLAnnotation : X3DAnnotationNode {
  SFString  [in,out] annotationGroupID ""
  SFString  [in,out] displayPolicy  "NEVER"  ["POINTER_OVER", "POINTER_ACTIVATE", "ALWAYS", "WHEN_VISIBLE", "NEVER"]
  SFBool    [in,out] enable			TRUE
  SFNode    [in,out] metadata       NULL     [X3DMetadataObject]
  MFString  [in,out] url            []
}

An annotation that defines its content in another file.

The location of the other file is defined by the url field. This annotation is not required to be immediately loaded. A browser may choose to load the URL or just disply the URL for the user to select and load externally.

cube X.5 Support Levels

The Annotation component defines two levels of support as specified in Table X.2.

Table X.2 — Annotation component support levels

LevelPrequisitesNodes/FeaturesSupport
Level 1 Core 1
Grouping 1
Shape 1
Rendering 1
Networking 1
X3DAnnotationNode n/a
AnnotationTarget All fields fully supported
IconAnnotation All fields fully supported
URLAnnotation All fields fully supported
TextAnnotation All fields fully supported
Level 2 Core 1
Grouping 1
Shape 1
Rendering 1
Networking 1,
Layering 1
AnnotationLayer All fields fully supported
--- X3D separator bar ---
[ Xj3D Homepage | Xj3D @ Web3d | Screenshots | Dev docs | Dev Releases | Contributors | Getting Started ]
Last updated: $Date: 2007-09-14 23:41:37 $