Writer factory pipelines provide users with an opportunity to alter the KML writer's feature processing, and reduce translation complexity. Pipelines are currently used to provide the KML writer's vector regionation and raster image pyramiding functionality, but could also be used for other purposes.
To use the pipeline functionality first enable the pipeline, and then specify the pipeline file. If no pipeline file is specified, a default pipeline file from $(FME_HOME)/plugins/kml21 will be used.
Pipeline files can be located in $(FME_HOME)/plugins/kml21 or $(FME_MF_DIR). In addition, a full path to the pipeline file can also be specified.
Vector (Placemark)
The vector pipeline processes features with vector geometry (typically Placemarks). The default pipeline, fmeregionator.fmi performs regionation.
Note: The default regionator pipeline requires Python.
Google Earth has difficulty opening and displaying large KML datasets that are contained in a single KML file. Regionation provides a mechanism for dividing vector data into many regions, each of which may contain sub-regions. Each region is contained within a separate kml file; Region and NetworkLink elements are used to instruct Google Earth when to load each set of vector data.
The basic idea behind regionation is that users should first be presented with the most important features, and as the user zooms to lower altitudes, less important features are displayed. The regionation pipeline uses relative weights to determine which features are displayed first.
The following format attributes are used to configure the regionation pipeline. See the sections below for further explanation.
|
KML Format Attribute |
Notes |
|
kml_region_weight |
A floating point value specifying the relative weight of the feature. If not present, heuristics will be applied to calculate a weight for the feature. |
|
kml_region_group |
The name of a group of features that will be regionated together. By default, all features will be regionated together. |
|
kml_features_per_region |
The number of features to include in each region. The default value is 16. |
|
kml_minimum_lod |
The minimum lod for each region. The default is 256. |
Relative Weights
During the regionation process, all input features are sorted according to their weight. Features with the highest weight are displayed first. It's important to understand the feature weight only determines relative display order; it does not guarantee that an item will be displayed at a certain altitude.
A feature's weight can be specified using the kml_region_weight format attribute. If no weight is specified, the following heuristic will be used to create a weight for each feature.
|
Feature Geometry |
Weight Calculation |
|
Point |
Constant value of 1.0 |
|
Line |
@Length()*1000 |
|
Area (and all others) |
@Area(1000) |
Level Of Detail
Each region is defined as a quadrant. Google Earth decides whether or not each region is displayed by comparing the number of pixels required to display the region in Google Earth to a particular minimum Level of Detail (LoD) specification. By default, the regionation pipeline uses a minimum LoD of 256, which can be overridden with the kml_minimum_lod format attribute. It is important to note that the the maximum LoD is always set to -1, which means that the region will always be turned on once the minimum LoD has been achieved.
Features per Quadrant
Each region can contain a certain number of features. When the region is activated, all features in the region are displayed. By default, each region contains at most 16 features, however this can be overridden using the kml_features_per_region format attribute.
Region Groups
By default, all vector features written to the writer will be regionated together. By using the kml_region_group format attribute, features can be assigned to groups for separated regionation.
Note: The regionation pipeline assumes that input features are sorted according to their individual region group. When the pipeline encounters a feature with a groupname that differs from the current group name, the current group will be completed, and regionation of a new group will begin.
Raster (GroundOverlay)
The raster pipeline processes features with raster geometry (typically GroundOverlays). The default pipeline, fmegroundoverlaypyramider.fmi performs image pyramiding.
Note: The default pipeline requires Python. An alternative pipeline, fmegroundoverlaypyramider_nopython.fmi, is also available.
Each feature will have a kml_images_folder format attribute added prior to input to the pipeline. This format attribute contains the location of the dataset's images' folder.
Raster (PhotoOverlay)
The raster pipeline processes features with PhotoOverlay feature types. No default pipeline is provided.
Each feature will have a kml_images_folder format attribute added prior to input to the pipeline. This format attribute contains the location of the dataset's images' folder.