= 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.||

=== Integrating Annotation Text Concepts into the FDO API ===

In order to support Annotation Text and the concepts outlined in the sections above, the object and metadata relationships defined by the OGC Simple Feature Access Specification will be incorporated into the FDO API as outlined in the sections below. 

==== Annotation Text Definitions as an FDO Property Definition ====

Annotation Text and its logical metadata will be creatable, modifiable and describable via the FDO API schema. Annotation Text will be defined as properties on FDO Feature Classes and be exposed in the same manner as Geometry, Raster and Associations, via an FDO property definition class that derives from !FdoPropertyDefinition. In this manner, class !FdoAnnotationPropertyDefinition will be added to the API and will contain the definition of the schema, classes and properties that define the location of the Annotation components. These elements are the logical properties that are needed to store the annotation text value, envelope, leader line, location and text attributes. The schema, classes and properties identified by these metadata properties will in turn be accessible through their own FDO schema definitions.

===== Starting from an Existing Physical Schema =====

Let us use the following physical schema as a starting point for further discussion.  In this example a Road table is used to capture the Location, Name and Width of road objects in a city. Associated to the Road table is a !RoadAnnotation table that contains textual labels that describe the road. A Road object can be associated to 0…n !RoadAnnotation objects. 

[[Image(road_example.png)]]

These two classes are related through their primary identifiers. 

        Road.!FeatId == !RoadAnnotation.!ParentId

Road features can be related n times to !RoadAnnotation objects through a combination of matching primary identifiers and the !RoadAnnotation !SequenceId. The full primary key on !RoadAnnotation is therefore a combination of the !ParentId and !SequenceId. The !SequenceId column is used to order the text elements associated to Road. Any sortable type is valid for this column in the table, although integers would be the obvious choice.

The !RoadAnnotation table contains a set of properties that are in form (not name) mandated by the OGC specification. These properties, taken together, represent a complete Annotation Text Element. Each Text Element is defined by its Location or spatial geometry, a textual display Value, a textual description of its display model Attributes, and the geographic Leader Line that is used to place the Text Value in relation to its owner or neighboring features.

The optional “Text” properties defined on the Road table are also mandated by the OGC Specification. Implementing applications may optionally provide a means of capturing the overall Text Envelope, a Default Text Value and a set of Default Text Attributes to be used to describe all instances of Annotation Text associated to the parent feature. The Default values are used if no values (NULL) are specified for a individual instance of an Annotation object. The Text Default Value may be a text string or a query expression. Text Default Attributes are typically serialized XML documents that describe how to symbolize text entities and their leader lines. 

In the example above, I show these properties defined on the parent Road table, however, they could in fact be located in any schema:table in the data store and their location and property names described using metadata. 

Starting from the Road Table described above, let’s construct a simple set of attribute data to represent a Road and several Annotation Text Elements. NOTE: Geometry and Envelope information are not described below.

Road Features

||!FeatId||Name||Width||!DefaultTextValue||
||100||Main St.||25||||
||200||First Ave.||20||||	
||300||Second Ave.||20||Expr(“Road.Name”)||

!RoadAnnotation Text Elements

||!ParentId||!SequenceId||!TextValue||
||100||1||“Main St.”||
||100||2||“Main St.”||
||200||1||“First Avenue”||
||200||2||“First Avenue”||
||200||3||“First Avenue”||
||300||1||||
||300||2||||

===== Physical Schema to FDO Logical Schema =====

From the above Physical Schema, a Logical Schema will be generated that exposes two classes: Feature Class “Road” and Annotation Text Element Class “!RoadAnnotation”. The road table columns will be exposed on the Road Feature Class as Properties. Class Road will also contain a reference to an Annotation property, a new FDO property definition type defined as '''!FdoAnnotationPropertyDefinition'''. The Annotation property will in turn reference a new FDO class type '''!FdoAnnotationTextElementClass''' that defines the instance of the !RoadAnnotation class.

[[Image(road_annotation.png)]]

Here are the new definitions (simplified property view) of the new !FdoAnnotationTextElement and !FdoAnnotationPropertyDefintion FDO API classes. The full descriptions of these new classes are available in subsequent sections and will specify the Set and Get methods for each class. Each property defined in the two classes described below map to a OGC Annotation construct as outlined in the 


{{{
class FdoAnnotationTextElementClass : public FdoClassDefinition
{
public:
    FdoDataPropertyDefinition* SequenceProperty;
    FdoDataPropertyDefinition* ParentIdentityProperty;
    FdoDataPropertyDefinition* TextValueProperty;
    FdoDataPropertyDefinition* TextAttributesProperty;
    FdoGeometricPropertyDefinition* GeometryProperty;
    FdoGeometricPropertyDefinition* LeaderLineProperty;
};
}}}

