Wednesday, June 17, 2015

Feature Strings

Feature Strings have been around since the introduction of Toolboxes in GTViewer version 8.0 in 2008.   They are simply a way to specify a feature or group of features to do something with.  For Toolboxes, they allow you to turn features on or off using Toolbox button. 

Traditionally, specifying a feature in GTViewer was done with a Category Id/Filter Id pair.  This method worked well for data using instance based symbology like CAD (Microstation, AutoCAD) and some GIS systems like MGE and FRAMME.    However, data using Style Based symbology, like SmallWorld and G/Technology, complicate the use of Filter Ids because many Filter Ids are now associated with a single feature (one for each style used with the feature).  For example, a primary conductor may have 200 different styles associated with it.  Figuring out those 200 Filter Ids, while simple, is tedious.  To compound this problem, only styles that get used are mapped to a Filter Id, so as a feature uses more and more styles (which is very common), the set of Filter Ids associated with the feature will increase requiring constant updating of the Filter Id list used to specify the feature.  This can problem will eventually result in having features that you can’t locate, can’t display, can’t turn off, can’t select, etc.

To solve this problem, the Feature String was created to give a simpler way to specify a feature or set of features by using feature metadata instead of the Filter Ids.  For example, if you want to specify a Pole, you can now say “Pole” instead of finding all of the different Filter Ids associated with every component of a Pole.   If a new style for Poles is used (which will use a new Filter Id), Feature Stirngs will automatically picked up by the Feature String that specifies “Pole”.

Feature String History

This concept of using metadata to find Filter Ids for Features was already used internally by the GTViewer Writer Plugin for FME.  By default, the FME Plugin uses the next available Filter Id anytime a new Style is needed.  To figure out which styles goes with a particular feature, the FME Plugin added to comment to each Filter Id entry in the Fitler File (.flt) to identify which FME_Feature_Type created the entry. 

The Filter Files (.flt) used by GTViewer contain an entry for each Filter Id used in a Category.  Each entry in the Filter File has a Filter Id and the Filter Name plus some other fields.  One of those additional fields is a Description field that has generally been used as a comment area (because it is not shown or used anywhere else), but it can now be used to define metadata about the Filter Id.   This metadata varies depending on the source GIS data and what method was used to convert the data to the GTViewer format.   Several notations are supported in the comment field:

Used by the GTech Loader:

GIS:<G3E_FNO>,<G3E_CNO>,<G3E_SRNo>,<G3E_SRRowNo>,<Style Name>

GIS:<G3E_FNO>,<G3E_CNO>,<G3E_SRNo>,<G3E_SRRowNo>,<Style Name>,<Feature Name>,<Component Name>

GIS:<Feature>,<Component>,<Style Rule Num>,<Style Num>,<Style Name>,<Feature Name>,<Component Name>

Generic Tag (used by newer versions of FME Writer Plugin):

GIS1:<Feature>,<Component>,<Style Name>

Originally Used for SmallWorld Data, but simple and flexible and can be used by custom data converters.

SW:<Feature>,<Component>,<Style Name>

Used to Support some older dataset where a Feature Name was provided in the comment:

Feature <Feature>

Used by Older versions of FME Writer Plugin:


With the feature metadata available in the Filter Files, the Feature String were devices to search this information in a variety of ways to pull out the Filter Ids you need based on a more abstract specification.   There are currently 7 different Feature String Items (commands) that you can use to select a list of Filter Ids.  These items can be used by themselves or combined with other.

Feature String Syntax

A Feature String is a list of items or a semicolon (;) delimited list of items:

<Feature String> = <item> [{; <item>}]

An Item can be one of the following:

<item> = Cat(<category Id>)

<item> = Gis(<category Id>, <Fea/Comp String>)

<item> = Flt(<category Id>,<Filter String>)

<item> = Dft(<category id>)

<item> = All(<category id>)

<item> = Contains(<category id>,"<string>")

<item> = Name(<category id>,<mode>,”<filter name>”, ”<feature>”,”<component>”, ”<feature name>”,
”<component name>”, ”<style name>”)

<Fea/Comp String> = <feature>[:<component>][{,<feature>[:<component>]}]

<Filter String> = <Filter Item>[{,<Filter Item>}]

<Filter Item> = <filter Id>
<Filter Item> = <Low Filter id>-<High FilterId>

In the above notation, tokens in square brackets ([]) are optional; tokens in curly braces ({}) can repeat.  This notation is probably over complicating 4 fairly simple entries that are described in plain English below:

·       Cat(<category Id>) – The Cat item will get all Filter Ids for a Category.

o   Cat(1)  = All Filter Ids in Category 1
o   Cat(1);Cat(2);Cat(3) = All Filter Ids in Categories 1, 2, and 3

