= FDO RFC 60 - Add OGC Annotation Support to the FDO API =

This page contains a request for comments document (RFC) for the FDO Open Source project.  
More FDO RFCs can be found on the [wiki:FDORfcs RFCs] page.

== Status == 
 
||RFC Template Version||1.1||
||Submission Date||April 13, 2011||
||Last Modified||Greg Boone, April 13, 2011||
||Author||Greg Boone||
||RFC Status||Not Ready For Review||
||Implementation Status||Not Started||
||Proposed Milestone||3.7.0.0||
||Assigned PSC guide(s)||Greg Boone||
||'''Voting History'''||(vote date)||
||+1||||
||+0||||
||-0||||
||-1||||
 
== Overview ==

The RFC is being proposed in order to add formal OGC Annotation Support to the FDO API.

Since the FDO API will continue to be used by muliple types of clients as an interchange format, support for annotation/cartographic text will evenetually need to be added to the FDO API, and exposed through our providers. 

The FDO representation of Annotation Text will be based (as closely as possible) on the OGC specification for cartographic text. The initial requirement would be to support the capabilities of Annotation Text so that the editing representation in our client would round-trip with full fidelity.

== Motivation ==

Spatially placed text is a common requirement of applications. Many application have stored their text placement information in proprietary manners due lack of a consistent and usable standard. Although the mechanisms for text storage have tended to be compatible, the actual format for exchange has been sufficiently different, and, therefore, non-standardized to interfere with complete data exchange and common usage. 

Annotation text is simply placed text that can carry either geographically-related or ad-hoc data and process-related information is displayable text. This text may be used for display in editors or in simpler maps. It is usually lacking in full cartographic quality, but may act as an approximation to such text as needed by any application. 

The primary purpose of standardizing this concept is to enable any application using any version of Simple Features data storage or XML to read and write text objects that will describe where and how the text should be displayed. This design ensures that applications that do text placement should have no problem storing their results and that applications that comply with the standard should have no problem exchanging information on text and its placement. 
Unlike spatial geometries, text display is very dependent on client text rendering engines and the style and layout attributes applied. The spatial area covered by text is only partially determined by the locating geometry. Style and layout attributes along with the actual text and locating geometry are all needed to display text correctly. Thus, it is critical to have a place to store these attributes in the feature database. While it is impossible to guarantee absolute fidelity of display on all rendering systems, applications can interoperate at a useful level. 

The most common perception of text display is for cartographic purposes, for printed maps of high technical and artistic quality. While this is a potential use of placed text, its more every-day use is for identification of features in any display, regardless of the purpose of that display. So both cartographic preprint and data collection edit displays have a requirement for placed-text, albeit at different levels of artistic quality. The purpose is still the same, to aid in the understanding of the “mapped” features, either for map use or feature edit and analysis. 

Text can also be used for less precise annotation purposes and more for quick display of text labels that make a display more understandable. The text so placed may not even have any associations to real-world features, but may be used to store information pertinent to the process that the data is undergoing at the moment. Thus, in a data collecting and edit display, a particular placed text may be used to indicate an error in the data that needs to be resolved, such as “sliver,” “gap” and “loop” error in digitization. Here the annotation is placed near the geometric error, but is not necessarily associated to a particular feature, as much as to a portion or portions of feature geometry objects.

Annotation text can include text on maps derived from vector information, or text overlays for imagery for information not discernable from the image, such as place or street names. In most cases, applications that do this have certain rules for creating and re-creating text based on the dynamic view of the mapping application. While this standard is not targeted to those usages, there are some allowances for this type of storage if it is so desired. In particular, it is allowable to store text that does not scale with the map objects but instead has a fixed display size (expressed as “points”, 72 to the inch). However, there are some limitations on this usage particularly with spatial indexing. 

A text object consists of an ordered list of independently placed text elements, possibly corresponding to individual lines of text in a multiline text display, and an envelope that approximates an outer limit of the text elements when placed. Each element has its own text attributes, but they are not used independently. The first element may set the attribute for all following elements and subsequent elements text attributes are only specified when a change is required. This behavior just extends that of the metadata text attributes to each element of the array.

A text object consists of a text string and information about its placement. The most important piece of information is the geometry to which the text is to refer, here referred to as the location geometry. A second geometry may be required to visually connect the placed text and the location geometry, especially where the location geometry is crowded in an area with other close-by features. This other geometry is referred to here as a leader line, and is a displayable curve of no geographic significance. If indexing is used, the envelope or minimum bounding box of the text is a handy piece of information that should be available. If unavailable, the envelope can be calculated from the processes of placing the text. Since this is often cumbersome, precalculating the envelope and storing it is often the most efficient manner to use this information. The other information associated to the annotation text is the various style information, such as the size of the text (usually in units appropriate to the display, such as pixels or points), the font used, characteristics of the font. 

== Proposed Solution ==

=== Supporting Annotations in Existing (Non-FDO) Schema ===

In order for the FDO API to be able to detect and support Annotation defined in existing schemas such as Oracle, the schema being read must support the Annotation metadata tables as mandated by the OGC Simple Feature Access Specification. The metadata can be exposed as a set of tables or views.

==== OGC Annotation Metadata Table ====

As specified in the OGC Simaple Access Specification, the following CREATE TABLE statement creates an appropriately structured table to be included in the schema, describing how text is stored in a feature table. This should be either an actual metadata table or an updateable view.

There is no requirement that the annotated feature have any other attributes. Unattributed annotations are in essence context-free, and may be used to place any text on the data, such as collection metadata or notes to user about unusual situations of which he may wish to be aware.

{{{
CREATE TABLE ANNOTATION_TEXT_METADATA AS
{
    F_TABLE_CATALOG AS CHARACTER VARYING NOT NULL,
    F_TABLE_SCHEMA AS CHARACTER VARYING NOT NULL,
    F_TABLE_NAME AS CHARACTER VARYING NOT NULL,
    F_TEXT_KEY_COLUMN AS CHARACTER VARYING NOT NULL,
    F_TEXT_ENVELOPE_COLUMN AS CHARACTER VARYING NOT NULL,
    A_ELEMENT_TABLE_CATALOG AS CHARACTER VARYING NOT NULL,
    A_ELEMENT_TABLE_SCHEMA AS CHARACTER VARYING NOT NULL,
    A_ELEMENT_TABLE_NAME AS CHARACTER VARYING NOT NULL,
    A_ELEMENT_TEXT_KEY_COLUMN AS CHARACTER VARYING NOT NULL
    A_ELEMENT_TEXT_SEQ_COLUMN AS CHARACTER VARYING NOT NULL
    A_ELEMENT_TEXT_VALUE_COLUMN AS CHARACTER VARYING NOT NULL,
    A_ELEMENT_TEXT_LEADERLINE_COLUMN AS CHARACTER VARYING NOT NULL,
    A_ELEMENT_TEXT_LOCATION_COLUMN AS CHARACTER VARYING NOT NULL,
    A_ELEMENT_TEXT_ATTRIBUTES_COLUMN AS CHARACTER VARYING NOT NULL,
    A_TEXT_DEFAULT_EXPRESSION AS CHARACTER VARYING,
    A_TEXT_DEFAULT_ATTRIBUTES AS CHARACTER VARYING
}
}}}

There are no constraints on rows in this table, allowing a single feature table/geometry column pair to be annotated using text from different feature table columns.

==== OGC Annotation Metadata Column Descriptions ====

The fields in the Annotations metadata information view are given in:

||COLUMNS||DESCRIPTION||
||F_TABLE_CATALOG,[[BR]]F_TABLE_SCHEMA,[[BR]]F_TABLE_NAME||The fully qualified name of the feature table containing the geometry column to be annotated.||
||F_TEXT_KEY_COLUMN,[[BR]]F_TEXT_KEY_ENVELOPE_COLUMN||The names of the column in the feature table that contain: A KEY for the text to which the text elements can use as a point of aggregation. An ENVELOPE_COLUMN that contains a geometry object that acts as an envelope for the set of text elements in this text entity. This column should also be a valid geometry column.||
||A_ELEMENT_TABLE_CATALOG,[[BR]]A_ELEMENT_TABLE_SCHEMA,[[BR]]A_ELEMENT_TABLE_NAME||The fully qualified name of the text element table containing the text elements used for the F_Text columns column defined above||
||A_TEXT_ELEMENT_KEY_COLUMN,[[BR]]A_TEXT_ELEMENT_SEQ_COLUMN,[[BR]]A_TEXT_ELEMENT_VALUE_COLUMN,[[BR]]A_TEXT_ELEMENT_LEADERLINE_COLUMN,[[BR]]A_TEXT_ELEMENT_LOCATION_COLUMN,[[BR]]A_TEXT_ELEMENT_ATTRIBUTES_COLUMN|| The names of the columns in the ELEMENT_TABLE that contain: [[BR]] The foreign KEY for the text entity as specified in the F_TEXT_KEY_COLUMN. [[BR]] A sequence (SEQ) column which will be used to order the text elements in this text entity. Any sortable type is valid for this column in the table, although integers would be the obvious choice. [[BR]] A text string VALUE for this text element. [[BR]] The LEADERLINE for this text element ⎯ if it has one (should also be a geometry column). [[BR]] The LOCATION for this text element (should also be a geometry column). [[BR]] The local text ATTRIBUTES providing the opportunity to override the text attributes currently in force. This is an XML type, and will be a collection of XML elements each describing a text attribute of the current text element. Unspecified attributes take the value most recently defined.||
||A_TEXT_DEFAULT_EXPRESSION,[[BR]]A_TEXT_DEFAULT_ATTRIBUTES||The default values for the corresponding “A_TEXT_” columns above, for cases where these columns are NULL in the feature table. They may be values or “query” expressions in terms of other columns in the database. These defaults shall be overridden on a row by row basis when the corresponding columns in the feature table row are not NULL.||

TBD


== Implications ==

TBD

== Test Plan ==

TBD

== !Funding/Resources ==

Autodesk to provide resources / funding