{{{
class FdoAnnotationPropertyDefinition : public FdoPropertyDefinition
{
public:
    FdoDataPropertyDefinition* FeatureIdentityProperty;
    FdoDataPropertyDefinition* DefaultTextValueProperty;
    FdoDataPropertyDefinition* DefaultTextAttributesProperty;
    FdoGeometricPropertyDefinition* TextEnvelopeProperty;
    FdoAnnotationTextElementClass* TextElementClass;
};
}}}

Here are the how these new classes and their respective definitions would map to the Road example specified above. Both Road and !RoadAnnotation are exposed as classes. Road is associated to !RoadAnnotation through an !AnnotationPropertyDefinition named ‘Annotation’.  The !AnnotationPropertyDefinition points to the !TextElementClass !RoadAnnotation. 

||Property||Value||
||!AnnotationPropertyDefintion.!TextElementClass||@!RoadAnnotation||
||!AnnotationPropertyDefintion.!FeatureIdentityProperty||Road.!FeatId||
||!AnnotationPropertyDefintion.!TextEnvelopeProperty||Road.!TextEnvelope||
||!AnnotationPropertyDefintion.!DefaultTextValueProperty||Road.!TextDefaultValue||
||!AnnotationPropertyDefintion.!DefaultTextAttributesProperty||Road.!TextDefaultAttributes||
||!AnnotationTextElementClass.!SequenceProperty||!RoadAnnotation.!SequenceId||
||!AnnotationTextElementClass.!ParentIdentityProperty||!RoadAnnotation.!ParentId||
||!AnnotationTextElementClass.!GeometryProperty||!RoadAnnotation.Location||
||!AnnotationTextElementClass.!LeaderLineProperty||!RoadAnnotation.!LeaderLine||
||!AnnotationTextElementClass.!TextValueProperty||!RoadAnnotation.!TextValue||
||!AnnotationTextElementClass.!TextAttributesProperty||!RoadAnnotation.!TextAttributes||

Through such an organization of Annotation properties into !FdoAnnotationPropertyDefinition and !FdoAnnotationTextElementClass types, multiple Annotation definitions can then be created and added to a single feature class definition, each named uniquely and pointing to a distinct !TextElement class. 

===== Enhanced FDO Class and Property Types =====

In order for the !AnnotationTextElement class type to be recognizable when reading an FDO schema, the FDO API Class Type enumeration will be extended to include an enumeration value for type !AnnotationTextElementClass.  


{{{
enum FdoClassType
{
    FdoClassType_Class,
    FdoClassType_FeatureClass,
    ...
    ...
    FdoClassType_AnnotationTextElementClass
};
}}}

This enumerated value will be returned by the implementation of 
	

{{{
FdoClassType FdoAnnotationTextElementClass::GetClassType();
}}}

In order for the !AnnotationPropertyDefinition type to be recognizable when reading an FDO schema, the FDO API Property Type enumeration will be extended to include an enumeration value for type !AnnotationPropertyDefinition.  


{{{
enum FdoPropertyType
{
    FdoPropertyType_DataProperty,
    FdoPropertyType_ObjectProperty,
    FdoPropertyType_GeometricProperty,
    FdoPropertyType_AssociationProperty,
    FdoPropertyType_RasterProperty,
    FdoPropertyType_AnnotationProperty
};
}}}

This enumerated value will be returned by the implementation of 
	

{{{
FdoPropertyType FdoAnnotationPropertyDefinition::GetPropertyType();
}}}

===== FDO Logical Schema to Physical Schema =====

Using the same FDO classes and physical schema elements introduced in the above sections, here is an FDO code example on how an !ApplySchema Command would be executed to create a physical schema from an FDO logical schema.


{{{
// Create the schema
FdoFeatureSchemaP schema = FdoFeatureSchema::Create(L"Default", L"");
FdoClassCollectionP classes = schema->GetClasses();

// Create the RoadAnnotation TextElements Class
FdoAnnotationTextElementClassP txtElementClassDef = 
    FdoAnnotationTextElementClass::Create(L"RoadAnnotation", L"");
FdoPropertyDefinitionCollectionP txtElementProps = 
    txtElementClassDef->GetProperties();
FdoDataPropertyDefinitionCollectionP txtElementIdProps = 
    txtElementClassDef->GetIdentityProperties();;

// Create a ParentId property to hold the parent ID that owns the text element
FdoDataPropertyDefinitionP dataProp = 
    FdoDataPropertyDefinition::Create(L"ParentId", L"");
dataProp->SetDataType(FdoDataType_Int32);
dataProp->SetNullable(false);
dataProp->SetReadOnly(false);
dataProp->SetIsAutoGenerated(false);

// The ParentId property is a class ID property
txtElementProps->Add(dataProp);
txtElementIdProps->Add(dataProp);

// Explicitly set the ParentId property
txtElementClassDef->SetParentIdentityProperty(dataProp);

// Create a ParentId property so that Text Elements can be ordered
dataProp = FdoDataPropertyDefinition::Create(L"SequenceId", L"");
dataProp->SetDataType(FdoDataType_Int32);
dataProp->SetNullable(false);
dataProp->SetReadOnly(false);
dataProp->SetIsAutoGenerated(false);

// The SequenceId property is a class ID property
txtElementProps->Add(dataProp);
txtElementIdProps->Add(dataProp);

// Explicitly set the SequenceId property
txtElementClassDef->SetSequenceProperty(dataProp);

// Create a string data property that will hold the Text Element Value
dataProp = FdoDataPropertyDefinition::Create(L"TextValue", L"");
dataProp->SetDataType(FdoDataType_String);
props->Add(dataProp);

// Explicitly set the Text Element Value property
txtElementClassDef->SetTextValueProperty(geoProp);

// Create a string data property that will hold the Text Element Attributes
dataProp = FdoDataPropertyDefinition::Create(L"TextAttributes", L"");
dataProp->SetDataType(FdoDataType_String);
props->Add(dataProp);

// Explicitly set the Text Element Attributes property
txtElementClassDef->SetTextAttributesProperty(geoProp);

// Create a Geometry Location property for the Text Element
FdoGeometricPropertyDefinitionP geoProp = 
FdoGeometricPropertyDefinition::Create(L"Location", L"");
geoProp->SetSpatialContextAssociation(L"EPSG:4326");
geoProp->SetGeometryTypes((int)(FdoGeometryType_Point)); // Point
props->Add(geoProp);

// Explicitly set the Geometry Location property
txtElementClassDef->SetGeometryProperty(geoProp);

// Create a Geometry LeaderLine property for the Text Element
geoProp = FdoGeometricPropertyDefinition::Create(L"LeaderLine", L"");
geoProp->SetSpatialContextAssociation(L"EPSG:4326");
geoProp->SetGeometryTypes((int)(FdoGeometryType_MultiCurveString)); 
props->Add(geoProp);

// Explicitly set the Geometry LeaderLine property
txtElementClassDef->SetLeaderLineProperty(geoProp);

// Add the class to the schema
classes->Add(txtElementClassDef);

// Create the Read class
FdoFeatureClassP classDef = FdoFeatureClass::Create(L"Road", L"");
FdoPropertyDefinitionCollectionP props = classDef->GetProperties();
FdoDataPropertyDefinitionCollectionP idProps = classDef->GetIdentityProperties();;

// Create an Annotation property to allow reference to the TextElements 
FdoAnnotationPropertyDefinitionP annotationProp = 
    FdoAnnotationPropertyDefinition::Create(L"Annotation", L"");
props->Add(annotationProp);

// Create a Road Identity property
dataProp = FdoDataPropertyDefinition::Create(L"FeatId", L"");
dataProp->SetDataType(FdoDataType_Int32);
dataProp->SetNullable(false);
dataProp->SetReadOnly(false);
dataProp->SetIsAutoGenerated(true);

// The FeatId property is an ID property
props->Add(dataProp);
idProps->Add(dataProp);

// Set the annotation identity property
annotationProp->SetIdentityProperty(dataProp);

// Create a Name property
dataProp = FdoDataPropertyDefinition::Create(L"Name", L"");
dataProp->SetDataType(FdoDataType_String);
props->Add(dataProp);

// Create a Width property
dataProp = FdoDataPropertyDefinition::Create(L"Width", L"");
dataProp->SetDataType(FdoDataType_Double);
props->Add(dataProp);

// Create a Geometry to contain the Road location
geoProp = FdoGeometricPropertyDefinition::Create(L"Location", L"");
geoProp->SetSpatialContextAssociation(L"EPSG:4326");
geoProp->SetGeometryTypes((int)(FdoGeometryType_CurveString)); // CurveString
props->Add(geoProp);

// Set the geometry property for the class
classDef->SetGeometryProperty(geoProp);

// Create a Geometry Envelope to contain the TextElements extents
geoProp = FdoGeometricPropertyDefinition::Create(L"TextEnvelope", L"");
geoProp->SetSpatialContextAssociation(L"EPSG:4326");
geoProp->SetGeometryTypes((int)(FdoGeometryType_CurveString)); // CurveString
props->Add(geoProp);

// Set the annotation envelope property
annotationProp->SetTextEnvelopeProperty(geoProp);

// Create a string data property that will hold the default TextElement Value
dataProp = FdoDataPropertyDefinition::Create(L"TextDefaultValue", L"");
dataProp->SetDataType(FdoDataType_String);
props->Add(dataProp);

// Explicitly set the Text Element Value property
annotationProp->SetDefaultTextValueProperty(dataProp);

// Create a string data property that will hold the default TextElement Attributes
dataProp = FdoDataPropertyDefinition::Create(L"TextDefaultAttributes", L"");
dataProp->SetDataType(FdoDataType_String);
props->Add(dataProp);

// Explicitly set the Text Element Attributes property
annotationProp->SetDefaultTextAttributesProperty(dataProp);

// Add the class to the schema
classes->Add(classDef);

// Execute ApplySchema to create the schema
FdoIApplySchemaP applyschema = 
    (FdoIApplySchema*)(connection->CreateCommand(FdoCommandType_ApplySchema));
applyschema->SetIgnoreStates(true);
applyschema->SetFeatureSchema(schema);
applyschema->Execute();
}}}

==== Selecting Annotation Text Objects Through FDO ====

Annotation Text instances owned by FDO features will be queryable and selectable through a new FDO Interface FdoIAnnotation. The FdoIAnnotation type will be considered a primary data type that can be accessed when reading FDO features, in the same manner that Raster, Association and Geometry are currently exposed. This will allow complex Annotation objects to be associated to logical features such as roads, pipes, etc.
 
The FdoIAnnotation Interface allows clients that interact with and maintain Annotation text to do so through a single interface. Whereas the data that completely defines the set of Text Elements may be spread across several logical classes, accessing the Annotation will be managed through a more linear mechanism that allows users to manage data with worrying where that data is stored. 

{{{
class FdoIAnnotation : public FdoIDisposable
{
public:
    FdoIEnvelope* TextEnvelope;
    FdoString* DefaultBaseMapScale;
    FdoExpression* DefaultTextValue;
    FdoString* DefaultTextAttributesAsXml;
    FdoAnnotationTextElementCollection* TextElements; 
};
}}}

In this simplified view of FdoIAnnotation, we see how the Annotation’s text envelope, map scale, default values, and text elements are all available through a single interface.

From FdoIAnnotation, users are able to retrieve the collection of text attributes associated to the annotation. This is possible by accessing the TextElements property and iterating over the returned !FdoAnnotationTextElement Collection. Each object in the collection represents a piece of individual Annotation text. 

{{{
class FdoAnnotationTextElement : public FdoIDisposable
{
public:
    FdoByteArray*  Location;
    FdoByteArray*  LeaderLine;
    FdoExpression* TextValue;
    FdoString*     TextAttributesAsXml;
};
}}}

In order to access the above example data through the FDO logical model The FDO API’s !FdoFeatureReader class will be extended to allow Annotation properties to be queried by name and by index, in the same manner as Geometry and Raster properties are today queried. 

{{{
class FdoIFeatureReader: public FdoIReader
{
public:
…
…
    FdoIAnnotation* GetAnnotation(FdoString* propertyName);
    FdoIAnnotation* GetAnnotation(FdoInt32 index);
};
}}}


===== Querying Features with Annotation Properties =====

Using the above Road/!RoadAnnotation Example, here is an example of how Annotation properties would be queried from an FDO data store.

{{{
// Create a select command to retrieve Road features and its associated Annotations
FdoISelectP selectCmd = (FdoISelect*)conn->CreateCommand(FdoCommandType_Select); 
selectCmd->SetFeatureClassName(L"Road");

// Add the class properties to the selection set, including the Annotation property
FdoIdentifierCollectionP props =  selectCmd->GetPropertyNames();
props->Add(FdoIdentifierP(FdoIdentifier::Create(L"FeatId")));
props->Add(FdoIdentifierP(FdoIdentifier::Create(L"Geometry")));
props->Add(FdoIdentifierP(FdoIdentifier::Create(L"Name")));
props->Add(FdoIdentifierP(FdoIdentifier::Create(L"Width")));
props->Add(FdoIdentifierP(FdoIdentifier::Create(L"Annotation")));

// The selection can be arbitrarily filtered against
FdoFilterP filter = FdoFilter::Parse(L"FeatId > 100");
selectCmd->SetFilter(filter);

// Execute the command and get a feature reader that points to the retrieved records
FdoIFeatureReaderP reader = selectCmd->Execute();
while (reader->ReadNext())
{
    // Get the Annotation property by name
    FdoPtr<FdoIAnnotation> annotation = reader->GetAnnotation(L"Annotation");

    // The annotation will have an envelope and default properties, some
    // or all of which may be NULL. Envelope is a Geometry ByteArray. The
    // Default Text will be an expression that can be evaluated as any
    // database value
    FdoByteArrayP envelope = annotation->GetEnvelope();
    FdoExpressionP defaultText = annotation->GetDefaultTextValue();
    FdoStringP defaultTextAttributes = annotation->GetDefaultTextAttibutesAsXml();
    const char* charArray = (const char*)textAttributes;
    
    // The TextAttributes would be an XML string that needs to be streamed into memory
    // and then Read into the XML API class FdoTextElementAttributes
    FdoIoMemoryStreamP stream = FdoIoMemoryStream::Create();
    stream->Write( (FdoByte*) charArray, strlen(charArray) );
    stream->Reset();

    // Create the XML API class that allows programatic access to the XML properties
    // and read the XML stream into the corresponding classes.
    FdoTextElementAttributesP defaultAttributes = FdoTextElementAttributes::Create();
    defaultAttributes->ReadXml(stream);

    // Each Annotation has 0...n Text Elements that are the actual text values
    FdoAnnotationTextElementCollectionP textElements = annotation->GetTextElements();
    for (FdoInt32 i=0; i<textElements->GetCount(); i++)
    {
        // Get the nth Text Element and read its values
        FdoAnnotationTextElementP textElement = textElements->GetItem(i);
        FdoExpressionP textValue = textElement->GetTextValue();
        FdoByteArrayP location = textElement->GetLocation();
        FdoByteArrayP leader = textElement->GetLeaderLine();

        // As seen above, the XML text will need to be parsed into its API clases
        FdoStringP textAttributes = textElement->GetTextAttributesAsXml();
        if (textAttributes != L"")
        {
            const char* charArrayA = (const char*)textAttributes;
            FdoIoMemoryStreamP streamA = FdoIoMemoryStream::Create();
            streamA->Write( (FdoByte*) charArrayA, strlen(charArrayA) );
            streamA->Reset();

            FdoTextElementAttributesP attributes = FdoTextElementAttributes::Create();
            attributes->ReadXml(streamA);
        }
    }
}
}}}

==== Inserting and Updating Features with Annotation Properties ====

Annotation Text associated to FDO features will be insertable and updatable through a extended set of derived FDO interfaces that follow the existing !PropertyValue pattern used to specify data values for the FdoIInsert and FdoIUpadte comands. The newly defined Annotation interfaces will be derived from FdoExpression and FdoValueExpression and allow the Annotation properties to be set as Property Values and be parsed as expressions. 

The first step required to support an insertable Annotation is to derive a new !FdoAnnotationValue class from !FdoValueExpression. Instances of !FdoAnnotationValue will be set as the Value object on !FdoPropertyValue. Users of !AnnotationValue will have the ability to specify the Annotation Envelope and set of !TextElementValues attached to the Annotation.

{{{
class FdoAnnotationValue : public FdoValueExpression
{
public:
    FdoGeometryValue* Envelope;
    FdoStringValue* DefaultTextValue;
    FdoStringValue* DefaultTextAttributesValue;
    FdoAnnotationTextElementValueCollection* TextElementValues; 

public:
    bool IsNull();
    void SetNullValue();
    void Process(FdoIExpressionProcessor* p);
    FdoString* ToString();
    FdoExpressionItemType GetExpressionType();
};
}}}

While the above class allows users to specify high level Annotation values, they will still need a secondary Expression interface to specify the order list of !TextElementValues attached to the Annotation. Through this interface, users will be able to specify the Annotation Text location, leader line, text value, and attributes.

{{{
class FdoAnnotationTextElementValue : public FdoExpression
{
public:
    FdoGeometryValue* Location;
    FdoGeometryValue* LeaderLine;
    FdoStringValue* TextValue;
    FdoStringValue* TextAttributesValue;

public:
    void Process(FdoIExpressionProcessor* p);
    FdoString* ToString();
    FdoExpressionItemType GetExpressionType();
};
}}}

===== Inserting Features with Annotation Properties =====

Using the above Road/!RoadAnnotation Example, here is an example of how Annotation properties would be inserted into an FDO data store as a part of a feature.


{{{
// Create an Insert command to create a Road
FdoPtr<FdoIInsert> insCmd = (FdoIInsert*)(conn->CreateCommand(FdoCommandType_Insert));
insCmd->SetFeatureClassName(L"Road");
FdoPtr<FdoPropertyValueCollection> propVals = insCmd->GetPropertyValues();

// Specify Road object's Geometry as a line string
FdoPtr<FdoDirectPositionCollection> objPoints = FdoDirectPositionCollection::Create();
FdoPtr<FdoIDirectPosition> pt1 = gf->CreatePositionXY(pt_A.x, pt_A.y); 
FdoPtr<FdoIDirectPosition> pt2 = gf->CreatePositionXY(pt_C.x, pt_B.y);
FdoPtr<FdoIDirectPosition> pt3 = gf->CreatePositionXY(pt_C.x, pt_C.y);
objPoints->Add(pt1);
objPoints->Add(pt2);
objPoints->Add(pt3);
FdoPtr<FdoILineStringSegment> lineSeg = gf->CreateLineStringSegment(objPoints);
FdoPtr<FdoByteArray> fgf = gf->GetFgf(lineSeg);
FdoPtr<FdoGeometryValue> gv = FdoGeometryValue::Create(fgf);
FdoPtr<FdoPropertyValue> propGeom = FdoPropertyValue::Create(L"Geometry", gv);
propVals->Add(propGeom);


// Specify Road object's Name
FdoPtr<FdoStringValue> strValue = FdoStringValue::Create(L"Main St.");
FdoPtr<FdoPropertyValue> propName = FdoPropertyValue::Create(L"Name", strValue);
propVals->Add(propName);

// Specify Road object's Width
FdoPtr<FdoInt32Value> width = FdoInt64Value::Create(20);
FdoPtr<FdoPropertyValue> propWidth = FdoPropertyValue::Create(L"Width", width);
propVals->Add(propWidth);

// Create a Text Annotation Location as a point in space
double* ordsXY = new double[2];
ordsXY[0] = pt_D.x; ordsXY[1] = pt_D.y;
FdoPtr<FdoIGeometry> pnt = gf->CreatePoint(FdoDimensionality_XY, ordsXY);
FdoPtr<FdoByteArray> fgf2 = gf->GetFgf(pnt);
FdoPtr<FdoGeometryValue> gv2 = FdoGeometryValue::Create(fgf2);

// Create a Text Annotation Leader Line as a 2 segment line
FdoPtr<FdoDirectPositionCollection> leaderPoints = FdoDirectPositionCollection::Create();
FdoPtr<FdoIDirectPosition> pt4 = gf->CreatePositionXY(pt_E.x, pt_E.y); 
FdoPtr<FdoIDirectPosition> pt5 = gf->CreatePositionXY(pt_F.x, pt_F.y);
FdoPtr<FdoIDirectPosition> pt6 = gf->CreatePositionXY(pt_G.x, pt_G.y);
leaderPoints->Add(pt4);
leaderPoints->Add(pt5);
leaderPoints->Add(pt6);
FdoPtr<FdoILineStringSegment> lineSeg2 = gf->CreateLineStringSegment(leaderPoints);
FdoPtr<FdoByteArray> fgf3 = gf->GetFgf(lineSeg2);
FdoPtr<FdoGeometryValue> gv3 = FdoGeometryValue::Create(fgf3);

// Define the Annotation Text Envelope as a simple bounding box
FdoPtr<FdoIEnvelope> envl = gf->CreateEnvelopeXY(pt_H.x, pt_H.y, pt_J.x, pt_J.y);
FdoPtr<FdoByteArray> fgf4 = gf->GetFgf(envl);
FdoPtr<FdoGeometryValue> gv4 = FdoGeometryValue::Create(fgf4);

// Specify the Annotation Text as an expression. Value determined at runtime
FdoPtr<FdoStringValue> textStrValue = FdoStringValue::Create(L"Road.Name");

// Specify the Annotation Text as an expression (NULL)
FdoPtr<FdoStringValue> textAttribValue = FdoStringValue::Create(L"");
textAttribValue->SetNull();

// Create the Text Element Values (only one here) associated to the annotation 
FdoPtr<FdoAnnotationTextElementValue> eValue = FdoAnnotationTextElementValue::Create();
eValue->SetLocation(gv2);
eValue->SetLeaderLine(gv3);
eValue->SetTextValue(textStrValue);
eValue->SetTextAttributesValue(textAttribValue);

// Create the Annotation Value and set the Envelope and text elements
FdoPtr<FdoAnnotationValue> annValue = FdoAnnotationValue::Create();
annValue->SetEnvelope(gv4);
FdoAnnotationTextElementValueCollectionP textElements = annValue->GetTextElementValues();
textElements->Add(eValue);
FdoPtr<FdoPropertyValue> propAnn = FdoPropertyValue::Create(L"Annotation", annValue);
propVals->Add(propAnn);

// Execute the insert
FdoPtr<FdoIFeatureReader> rdr = insCmd->Execute();
}}}