·       Gis(<category Id>, <Fea/Comp String>) – The GIS item will get a list of Filter Ids for all of the Feature/Components specified in the Fea/Comp String which is a comma separated list of <Feature> or <Feature>:<Component> items.  If only the Feature is specified, then all Component Filter Ids will be retrieved; if a Feature:Component is specified, only the Filter Ids for the specific Feature Component will be retrieved.

o   Gis(2,Pole) = Category 2, All Pole components
o   Gis(2,Pole:Symbol) = Category 2, Only Pole Symbol component

For GTech Data, the Feature and Component fields use the G3E_FNO and G3E_CNO attributes, so they are numbers:

o   Gis(3, 300) = Category 3, Feature 300 (all components)
o   Gis(3, 300, 305, 306) = Category 3, Features 300, 305, and 306 (all components of each)
o   Gis(3, 300:10001, 300:10002) = Category 3, Feature 300 Component 10001 and Feature 300 Component 10002
o   Gis(3, 300:10001, 400, 500)  = Category 3, Feature 300 Component 10001 and Feature 400 and 500 (all components of each).
o   Gis (3,300); Gis(4,900) = Category 3 Feature 300  and Category 4 Feature 900

·       Flt(<category Id>,<Filter String>) – The Flt item will get a list of Filter Ids for the specified category.  The Filter String can be specified as a comma delimited list of Filter Ids, a hyphenated list for a range of Filter Ids, or a combination of the two.

o   Flt(5, 1,3,5) – Category 5 Filter Ids 1, 3, and 5
o   Flt(5, 1-10) – Category 5 Filter Ids 1,2,3,4,5,6,7,8,9,10
o   Flt(5, 1,4,20-23) – Category 5 Filter Ids 1,4,20,21,22,23
o   Flt(5, 1,3,5);Flt(6,30,32-35) – Category 5 Filter Ids 1,3,5  and Category 6 Filter Ids 30,32,33,34,35

·       Dft(<category id>) – The Dft item will get the list of Filter Ids in a specified category that are displayed by default as defined by the category’s Filter File (.flt).

    • Dft(5) – Get all of the filter ids for Category 5 that are Displayed by default

·       All(<category id>) - The All item will get all Filter Ids in the specified category.  This item is functionally equivalent to the Cat item.

    • All(5) – Get all Filter Ids for Category 5

·       Contains(<category id>,"<string>") - The Contains item will find all Filter Ids in the specified category that contain the specified string in the Filter Id’s Name.

    • Contains(5,"[Foreign Owner]") –Category 5 that contain “[Foreign Owner]” in the Filter Name.

·       Name(<category id>,<mode>,"<filter name>","<feature">,"<component>","<feature name>","<component name">,”<style name>") - The Name item will find all Filter Ids in the specified category that meet the search criteria.  This is a very powerful and potentially confusing item to use.   The Mode parameter can be:

-       AND – All of the criteria must be true (or not used) to get the Filter Id
-       OR –  Any one of the criteria can be true to get the Filter Id
-       INVERTAND – If all of the criteria is true, do not get the Filter Id
-       INVERTOR – If any of the criteria is true, do not get the Filter Id

The rest of the parameters can be left empty (don’t use) or a wild-carded string can be specified.  If a wild-card is not specified, the string must match exactly (not case sensitive).  A wild-card can appear at the beginning, end, in the middle, or any combination of these.

    • NAME(800,AND,*,519,966,*,*,"Ln_W_Pipe_Op_*") = Category 800, all Feature 519, Component 966 whose Style Name starts with “Ln_W_Pipe_Op_”

o   Name(5,AND,"*Foreign Owner*") = this is equivalent to the Contains example.

Where Feature Strings are Used

There are a lot of tools and functionality that use Feature String:

o   Feature Tooltips and the Feature Tooltip Builder App can use Feature Strings to specify which feature a tooltip is for.

o   GTPreset is a GTData tool that creates a Display Preset file (.gtp) from a description of what you want display.  This description is composed of Feature Strings.

o   Where Am I functionality in GTViewer and GTWeb uses Feature Strings to specify which shapes to look for.

o   Dynamic Graphics uses Feature Strings to specify which features to operate on.

o   GTViewer and GTVx both have methods exposed in their APIs to use Feature Strings:  GetFilterListFromFeatureString and GetCatFilterListFromFeaStr.

o   The DGN Export Exclude String in GTViewer uses Feature Strings.

o   The GTV Control has two methods that use Feature Strings:  GetCategoryListFromFeatureString and GetFilterListFromFeatureString.

o   GTQuery and the Query Builder App use a subset of the Query String (basically the GIS item) modified to fit the context of the existing Query Definition Files.  

o   Toolboxes in GTViewer use Feature String for the Display Toggle functionality.

o   GTViewer for iOS uses Features String to associate Data Collection forms with features.

No comments: