Features and Attributes
Also see
tsc_FeatureLibrary class.
tsc_EntityFeatures class.
Introduction
The idea behind features and attributes is for a user to be able to assign one or more codes - which are short descriptive names - to an entity in the database such as a point, line, arc, polyline. These codes, known as Feature codes (or Feature names), can be more-or-less anything but are typically used to describe the entity, such as "Manhole", "Fence", "Pole", "Curb" and so forth.
In addition, each feature may contain a number of properties known as Attributes, which are name/value pairs. Attributes are used to further describe the feature, so that for instance, a Pole feature might have an Attribute called Type which could be one of "Power", "Street light", etc, and perhaps a height in feet or metres.
While a database entity may contain almost any number of arbitrary feature codes and attributes, it is common for a schema to be enforced so that a user may attach only known feature codes and known attributes to a database entity.
A schema is supplied in the form of a Feature Library (FXL) file. An FXL contains any number of features, and each feature may contain a list of possible attribute names. Each attribute additionally contains a set of input rules such as type (string, integer, menu, etc), the allowable range of values or a list of choices, whether the item is mandatory or not, a default value, and so on.
FXL libraries are XML files. Survey Core also supports reading legacy library file types such as FAL, but support is limited and may be discontinued in the future. FXL is recommended, since it is fully supported by the current office software, Trimble Business Center (TBC).
The General Survey UI enforces the schema - the user cannot enter features or attributes that are not part of the currently attached library. On the other hand, a plugin may update a database entity with features and attributes that are not defined in any library, and Survey Core will support this by outputting all feature and attribute information, without change, into an exported JobXml file. It is the plugin developer's responsibility to ensure that other systems which process JobXml feature and attribute information will operate correctly when the features and attributes do not conform to a library schema.
Important
The feature and attribute editing forms in Survey Core are designed to operate with a fixed feature library. If the library is edited or a different library is attached to the job then the features and attributes that were previously entered will become read-only. The original library must be re-attached to re-enable editing.
Features and attributes are intimately connected to the code field, which contains a space-separated list of the entity's features. If the user edits the code field, then any features removed from the code will be removed from the features and attributes that were stored.
Libraries and entity datasets
A feature library contains a list of features, each containing a name and a list of attributes. The same can be said of the feature codes and attributes that have been stored with a database entity, except the database does not carry the input rules; it contains only the feature names, the attribute names, and their values.
If the current job has a feature library (.FXL or .FAL file) attached then a reference to it may be obtained as a tsc_FeatureLibrary from the current job's tsc_Job instance. This library is read-only; the current job does not allow this library to be changed, although a different library may be attached to the job, either by the plugin or by the user. Only one library may be attached to a job at any one time. A Feature Library is structured in API classes as follows:
tsc_FeatureLibrary
tsc_LibraryFeature
tsc_LibraryAttributeList
tsc_LibraryAttribute : Name, default value, input rules.
tsc_LibraryAttribute : Name, default value, input rules.
...
tsc_LibraryFeature
tsc_LibraryAttributeList
tsc_LibraryAttribute : Name, default value, input rules.
tsc_LibraryAttribute : Name, default value, input rules.
...
...
On the other hand, a database entity's features and attributes are represented by the tsc_EntityFeatures class. An entity's features and attributes may be changed at any time while the job is open.
It can be useful to set the features and attributes to those that are defined in the current FXL library, since that will allow a number of related systems to function. These systems include feature coding in the map, user-editing of the attribute values, and subsequent processing by Trimble office software. If those systems are unimportant then any arbitrary features and attributes may be added to an entity. Because Survey Core has no schema for these features and their input rules it will not allow the user to edit them, however the plugin may supply its own input forms instead.
The structure of the features and attributes attached to an entity is like this:
tsc_EntityFeatures
tsc_Feature
tsc_AttributeList
tsc_Attribute : Name and value.
tsc_Attribute : Name and value.
...
tsc_Feature
tsc_AttributeList
tsc_Attribute : Name and value.
tsc_Attribute : Name and value.
...
...
Attribute types and subclasses
There are several data types that may be used for an attribute. The attribute name is always a string but the value may be an integer, some text, a floating-point number, a choice from a set, a date, a time, a file name, or a reference to a photograph. These types are subclasses of the tsc_Attribute base.
The tsc_Attribute class and its subclasses contain only the attribute's name, type, and value. The input rules are not stored in the database.
The tsc_LibraryAttribute class contains the name, and type, and additionally holds input rules such as maximum and minimum values, plus a default value which was either predefined in the library or automatically generated in the case of date and time attribute types.
Reading and updating database entities
Certain objects in the job database may contain features and attributes. These objects include Points, Lines, Arcs, and Polylines, and are all subclasses of tsc_Entity. The current features and attributes of an entity can be obtained as a tsc_EntityFeatures instance from the object's class (eg, tsc_Point) by calling the base class method tsc_Entity::Features().
To set arbitrary features and attributes on an entity, a tsc_EntityFeatures object must be created and some appropriate features and/or attributes added to it with the values set as required. The tsc_EntityFeatures object can then be attached to a new entity before it is stored by calling tsc_Observation::SetFeatures. For an existing entity, the method tsc_Database::StoreFeatures() will replace the existing features and attributes of the entity. If the entity already has features and/or attributes, it is generally preferable to read and modify them rather than simply overwriting them. If the entity has no features then the tsc_FeatureList returned by tsc_Entity::Features() will be empty. To remove features and attributes of an entity, pass SetFeatures() an empty feature list.
Structure and ownership
Database entity features are organised in a tree-like structure as described above. Every element (except the root) of the structure has a parent, which "owns" the element. An element cannot be owned by more than one parent element; if an instance belonging to a tree is added to part of some other tree, the object will be cloned while the original object remains unchanged. Elements may also be orphans (having no parent), such as when they are newly created. Such elements may be added to any suitable parent.
When adding features or attributes to a database entity using a library as a schema, it is possible to construct a tsc_Attribute or a tsc_Feature from a corresponding library object, which can then be added to the entity's feature and attribute structure. All attribute values are set to their default values as specified by the library. To set attribute values it will be necessary to access the entity's structure and retrieve the copied tsc_Attribute objects.
Typical work scenarios
There are a number of ways in which libraries and entity datasets can be used:
Add arbitrary properties to a point before storing
No library is required for this. Simply create an empty tsc_EntityFeatures instance, add one or more features (tsc_Feature), and add the required attributes to each feature. Before storing the observation, set the features to the created tsc_EntityFeatures instance using the tsc_Observation::SetFeatures() method.
Access a database point's features and attributes
No library is required for this. Call the method tsc_Entity::Features() on the tsc_Point object to obtain a reference to the point's current features and attributes. The user will be unable to view or edit the attributes, but they may be accidentally deleted if the user changes the Code of the point.
Modify an existing database point's features and/or attributes
No library is required. Obtain a reference to the point's features and attributes by calling tsc_Entity::Features() on the tsc_Point object as explained above. The required modifications may be made to any object within the tsc_EntityFeatures. The modified copy can then be used in a call to tsc_Database::StoreFeatures() to update the entity in the database. Note that if the added features and attributes are not defined by the job's current library then the user will not be able to edit them using General Survey's standard UI.
Replace a database point's features and/or attributes
No library is required. Simply create a tsc_EntityFeatures object, add features and attributes as required, and call tsc_Database::StoreFeatures() to update the database. Any previous features will be overwritten by the new ones, so it is preferable to read and modify them rather than simply overwriting the old features and attributes.
Add features and attributes to a point according to the schema in a Feature Library
The current job must have an attached feature library. Obtain a reference to the current library by calling tsc_Job::CurrentFeatureLibrary(). The returned library is read-only. Create or obtain a tsc_EntityFeatures object which is to be used to update the point in the database. A tsc_Feature instance may be constructed directly from a tsc_LibraryFeature. Add the tsc_Feature to the entity's features using tsc_FeatureList::Add, which will add the feature and all the attributes it contains. Note that it is also possible to construct a tsc_Attribute class from a tsc_LibraryAttribute instance and add it into the tsc_EntityFeatures structure by calling tsc_AttributeList::Add. The attributes added to the tsc_EntityFeatures will contain their default values and they should be set to appropriate values, where necessary, before being used to update the point.