===== Updating Features with Annotation Properties =====

Using the above Road/!RoadAnnotation Example, here is an example of how Annotation properties would be updated in an FDO data store as a part of a feature edit.


{{{
// Create an Update command to create a Road
FdoPtr<FdoIUpdate> cmd = (FdoIUpdate*)(conn->CreateCommand(FdoCommandType_Insert));
cmd->SetFeatureClassName(L"Road");
FdoPtr<FdoPropertyValueCollection> propVals = cmd->GetPropertyValues();

// Specify the Filter
FdoPtr<FdoFilter> filter = FdoFilter::Parse(L"FeatId=100");
cmd->SetFilter(filter);

// Create a Text Annotation Location as a point in space
double*	ordsXY = new double[2];
ordsXY[0] = pt_D.x; ordsXY[1] = pt_D.y;
FdoPtr<FdoIGeometry> pnt = gf->CreatePoint(FdoDimensionality_XY, ordsXY);
FdoPtr<FdoByteArray> fgf2 = gf->GetFgf(pnt);
FdoPtr<FdoGeometryValue> gv2 = FdoGeometryValue::Create(fgf2);

// Create a Text Annotation Leader Line as a 2 segment line
FdoPtr<FdoDirectPositionCollection> ldrPts = FdoDirectPositionCollection::Create();
FdoPtr<FdoIDirectPosition> pt4 = gf->CreatePositionXY(pt_E.x, pt_E.y); 
FdoPtr<FdoIDirectPosition> pt5 = gf->CreatePositionXY(pt_F.x, pt_F.y);
FdoPtr<FdoIDirectPosition> pt6 = gf->CreatePositionXY(pt_G.x, pt_G.y);
ldrPts->Add(pt4);
ldrPts->Add(pt5);
ldrPts->Add(pt6);
FdoPtr<FdoILineStringSegment> lineSeg2 = gf->CreateLineStringSegment(ldrPts);
FdoPtr<FdoByteArray> fgf3 = gf->GetFgf(lineSeg2);
FdoPtr<FdoGeometryValue> gv3 = FdoGeometryValue::Create(fgf3);

// Define the Annotation Text Envelope as a simple bounding box
FdoPtr<FdoIEnvelope> envl = gf->CreateEnvelopeXY(pt_H.x, pt_H.y, pt_J.x, pt_J.y);
FdoPtr<FdoByteArray> fgf4 = gf->GetFgf(envl);
FdoPtr<FdoGeometryValue> gv4 = FdoGeometryValue::Create(fgf4);

// Specify the Annotation Text as an expression. Value determined at runtime
FdoPtr<FdoStringValue> textStrValue = FdoStringValue::Create(L"Main St.");

// Specify the Annotation Text as an expression (NULL)
FdoStringP textAttributes = GetTextAttributesAsXMLDocument();
FdoPtr<FdoStringValue> textAttribValue = FdoStringValue::Create(textAttributes);

// Create the Text Element Values (only one here) associated to the annotation 
FdoAnnotationTextElementValueP txtElemVal = FdoAnnotationTextElementValue::Create();
txtElemVal->SetLocation(gv2);
txtElemVal->SetLeaderLine(gv3);
txtElemVal->SetTextValue(textStrValue);
txtElemVal->SetTextAttributesValue(textAttribValue);

// Create the Annotation Value and set the Envelope and text elements
FdoPtr<FdoAnnotationValue> annotationValue = FdoAnnotationValue::Create();
annotationValue->SetEnvelope(gv4);
FdoAnnotationTextElementValueCollectionP txtElems = annValue->GetTextElementValues();
textElements->Add(textElementValue);
FdoPtr<FdoPropertyValue> propAnn = FdoPropertyValue::Create(L"Annotation", annValue);
propVals->Add(propAnn);

// Execute the update
FdoPtr<FdoITransaction> tr = conn->BeginTransaction();
FdoInt32 rez = cmd->Execute();
tr->Commit();
}}}

