The OSM configuration file is a simple XML document that users can write to modify the map features and attributes that FME recognizes. The syntax is divided into two simple functions: adding/modifying map features, attributes, and geometry types; and removing them.
All the remaining content of the config should be contained within a root <fme_osm_config> element. You can find an example of a configuration file by looking at FME’s config file at <FMEInstallDir>\xml\osm\fme_map_features.xml. This file adds all the OSM wiki defined map features to FME. It is strongly recommended that you do not edit this file and instead specify any changes you wish to make in your own config file.
Adding Map Features
The primary method of adding map features is by writing <key> elements that contain child <value> elements. For example:
<key k="aerialway">
<value v="cable_car"></value>
<value v="gondola"></value>
<value v="chair_lift"></value>
</key>
This adds the broad feature aerialway with specific features aerialway_cable_car, aerialway_gondola, and aerialway_chair_lift. In this case, writing this in your user config would be unnecessary because aerialway is an OSM-wiki-defined feature and is already understood by FME.
The Add Command
An add command can be specified by adding children elements to an <add> element. These children elements include <ftype>, <attribute>, <geom_type>, and <linear>.
An alternative way to add map features is by specifying the key and value in an <ftype> element. For example:
<add>
<ftype k=”aerialway” v=”cable_car”></ftype>
<ftype k=”aerialway” v=”gondola”></ftype>
<ftype k=”aerialway” v=”chair_lift”></ftype>
</add>
This is equivalent to the code found above, in the Adding Map Features section. Note that the attribute v in the <ftype> element is optional.
The method of adding attributes and geometry types are almost identical via add commands. Both <attribute> and <geom_type> elements have name, k, and v attributes. Only the name attribute is mandatory; the k attribute is only necessary when v is specified. For example:
<add>
<attribute name=”attr1”></attribute>
<attribute name=”attr2” k=”shop”></attribute>
<attribute name=”attr3” k=”shop” v=”car”></attribute>
<geom_type name=”area”></geom_type>
<geom_type name=”line” k=”shop”></geom_type>
<geom_type name=”point” k=”shop” v=”car”></ geom_type>
<attribute name=”attr4” v=”car”></attribute>
</add>
This adds attr1 and area (xml_area) to ALL existing map features and also any map features that are created in the future. attr2 and line (xml_line) are added to the shop feature and also all of its specific features. Any specific features that are added to shop in the future will also have attr2 line (xml_line). attr3 and point (xml_point) are added to ONLY the shop_car feature. attr4 has specified a value but not key, so attr4 will not be added to anything.
Note that the geometry types in the config file are generic so that the file can be shared with OSM PBF. These generic names will map to XML types on the actual feature for OSM XML.
The following is a list of the supported geometry types with their xml type mappings that you can specify in your config file:
aggregate -> xml_aggregate
no_geom -> xml_no_geom
area -> xml_area
line -> xml_line
point -> xml_point
You should only be specifying these values in the name attribute of the <geom_type> element.
The attribute element also has an additional, optional type tag that can be used to add types to new attributes or modify the type of attributes on existing features. Note that the type names in the config file are also generic. These generic names will map to XML types on the actual feature for OSM XML. For example:
<add>
<attribute name=”attr_with_type” k=”shop” v=”car” type=”xml_datetime”</attribute>
</add>
If shop_car already has an attribute called attr_with_type, its type will be changed to datetime (xml_datetime). Otherwise, an attribute called attr_with_type with type datetime (xml_datetime) will be added to it. Either way, the result ends up being the same. Note that if the type isn’t specified in the attribute element, the type will be defaulted to string (xml_buffer). The following is a list of the supported attribute types (with their xml type mappings) that you can specify in your config file:
string -> xml_buffer
int32 -> xml_int32
int64 -> xml_int64
double -> xml_real64
datetime -> xml_datetime
Lastly, the <linear> tag can be used to determine whether the geometry of a closed way feature should be interpreted as a line or an area. An example of how to use the linear option can be found in the fme map features config file at <FMEInstallDir>\xml\osm\fme_map_features.xml:
<add>
<linear k="barrier"></linear>
<linear k="highway"></linear>
</add>
For the <linear> tag, it is mandatory to specify at least a k attribute while v is optional. By default, all closed way features, including any new user defined feature types, will be interpreted as areas. Exceptions to this are the barrier and highway feature types and their related types (that is, highway_motorway, barrier_block).
An area tag in an OSM element will override the default interpretation of a closed way feature. If the area tag is set to yes, closed way features will always be interpreted as an area. Whereas if the area tag is set to no, it will always be interpreted as a line. More information on this can be found at http://wiki.openstreetmap.org/wiki/Key:area.
The Remove Command
The syntax and logic for removing <ftype>, <attribute>, <geom_type>, and <linear> elements are extremely similar to the syntax and logic for adding, except that they take place as children of a <remove> tag instead. There are two key things to be aware of:
- Specifying remove on an <ftype> with only a k attribute won’t just remove the broad feature – it will also remove all of its specific features. For example:
<remove>
<ftype k=”barrier”></ftype>
</remove>
This doesn’t just remove the barrier feature; it also removes barrier_block, barrier_wall, etc.
- Note that the <attribute> element here does not accept a type attribute.
Ordering of Commands
The order in which map features are added and removed does matter – features that were previously added can be removed, and vice versa. This also applies to attributes and geometry types, which can be especially useful in certain cases. For example, imagine the broad feature shop and all of its specific features have the attribute width. Suppose you only want the attribute width to be on the feature shop_car. The user config can include the following to do this:
<remove>
<attribute name=”width” k=”shop”></attribute>
</remove>
<add>
</add>
<attribute name=”width” k =”shop” v=”car”></attribute>
</add>
However, the way attributes and geometry types are applied to map features is not affected by order. This means that attributes and geometry types can be added to features that have not yet been defined. For example, compare the following two config files:
1.
<add>
<ftype k=”park” v=”tree”></ftype>
<ftype k=”desert” v=”cactus”></ftype>
<ftype k=”desert” v=”sand”></ftype>
<attribute name=”global_attr”></attribute>
<attribute name=”k_attr” k=”desert”></attribute>
<attribute name=”v_attr” k=”desert” v=”sand”></attribute>
</add>
2.
<add>
<attribute name=”global_attr”></attribute>
<attribute name=”k_attr” k=”desert”></attribute>
<attribute name=”v_attr” k=”desert” v=”sand”></attribute>
<ftype k=”park” v=”tree”></ftype>
<ftype k=”desert” v=”cactus”></ftype>
<ftype k=”desert” v=”sand”></ftype>
</add>
These files perform the exact same function. Map features park, park_tree, desert, desert_cactus, and desert_sand are added:
- park and park_tree will have global_attr
- desert, desert_cactus, and desert_sand will have k_attr
- desert_sand will have v_attr
Default Attributes and Geometry Types
Specified in FME’s config file (found at at <FMEInstallDir>\xml\osm\fme_map_features.xml), are several attributes and geometry types that will be added by default to any new map features unless specified otherwise. Once again, it is strong advised that any changes you wish to make should be done in your own config file and NOT in fme_map_features.xml. The default attributes all have type string (xml_buffer). They include:
id
timestamp
user
created_by
visible
area
layer
uid
version
changeset
tag{}.ktag{}.vnd{}.refmember{}.typemember{}.refmember{}.roleosm_feature_type
osm_theme
The default geometry types are:
aggregate (xml_aggregate)
no_geom (xml_no_geom)
area (xml_area)
line (xml_line)
point (xml_point)