==== Filtering on Features with Annotation Properties ====

TBD…

Q: Can you filter on Annotation values? Join? Computed Values? Do we need to define a textual representation of an Annotation property and subsequently update the FDO filter parser to recognize the new constructs?

==== Accessing Annotation Text Element Stylization ====

Each Annotation object will contain references to its Text Elements exposed through an associated collection of !FdoAnnotationTextElement objects. Text Attributes will be supported for individual Text Entities using XML descriptive text that will be supported through a set of XML serializable objects that allow all of the attributes to be programmatically accessed. 

As mandated by the OGC Simple Feature Access Specification, each Text Element associated to an Annotation will allow attributes to be specified for Style and Layout. Style attributes will include properties for Font, Fill, Stroke and Decoration. Layout attributes will include properties for Alignment, Justification and Spacing. In the FDO API, these properties will be exposed on two new classes !FdoTextElementStyle and !FdoTextElementLayout.


{{{
class FdoTextElementStyle 
{
public:
    FdoString* FontFamily;
    double FontSize;
    FdoFontWeightType FontWeight;
    FdoFontStyleType FontStyle;
    FdoTextDecorationType TextDecoration;
    FdoString* FillColor;
    double FillOpacity;
    FdoString* StrokeColor;
    double StrokeWidth;
    double StrokOpacity;
};
}}}

{{{
class FdoTextElementLayout 
{
public:
    FdoHorizontalAlignmentType HorizontalAlignment;
    FdoVerticalAlignmentType VerticalAlignment;
    FdoMultilineJustificationType MultilineJustification;
    double MultilineSpacing;
};
}}}

These two sets of properties shall be exposed through another new Interface !FdoTextElemnetAttributes. This interface will allow both sets of properties to be grouped together yet still allow each group to be accessed separately. Instances of !TextElementAttributes will be associated to the FDO Annotation as a whole through the "!TextDefaultAttributes" property, and to each FDO Text Element through its "!TextAttributes" property.

{{{
class FdoTextElementAttributes
{
public:
    FdoTextElementStyle* TextStyle;
    FdoTextElementLayout* TextLayout;
};
}}}

===== Processing Text Element Attributes =====

Using the select example preciously documented to query Annotations, we can continue to flush out the on and show how the de-serialized XML string elements can be accessed using the classes described above. 

{{{
// Since OGC allows text elements to inherit their style
// from previously defined elements, we will need to save a 
// "parent" style information as we work down the element array
FdoTextElementStyleP parentTextStyle;
FdoTextElementLayoutP parentTextLayout;

// Each Annotation has 0...n Text Elements that are the actual text values
FdoAnnotationTextElementCollectionP textElements = annotation->GetTextElements();
for (FdoInt32 i=0; i<textElements->GetCount(); i++)
{
    // Get the n’th Text Element and read its style values
    FdoAnnotationTextElementP textElement = textElements->GetItem(i);

    // As seen above, the XML text will need to be parsed into its API clases
    FdoStringP textAttributes = textElement->GetTextAttributesAsXml();

    // Convert the FdoString to a char array and stream it into memory
    const char* charArrayA = (const char*)textAttributes;
    FdoIoMemoryStreamP streamA = FdoIoMemoryStream::Create();
    streamA->Write( (FdoByte*) charArrayA, strlen(charArrayA) );
    streamA->Reset();

    // Create the extended style object (initially empty) and read the style
    // attributes into it from the XML stream.
    FdoTextElementAttributesP attributes = FdoTextElementAttributes::Create();
    attributes->ReadXml(streamA);

    // Extract the text style info. If defined for this element process and display it.
    // NOTE: The OGC specification allow for elements higher in the display
    // list to dictate style if the element lower in the array has no style 
    // information specified. Therefore, save the parent and use it later in the 
    // array iteration if needed. This applies for the next 3 types as well
    FdoTextElementStyleP textStyle = attributes->GetTextStyle();
    if (textStyle) 
    {
        ProcessTextStyle(textStyle);
        parentTextStyle = textStyle;
    }
    else if (parentTextStyle)
        ProcessTextStyle(parentTextStyle);
       
    // Extract the layout style. If defined for this element process it for display
    FdoTextElementLayoutP textLayout = attributes->GetTextLayout();
    if (textLayout)
    {
        ProcessLayoutStyle(textLayout);
        parentTextLayout = textLayout;
    }
    else if (parentTextLayout)
        ProcessLayoutStyle(parentTextLayout);
}
}}}
  

== Implications ==

TBD

== Test Plan ==

TBD

== !Funding/Resources ==

TBD