Professional Documents
Culture Documents
<xN>,<yN>[,<zN>]
END
TIP: Polygonal features may also be input and output using linear Generate files. In such cases, the first point
and the last point of the line are identical.
As with point files, the <idNumber> is any numeric value, and need not be unique
within a file. As well, the <z> value is optional and, if it is not specified, the linear
15-5 FME Reference Manual Version 2.0
Safe Software Inc. ESRI ARCINFO GENERATE FILE READER/WRITER
feature is considered to be two-dimensional. The end of each linear feature is marked
by a line containing only the word END. A linear Generate file is terminated with two
consecutive lines containing only the word END. A three-dimensional linear
Generate file example, containing two features, is shown below:
101
32,52,1
33,56,2
36,59,6
31,70,3
END
102
52,32,3
53,56,5
56,29,1
61,73,14
END
END
15.6.3 Text
Generate files containing only text (annotation) features, consist of a series of lines
that follow this syntax:
<idNumber>,<x>,<y>,<angle>,<size>,<text>
As with point files, the <idNumber> is any numeric value and need not be unique
within a file. A Text generate file is terminated with the word END. A text Generate
file example, containing two features, is shown below:
101,32,52,0,20,Arnet Maves
102,52,32,90,30,Barnie Maves
END
The attributes used by the generate reader and writer are described in the table below.
Attribute Name Value
arcgen_rotation Specifies the rotation of the text in degrees measured
counter-clockwise from horizontal.
Range: -360.0 . . . 360.0
arcgen_text_size The size of the annotation in ground units.
Range: Float > 0.
arcgen_text_string The text string to be placed at the annotation location.
Range: Any text string.
ESRI ARCINFO GENERATE FILE READER/WRITER Safe Software Inc.
15-6 FME Reference Manual Version 2.0
The example below shows an FME mapping file used to translate some points and
linear features from the Generate format into Shape files. The mapping file defines
the dataset location and gives the Generate definitions for the two files to be read. At
run time, the Generate reader goes out to the directory, reads the files, and produces
an FME feature for each Generate feature it finds.
15.7 Example
Sample Generate to Shape Mapping File:
# ---------------------------------------------
# Define the location of the Generate files
ARCGEN_DATASET /usr/data/generate/92i080
# ---------------------------------------------
# Define the type of each of the Generate files
ARCGEN_DEF nodes ARCGEN_GEOMETRY arcgen_point
# ---------------------------------------------
# This second file uses a space as the delimiter
ARCGEN_DEF boundaries ARCGEN_GEOMETRY arcgen_line \
ARCGEN_DELIMITER
# ---------------------------------------------
# Now define the location of the Shape files
# which will be created
SHAPE_DATASET /usr/data/shape/92i080
# ---------------------------------------------
# Define each of the Shape files.
SHAPE_DEF markers SHAPE_GEOMETRY shape_point \
MARKER_ID number(6,0)
SHAPE_DEF edges SHAPE_GEOMETRY shape_arc \
EDGE_ID number(6,0)
# ---------------------------------------------
# Now define transfer specifications
ARCGEN nodes arcgen_id %nodeNum
SHAPE markers MARK_ID %nodeNum
ARCGEN boundaries arcgen_id %boundNum
SHAPE edges EDGE_ID %boundNum
TIP: Notice the Shape file definitions create a field to store the identifier associated with each generate feature.
If the /usr/data/generate/92i080 directory contained the following files:
15-7 FME Reference Manual Version 2.0
Safe Software Inc. ESRI ARCINFO GENERATE FILE READER/WRITER
then the FME features shown below would be created by the Generate reader.
nodes.gen boundaries.gen
601,7,7
602,53,21
603,19,20
END
101
32 52 1
33 56 2
36 59 6
31 70 3
END
102
52 32 3
53 56 5
56 29 1
61 73 14
END
END
Feature Type: nodes
Attribute Name Value
arcgen_id 601
Coordinates: 37,7
Feature Type: nodes
Attribute Name Value
arcgen_id 602
Coordinates: 53,21
Feature Type: nodes
Attribute Name Value
arcgen_id 603
Coordinates: 19,20
ESRI ARCINFO GENERATE FILE READER/WRITER Safe Software Inc.
15-8 FME Reference Manual Version 2.0
These features would then be transformed by the FME and output to their destination
Shape files by the Shape writer.
Feature Type: boundaries
Attribute Name Value
arcgen_id 101
Coordinates: (32,52,1),(33,56,2),(36,59,6),(31,70,3)
Feature Type: boundaries
Attribute Name Value
arcgen_id 102
Coordinates: (52,32,3),(53,56,5),(56,29,1),(61,73,14)
16-1 FME Reference Manual Version 2.0
16
16 ESRI SHAPE FILE READER/
WRITER
The ESRI Shape File reader and writer modules provide the Feature
Manipulation Engine (FME) with access to ESRIs Shape file format. The
Shape file format is the native format of ESRIs ArcView product and has
been made public by ESRI. Recent releases of ArcInfo contain support for
direct and very fast import, and for export of Shape files. Users of ArcInfo
may use Shape files to provide a bridge between the formats and processing
capabilities supported by the FME and ArcInfo coverages.
16.1 Overview
Shape files store both geometry and attributes for features. No topological
information however is carried in a shape file. A single logical shape file
consists of three physical files, that have one of three file name extensions:
These extensions are added to the basename of the shape file creating three
separate physical files that must all reside in the same directory.
Filename extension Contents
.shp Vector geometric data
.shx Index to the geometric data
.dbf Attributes for the geometric data
ESRI SHAPE FILE READER/WRITER Safe Software Inc.
16-2 FME Reference Manual Version 2.0
Point, multipoint, arc, and polygon geometric data can be stored in .shp files.
However, a single .shp file can contain only one type of geometry. Each entity in
a .shp file has a corresponding entry in the .shx index file and a corresponding row
of attributes in the associate dbf file. The order of the entries in each of these three
files is synchronized. For example, the third geometric entity in the .shp file is
pointed to by the third entry in the .shx index file and has the attributes held in the
third row of the .dbf file.
In the case of multipoint data, there is only one .dbf row for each set of points held
in the file. This is in contrast with a point file where there is one .dbf row for each
point. Arc files contain linear features or aggregates of linear features, each having a
single attribute entry. Polygon files contain polygons or groups of disjoint or
overlapped, in the case of holes, polygons each having a single attribute entity.
TIP: Aggregate linear features and aggregate polygonal features may be created using the AggregateFactory.
They may be broken into their component pieces for output to formats that do not support aggregation
using the DeaggregateFactory.
TIP: If a polygon containing holes is written to a Shape file, any adjacent holes will be merged into a single hole
before the polygon is output.
The number and type of attributes associated with each entity is user-definable
however, there must be at least one field in the .dbf file. As well, all features in the
same Shape file will have the same number and type of attributes.
Shape files hold only two dimensional geometry and there is no provision for
transferring elevation data with each vertex in a Shape feature. However, features can
define an elevation attribute to store their elevation.
The FME considers a Shape dataset to be a collection of Shape files in a single
directory. The geometry type and attribute definitions of each Shape file must be
defined in the mapping file before being read or written.
The following diagram shows a Shape polygon file with three geometric entities in it.
The index file has three entries, each of which refer to the vector data defining each
polygon. Note that the second polygon contains a hole and the third polygon is an
aggregate of two disjoint polygons, one of which contains a hole. Each geometric
entity in turn corresponds with one record in the attribute table.
16-3 FME Reference Manual Version 2.0
Safe Software Inc. ESRI SHAPE FILE READER/WRITER
16.2 Reader Overview
The Shape reader produces FME features for all feature data held in Shape files
residing in a given directory. The Shape reader first scans the directory given for the
Shape files which have been defined in the mapping file. For each Shape file it finds,
it checks to see if it that file is requested by looking at the list of IDs specified in the
mapping file. If a match is made or no IDs were specified in the mapping file, the
Shape file is opened to be read. The Shape reader extracts features one at a time from
the file and passes them on to the rest of the FME for further processing. When the
file is exhausted, the Shape reader starts on the next file in the directory.
16.3 Reader Keywords
The following table lists the keywords processed by the Shape reader. The suffixes
shown are prefixed by the current <ReaderKeyword> in a mapping file. By
default, the <ReaderKeyword> for the Shape reader is SHAPE.
DEPTH LAKE_NAME
10
15
25
Smokey Lake
Beaver Hill Lake
Swan Lake
.shx Index File .shp Geometry File .dbf Attribute File
ESRI SHAPE FILE READER/WRITER Safe Software Inc.
16-4 FME Reference Manual Version 2.0
16.3.1 DATASET
The value for this keyword is the directory containing the Shape files to be read. A
typical mapping file fragment specifying an input Shape dataset looks like:
SHAPE_DATASET /usr/data/shape/92i080
16.3.2 DEF
Each Shape file must be defined before it can be read. The definition specifies only
the base name of the file, the type of geometry it contains, and names and types of all
attributes. The syntax of a Shape DEF line is:
<ReaderKeyword>_DEF <baseName> \
SHAPE_GEOMETRY shape_point|shape_arc| \
shape_polygon|shape_multipoint \
[<attrName> <attrType>]+
The filename of the each of the physical Shape files is constructed by adding their
extension to the basename. The SHAPE_GEOMETRY clause specifies the geometry
type for the entire file.
It is also possible to store features having no defined geometry. These features have
their SHAPE_GEOMETRY attribute set to shape_null. These shape_null
features may be stored or read from any type of shape file.
TIP: When creating Shape files, no attributes need to be specified on the SHAPE_DEF line. When no attributes
are defined on a Shape file being written, the FME automatically generates an _ID attribute for the shape
file. This is useful if the Shape file is to be imported into ArcInfo. If the Shape file contained polygons, an
AREA attribute is also generated. In both cases, the values of these attributes will be NULL for all features.
Keyword Suffix Value Required/
Optional
DATASET Contains the directory name of the input Shape files. Required
DEF Defines a Shape file. Each Shape file must be defined
before it can be read. The definition contains the files
base name without any of the extensions, the type of
geometry it holds, and the definitions of the attributes.
There may be many DEF lines, one for each file to be
read.
Required
IDs Contains a list of Shape files to process. If more Shape
files were in the directory, they are ignored. If this is not
specified, then all defined Shape files in the directory are
read.
Optional
16-5 FME Reference Manual Version 2.0
Safe Software Inc. ESRI SHAPE FILE READER/WRITER
Shape files require at least one attribute be defined. The attribute definition given
must match the definition of the file being read. If it does not, translation is halted and
the true definition of the Shape files attributes is logged to the log file. All Shape file
attribute names must be uppercase and must not exceed 10 characters in length. The
following table shows the attribute types that are supported.
The following mapping file fragment defines two Shape filesone containing
polygonal features possibly disjoint and with holes, and the other containing linear
features:
SHAPE_DEF landcover SHAPE_GEOMETRY shape_polygon \
AREA number(12,3) \
TYPE char(11) \
PERIMETERnumber(12,3)
SHAPE_DEF roads SHAPE_GEOMETRY shape_arc \
NUMOFLANES number(2,0) \
TYPE char(5) \
UNDERCNST logical \
DIVIDED logical \
TRVLDIR char(6)
16.3.3 IDs
This optional specification is used to limit the available and defined Shape files read.
If no IDs are specified, then all defined and available Shape files are read. The syntax
of the IDs keyword is:
Field Type Description
char(<width>) Character fields store fixed length strings. The
width parameter controls the maximum
characters that can be stored by the field.
When a character field is written, it is right-
padded with blanks, or truncated, to fit the
width. When a character field is retrieved, any
padding blank characters are stripped away
date Date fields store dates as character strings with
the format YYYYMMDD.
logical Logical fields store TRUE/FALSE data. Data
read to or written from such fields must always
have a value of either true or false.
number(<width>,<decimals>) Number fields store single and double
precision floating point values. The width
parameter is the total number of characters
allocated to the field, including the decimal
point. The decimals parameter controls the
precision of the data and is the number of
digits to the right of the decimal.
ESRI SHAPE FILE READER/WRITER Safe Software Inc.
16-6 FME Reference Manual Version 2.0
<ReaderKeyword>_IDs <baseName1> \
<baseName1> \
<baseNameN>
The basenames must match those used in DEF lines.
The example below selects only the roads Shape file for input during a translation:
SHAPE_IDs roads
16.4 Writer Overview
The Shape writer creates and writes feature data to Shape files in the directory
specified by the DATASET keyword. As with the reader, the directory must exist
before the translation occurs. Any old Shape files in the directory are overwritten with
the new feature data. As features are routed to the Shape writer by the FME, it
determines the file they are to be written to and outputs them according to the type of
the file. Many Shape files can be written during a single FME session.
16.5 Writer Keywords
The Shape writer processes the DATASET and DEF keywords as described in Section
16.3, Reader Keywords. It does not make use of the IDs keyword.
16.6 Feature Representation
Shape features consist of their geometry and a series of attribute values. The attribute
names are defined in the DEF line and there is a value for each attribute in each FME
Shape feature.
The FME considers the basename of the Shape file to be the FME feature type of a
Shape feature. The feature type of a Shape feature must match the basename of a
Shape file defined by a Shape DEF line.
The Shape reader adds the following special attributes to each feature it reads.
Attribute Name Contents
SHAPE_GEOMETRY The type of the geometry read from the shape file. This
attribute will contain one of:
shape_point
shape_multipoint
shape_arc
shape_polygon
shape_null
16-7 FME Reference Manual Version 2.0
Safe Software Inc. ESRI SHAPE FILE READER/WRITER
16.7 Example
The example below shows an FME mapping file used to translate some linear road
features from the IGDS format into Shape files. The mapping file defines the dataset
location and gives the Shape definitions for the Shape file being written. At run time,
the Shape writer is given FME features with full attribution to output.
TIP: This example shows how attributes encoded in class and color attributes in an IGDS file can be made
explicit in a Shape file.
Sample IGDS to Shape Mapping File:
# ---------------------------------------------
# Define the location of the output Shape files
SHAPE_DATASET /usr/data/shape/92i080
# ---------------------------------------------
# Define the attributes and type of the Shape
# file to be created
SHAPE_DEF roads SHAPE_GEOMETRY shape_arc \
NUMOFLANES number(2,0) \
TYPE char(5) \
UNDERCNST logical \
DIVIDED logical \
TRVLDIR char(6)
# ---------------------------------------------
# Now define the location of the IGDS file
# to be read
IGDS_DATASET /usr/data/dgn/92i080.dgn
# ---------------------------------------------
# Now define transfer specifications
IGDS 17 igds_color 7 igds_class 3 \
igds_type igds_line
SHAPE roads surfaceType loose numberOfLanes 1 \
travelDirection twoWay divided false \
underConstruction false
IGDS 17 igds_color 6 igds_class 3 \
igds_type igds_line
SHAPE roads surfaceType loose numberOfLanes 2 \
travelDirection twoWay divided false \
underConstruction false
IGDS 17 igds_color 16 igds_class 3 \
igds_type igds_line
SHAPE roads surfaceType loose numberOfLanes 2 \
travelDirection twoWay divided false \
underConstruction true
ESRI SHAPE FILE READER/WRITER Safe Software Inc.
16-8 FME Reference Manual Version 2.0
17-1 FME Reference Manual Version 2.0
17
17 ESRI SDE READER/WRITER
ESRIs Spatial Database Engine (SDE) brings Geographical Information
Systems (GIS) into the realm of Management Information Systems (MIS) by
providing a spatial interface to industry standard Relational DataBase
Management Systems (RDBMS).
The SDE enables a Relational DataBase Management System to store both
spatial and non-spatial data.
Spatial Database Engine
(SDE)
RDBMS Interface
Layer
RDBMS
(ORACLE, ODBC, ...)
Spatial Database Engine
ESRI SDE READER/WRITER Safe Software Inc.
17-2 FME Reference Manual Version 2.0
17.1 Overview
The SDE provides a seamless data model into which geographic data is stored. The
SDE provides a geo-relational data model organized around feature types. Feature
types
1
are roughly equivalent to entities to those familiar with Entity-Relationship
diagrams, classes to those familiar with Object-Oriented concepts, or layers to those
familiar with either Computer Aided Design (CAD) or traditional GIS products.
Example feature types include Roads and Rivers. A single SDE database may
consist of a large number of different feature types. Each feature type has the
following properties:
Each feature type has a spatial index that can be tuned specifically for the feature
type. The spatial index for each layer consists of between one and three two-
dimensional (2D) grids. The sizes of the grid elements is ordered so that:
grid1 size < grid2 size < grid3 size
TIP: Since the SDE uses integer coordinates, it is possible for precision to be lost or for overflow to
occur when features are output. Care must be taken to ensure that the SDE dataset system units
preserve the data precision and the range.
Each feature type has a single relational table into which attributes are stored.
There is a 1 to 1 mapping between the features in the feature type and the rows
in the relational table.
All features in a feature type must be either 2D or three-dimensional (3D). Mixed
dimensionality is not allowed.
Attribute indices can be created for each feature types to increase the
performance of the non-spatial portion of queries.
The Feature Manipulation Engines (FME) SDE reader and writer modules take
advantage of the unique capabilities of the SDE. The reader module retrieves features
from the SDE by constructing queries consisting of both spatial and non-spatial
components. An SDE database may have a very large number of features therefore
the query building capability is critical to ensure that the FME reader module is
capable of satisfying highly focused data requests. The writer module takes
advantage of the SDEs transaction model to ease the task of importing data into the
SDE.
TIP: See the SDEQueryFactory in Appendix B. This factory exploits the powerful query capabilities of the SDE.
1. The terms Feature type and SDE layer are used interchangeably throughout this section.
17-3 FME Reference Manual Version 2.0
Safe Software Inc. ESRI SDE READER/WRITER
17.2 FME SDE Highlights
The SDE reader and writer modules provide the FME with the ability to store data in
and retrieve data from the ESRIs SDE, and greatly reduce the time required to set up
a database for data import.
The SDE modules deliver the following capabilities:
Programmatic Layer Creation: Layers need not be created before a data
import operation. All layer creation details are handled by the FME.
Programmatic Attribute Creation: Layer attribute tables are created
automatically, eliminating the error-prone task of manually defining attribute
tables. Both optional and required attributes may be created.
Programmatic Attribute Index Creation: Attribute indices can be specified
within FME mapping files. These indices are used to enhance the performance
of the non-spatial component of searches.
Programmatic Layer and Attribute Verification: When loading data into an
existing spatial database, the FME verifies that the feature definitions specified
in the mapping file match the existing SDE layer and attribute definitions.
Transaction Support: Transactions are fully supported enabling a partially
complete load operation to be resumed later, without the loss of or duplication of
data.
Feature Logging Support: An SDE log file can be specified. This log file,
which is completely different than an FME log file, contains SDE feature
identifiers. The SDE reader module can use an SDE log file to control the
features it reads from the SDE, and the SDE writer module can log the feature
identifiers it writes to an SDE log file.
Attribute Query Support: SQL where clauses can be specified to limit the data
being exported.
Spatial Query Support: Simple spatial query support can be used to limit data
being exported from the SDE to an area of interest.
TIP: The query support enables the data export operation to be highly focused, thereby reducing the amount of
data which is exported.
The SDE modules with the FME are designed to work with other SDE products. For
example, a user with a sophisticated Graphical User Interface (GUI) search engine
can easily identify all features satisfying a complicated query and then use the FME
with the SDE reader module to process these features.
ESRI SDE READER/WRITER Safe Software Inc.
17-4 FME Reference Manual Version 2.0
17.3 Reader Overview
The SDE reader module is an SDE client application responsible for retrieving
features from SDE datasets. The SDE reader begins by starting an SDE session with
the server upon which the SDE dataset resides. Once connected, the SDE reader sends
requests to the SDE server for features and passes them on to the FME for processing.
After the SDE reader has connected to the SDE server, it determines the type of
feature retrieval operation specified in the FME mapping file. The SDE reader
currently supports spatially directed and log file directed feature retrieval operations.
In a spatially directed feature retrieval operation, the layers from which features are
retrieved are specified in the mapping file using the <ReaderKeyword>_IDs. An
optional search envelope and where-clause may also be specified. The SDE reader
then returns all features from the identified layers that intersect the search envelope.
If no search envelope is specified, then all features from the identified layers are
returned. If no <ReaderKeyword>_IDs statement is specified, then features from
all layers are returned.
In a log file directed feature retrieval operation, the features to retrieve are identified
in an SDE log file. This log file is specified in the FME mapping file with a
<ReaderKeyword>_LOGFILE statement.
TIP: SDE log files are distinct from FME log files. SDE log files contain the IDs of features previously
identified for processing, while FME log files contain statistics and other informational messages about
the FME session.
In both spatially and log file directed feature retrieval operations, an optional attribute
constraint can be specified with an SQL where clause. When the attribute constraint
is specified, only features that satisfy the constraint are retrieved.
The table below summarizes the different feature retrieval modes supported by the
SDE reader module. The next section contains an in-depth discussion of each of these
keywords.
Search Type Search Keyword
Suffix
Description
Spatial Retrieval IDs Specifies the layers from which features
are to be retrieved. If no layers are
specified, then the reader retrieves features
from all SDE layers.
SEARCH_ENVELOPE Specifies the spatial extent of the feature
retrieval. Only features that intersect this
envelope are returned.
WHERE Specifies the attribute values that a feature
must have to be retrieved.
17-5 FME Reference Manual Version 2.0
Safe Software Inc. ESRI SDE READER/WRITER
17.4 Reader Keywords
This section describes the keywords the SDE reader module recognizes. Each of the
keywords is prefixed by the current <ReaderKeyword>_ when they are placed in
a mapping file. By default, the <ReaderKeyword> for the SDE reader is SDE.
17.4.1 DATASET
This statement identifies the SDE dataset from which features are retrieved.
Example:
SDE_DATASET testdset
17.4.2 SERVER
This statement identifies the SDE server to communicate with.
Example:
SDE_SERVER tuvok
Logfile Retrieval LOGFILE Features retrieved are restricted to those
identified in the log file.
WHERE Specifies the attribution values that a
feature must have to be retrieved.
Parameter Contents
<dataset> The name of the dataset from which the features are
retrieved.
Parameter Contents
<server> The name of the SDE server used to read data from the
dataset.
Search Type Search Keyword
Suffix
Description
ESRI SDE READER/WRITER Safe Software Inc.
17-6 FME Reference Manual Version 2.0
17.4.3 USERID
The user name which is used to access the SDE database.
Example:
SDE_USERID ronny
17.4.4 PASSWORD
The password associated with the specified user ID.
Example:
SDE_PASSWORD ronpassword
17.4.5 WHERE
This statement may be specified for both Log File directed and Spatially directed
feature retrieval operations. The specified where clause is passed to the SDE for
processing.
Example:
The where clause specified below instructs the SDE to retrieve features whose
NUMLANES attribute has a value of 2.
SDE_WHERE where NUMLANES=2
Parameter Contents
<userid> The ID of the user account given to access the SDE
dataset.
Parameter Contents
<password> The password of the user account given to access the
SDE.
Parameter Contents
<where clause> The attribute constraint used to limit the features
which are retrieved based on attribution.
17-7 FME Reference Manual Version 2.0
Safe Software Inc. ESRI SDE READER/WRITER
17.4.6 SEARCH_ENVELOPE
The search envelope statement restricts the features being returned by the SDE reader
module to those which intersect the specified envelope. The envelope is specified in
user coordinates. This statement can only be specified for spatially directed searches.
Example:
SDE_SEARCH_ENVELOPE 601190 5437839 611110 5447549
17.4.7 LOGFILE
Specify this statement when log file directed feature retrieval is desired. This
identifies the log file that directs the feature retrieval.
Example:
SDE_LOGFILE wanted.log
17.4.8 IDs
This statement specifies the layers from which features are to be retrieved during a
spatially directed feature retrieval operation. There may be multiple SDE_IDs
statements within a single FME mapping file, in which case the input set of layers
comprises the union of all the SDE_IDs statements. The SDE reader module only
extracts features from the identified layers.
Parameter Contents
<minx> The lower x value of the search envelope.
<miny> The lower y value of the search envelope.
<maxx> The upper x value of the search envelope.
<maxy> The upper y value of the search envelope.
Parameter Contents
<logfile> The name of the log file containing the feature IDs to
be retrieved.
This is used for Log file directed feature retrieval
operation.
Parameter Contents
<[layer name]+> The name of the layers from which features are
retrieved.
ESRI SDE READER/WRITER Safe Software Inc.
17-8 FME Reference Manual Version 2.0
Example:
SDE_IDs roads
17.4.9 Complete Reader Example
The example below configures an SDE reader to extract features from the dataset
testdset located on server tuvok. Only features located on the layer named roads,
falling within the specified envelope and having an attribute NUMLANES with a value
of 2 will be read from the SDE.
SDE_DATASET testdset
SDE_SERVER tuvok
SDE_WHERE where NUMLANES=2
SDE_SEARCH_ENVELOPE 601190 5437839 611110 5447549
SDE_IDs roads
17.5 Writer Overview
The SDE writer module stores FME features in an SDE dataset. The SDE writer
module provides these capabilities:
Transaction Support: The SDE writer provides transaction support that eases
the data loading process. Occasionally, a data load operation terminates
prematurely due to data difficulties. The transaction support provided by the
SDE writer module provides a mechanism for correcting inconsistent data
without data loss or data duplication.
Layer Creation: The SDE writer module uses the information within the FME
mapping file to automatically create SDE dataset layers as needed.
Layer Validation: When data is loaded into an existing layer, the FME writer
module performs validation operations between the layer definition in the
mapping file and that within the SDE. Any discrepancies found are logged and
the data load operation is halted.
Attribute Creation: Attribute tables are also created using information from the
FME mapping file.
Attribute Index Creation: The SDE writer module can also define attribute
indices. Attribute indices are specified to increase the performance of searches
having a non-spatial component.
Feature Logging Support: The SDE writer module can be directed to write the
feature identifiers (IDs) to an SDE log file. Feature logging enables other
17-9 FME Reference Manual Version 2.0
Safe Software Inc. ESRI SDE READER/WRITER
applications or utilities to perform subsequent operation on newly loaded
features.
17.6 Writer Keywords
This section describes the keywords the SDE writer module recognizes. Each of the
keywords is prefixed by the current <WriterKeyword>_ when they are placed in
a mapping file. By default, the <WriterKeyword> for the SDE writer is SDE.
The DATASET, SERVER, USERID, and PASSWORD keywords operate in the
same manner as they do for the SDE reader. The other writer specific keywords are
discussed in the following sections.
17.6.1 SDE_LOGFILE
This statement specifies the name of the log file into which feature IDs are written. If
the log file doesnt exist then it is created, otherwise the existing log file is extended.
Example:
The statement below instructs the SDE writer to write the IDs of all features written
to the log file written.log
SDE_LOGFILE written.log
Keyword Suffix Value Required/
Optional
DATASET The SDE dataset into which data is to be read. Required
SERVER The server machine where the dataset resides. Required
USERID User ID to use for data load. Required
PASSWORD Password for user account. Required
LOGFILE SDE log file into which logged features are
placed.
Optional
TRANSACTION Transaction number to start loading operation. Optional
Parameter Contents
<logfile name> The name of the log file into which the feature IDs are
written.
ESRI SDE READER/WRITER Safe Software Inc.
17-10 FME Reference Manual Version 2.0
17.6.2 SDE_TRANSACTION
This statement instructs the SDE writer module to use transactions when loading data
into the SDE. The SDE writer will not write any features to the SDE until the feature
is reached that belongs to <last successful transaction> + 1. Specifying a value of 0
causes the SDE writer to use transactions and to write every feature to the SDE.
Normally the value specified is zero; a non-zero value is only specified when a
previous data load operation is being rerun.
If the SDE_TRANSACTION statement is not specified then transactions are not used
during the data load operation.
Example:
SDE_TRANSACTION 0
17.7 SDE Layer Representation
The SDE writer requires that every SDE layer into which a feature is written be
defined within the FME mapping file. The SDE writer uses this mapping file
information to automatically create layers, attribute tables, and attribute indices. SDE
layers are specified within the FME mapping file using the
<WriterKeyword>_DEF statement. This statement has the following form:
<WriterKeyword>_DEF <layerName> \
SDE_BASE_LAYER <Base layerNum> \
SDE_LAYER <layer Num> \
SDE_GRID{0} <grid size> \
[SDE_GRID{1} <grid size>] \
[SDE_GRID{2} <grid size>] \
SDE_DIMENSION 2|3 \
SDE_AVERAGE_PTS <average pts> \
SDE_INIT_NUM_FEATS <num feats> \
SDE_CONFIG_KEYWORD <config keyword> \
SDE_GEOMETRY (<geometry> [,<geometry>]*) \
[SDE_SECURITYCLASS <security class>] \
[<attribute Name> <attribute definition>]* \
[SDE_INDEX{#} ([<attribute Name>,]+ SDE_ASCEND|SDE_DESCEND)]
Parameter Contents
<last successful transaction> The transaction number of the last successful
transaction. When loading data for the first time, set
this value to 0.
17-11 FME Reference Manual Version 2.0
Safe Software Inc. ESRI SDE READER/WRITER
17.7.1 <layerName>
This specifies the name of the SDE layer being defined by the SDE_DEF statement.
The name must conform to the conventions and restrictions of the SDE.
The following example shows the first portion of the definition for a feature type
named roads.
SDE_DEF roads . . .
When a group of layers is logically related to one another, it is often useful to
associate them using a common suffix. This can be done within an FME mapping file
as follows:
1. Define a macro with the common suffix name.
MACRO BaseName Cadastral
2. Use the macro at the end of each of the associated layer names in the FME
mapping file.
SDE_DEF roads::$(BaseName)
TIP: This is an easy way to avoid name clashes in SDE datasets having large numbers of layers.
17.7.2 SDE_BASE_LAYER
The base layer value is used as a base layer address. Typically, the base layer value
is specified in an FME mapping file using a macro. This macro is then referred to
within all SDE definition statements in a single mapping file. During initial data
modeling and planning, the layer organization is often in a constant state of flux.
Defining the SDE_BASE_LAYER within a macro enables the SDE layer allocation
to be easily changed during the SDE data engineering phase.
TIP: Using the base layer, in conjunction with the suggested suffix layer naming scheme above, it is easy to
relocate a large collection of related layers.
The suggested method of using the SDE_BASE_LAYER is given below:
1. Define a macro which is used for all associated base layers.
MACRO BaseLayer 1000
2. Use this macro as the base layer number in all associated layers.
SDE_BASELAYER $(BaseLayer)
ESRI SDE READER/WRITER Safe Software Inc.
17-12 FME Reference Manual Version 2.0
17.7.3 SDE_LAYER
This defines the offset of the layer from the value specified in SDE_BASE_LAYER.
The actual SDE layer number is thus SDE_BASE_LAYER + SDE_LAYER.
The following example results in the layer being stored at layer 1005, using the
SDE_BASE_LAYER statement above.
SDE_LAYER 5
17.7.4 SDE_GRID{0}
This specifies the grid element size for grid level 1 of the layers spatial index. This
is specified in system units as described in the SDE documentation.
Assuming the number of system units to logical units is 100 and the logical units are
in meters, the following example defines a grid size of 200 meters.
SDE_GRID{0} 20000
TIP: Initially dont define the grid sizes for SDE_GRID2 and SDE_GRID3. Define them later for the few
layers that require them.
17.7.5 SDE_GRID{1}
This optional parameter defines the level 2 grid element size. This is not needed for
the majority of layers.
Assuming the number of system units to logical units is 100 and the logical units are
in meters, the following example defines a grid size of 1600 meters for the level 2
grid.
SDE_GRID{1} 160000
17.7.6 SDE_GRID{2}
This optional parameter defines the level 3 grid element size. This level grid is rarely
required.
Assuming the number of system units to logical units is 100 and the logical units are
in meters, the following example defines a grid size of 12,800 meters for the level 2
grid.
SDE_GRID{2} 1280000
17-13 FME Reference Manual Version 2.0
Safe Software Inc. ESRI SDE READER/WRITER
17.7.7 SDE_DIMENSION
The SDE requires that all features within a layer have the same dimension. This
parameter defines the dimension of the layer. Currently the dimension can be either
2 or 3.
The example below defines the layer to have a dimension of 2.
SDE_DIMENSION 2
17.7.8 SDE_AVERAGE_PTS
This specifies the average number of coordinates for the features of the feature type
being defined.
The example below defines the average number of coordinates within features as 75.
SDE_AVERAGE_PTS 75
17.7.9 SDE_INIT_NUM_FEATS
This value identifies the initial number of features likely to be stored in the SDE for
the layer. This is used by the SDE to improve performance loading of features.
The example below defines the layer to have an initial number of features of 500.
SDE_INIT_NUM_FEATS 500
17.7.10 SDE_CONFIG_KEYWORD
The SDE configuration keyword specifies the storage parameters for the layer. The
configuration keyword specified must be present in the $SDEHOME/etc/
dbtune.sde file. See the SDE Users Manual for a full description.
The example below uses a configuration keyword of TEST.
SDE_CONFIG_KEYWORD TEST
17.7.11 SDE_GEOMETRY
This parameter defines the list of geometry entity types that may be stored within the
layer being defined. The geometry types currently supported are shown in the
following table.
TIP: One must be careful when defining layers. Be sure to understand the difference between a ring and a
polygon. They are quite different and, as such, support different operations.
ESRI SDE READER/WRITER Safe Software Inc.
17-14 FME Reference Manual Version 2.0
Multiple geometric entity types are specified using a comma-separated list.
The example given below enables the layer to store point, linestring, and polygon
entity types.
SDE_GEOMETRY (sde_point, sde_linestring,sde_polygon)
If an attempt is made to store features with a geometry different than those specified
in the SDE_Geometry statement, then the feature is rejected by the SDE. The SDE
writer logs the problem feature the FME log file.
17.7.12 SDE_SECURITYCLASS
This optional parameter defines the security class for the layer when it is created. If
the parameter is not specified, then the security class of 0 is used at the time the layer
is created. The security class parameter is only used during layer creation. The values
for the security class are between 1 and 255 as defined in the SDE documentation.
In most cases this parameter is not specified.
Geometry Type Description
sde_point Consists of a single coordinate.
sde_pointcluster A single feature that contains a collection of two or more
unconnected points.
sde_spaghetti A feature in which no integrity rules are enforced. The feature
may cross over itself in any fashion any number of times.
sde_linestring A linear feature that does not cross or touch itself at any
location.
sde_ring A linear feature that has the same start and end points. The
ring cannot touch or cross over itself at any other point.
sde_polygon An area feature consisting of a single shell.
sde_donutpolygon An area feature consisting of a single outer shell and one or
more holes.
The geometries specified within the FME mapping file are only used during layer creation. If a
new geometric entity type is to be added to an existing layer, it must be done using the SDE
Administration Utility supplied by ESRI.
For the FME to operate correctly, the SDE_GEOMETRY list must be consistent with the current
state of the associated layer.
17-15 FME Reference Manual Version 2.0
Safe Software Inc. ESRI SDE READER/WRITER
The example below defines a security class of 1, thereby granting security class 1
access to the new layer.
SDE_SECURITYCLASS 1
17.7.13 Attribute Definitions
This section of the SDE_DEF statement defines the attributes for a layer. If a layer
has no attributes defined, then this section is omitted.
The <attribute name> specified within the FME mapping file must obey
the following rules:
Attribute Names must be in uppercase.
Attribute Names must obey all length and character restrictions of the SDE.
The <attribute definition> defines the type and optionality of the
attribute, and has the following form:
<attribute type>,(optional|required)
The supported attribute types are listed below.
a. The current implementation of blobs is restricted to unbounded strings. Support
for generic binary objects is planned. When the SDE is on the Oracle DBMS, a
single blob is permitted for each SDE feature type.
b. The current FME implementation doesnt support the date type. Support for this
is planned. Currently, all dates are stored by the FME as integers in the form
YYYYMMDD. This has less accuracy than the SDE date but is sufficiently
accurate for all current users.
c. This is only available on the Oracle version of the SDE.
FME Attribute Type SDE Attribute Type C Data Type
smallint SE_SMALLINT short integer
integer SE_INTEGER long integer
float SE_FLOAT float
double SE_DOUBLE double
char(n) SE_STRING char[n]
blob
a
SE_BLOB void *
date
b
SE_DATE struct tm
varchar2
c
SE_STRING char *
ESRI SDE READER/WRITER Safe Software Inc.
17-16 FME Reference Manual Version 2.0
Immediately following the attribute type is the keyword optional or required
indicating if the attribute is required. Features in which a required attribute is not
specified, cannot be stored within the SDE dataset.
The following example creates a required attribute called NUMOFLANES which is
of type integer.
NUMOFLANES integer,required
17.7.14 SDE_INDEX{#}
The final parameter on the SDE_DEF line is one or more instances of the
SDE_INDEX{#} clauses. This is used to define attribute indices. Attribute indices
are used to increase the performance of queries having an attribute component.
Each index definition is identified by a number enclosed in parenthesis. The first
index must end in {0}, the second in {1}, and so on.
The following example creates an attribute index on the field NUMOFLANES.
SDE_INDEX{0} NUMOFLANES,SDE_ASCEND
TIP: When creating layer definitions it is easier to use an existing definition as a starting point than starting from
scratch.
17.7.15 Example of a Layer Definition
Finally, putting all of the pieces together to define an SDE layer results in the
following structure.
MACRO BaseName Cadastral
MACRO BaseLayer 1000
SDE_DEF Township::$(BaseName) \
SDE_BASE_LAYER $(BaseLayer) \
SDE_LAYER 20 \
SDE_GRID{0} 100000 \
SDE_DIMENSION 2 \
SDE_AVERAGE_PTS 75 \
SDE_INIT_NUM_FEATS 500 \
SDE_CONFIG_KEYWORD DEFAULTS \
SDE_GEOMETRY (sde_polygon) \
PPID char(10),required \
TOWNSHIPID char(4),optional \
TOWNSHIP char(3),optional \
RANGE char(3),optional \
MERIDIAN char(1),optional \
DATECHNG integer,optional \
BOUNDARY blob,optional
17-17 FME Reference Manual Version 2.0
Safe Software Inc. ESRI SDE READER/WRITER
17.8 Feature Representation
The SDE modules make use of the following special attribute names. With the
exception of the annotation location and angle, the names are used only by the SDE
reader.
Attribute Name Contents SDE Module
Applicability
SDE_INSIDEPOINT.X The X coordinate of the centroid
calculated by the SDE for a
polygonal feature. If the feature was
not polygonal, this value will be
meaningless.
Reader only
SDE_INSIDEPOINT.Y The Y coordinate of the centroid
calculated by the SDE for a
polygonal feature. If the feature was
not polygonal, this value will be
meaningless.
Reader only
SDE_ANNOTATIONLOCATION.X The X coordinate of the annotation
location stored with each SDE
feature.
Reader and Writer
SDE_ANNOTATIONLOCATION.Y The Y coordinate of the annotation
location stored with each SDE
feature.
Reader and Writer
SDE_ANNOTATIONANGLE The annotation angle stored with
each SDE feature. The value is
measured in degrees counter-
clockwise from horizontal, and is
accurate to the second.
Reader and Writer
SDE_SYMBOLNUMBER The number of the symbol associated
with each SDE feature. The value is a
16 bit integer.
Reader and Writer
SDE_AREA The area of the feature; 0 for point
and linear features.
Reader only
SDE_LENGTH The length of the linear feature or the
perimeter of an area feature.
Reader only
SDE_UID The feature identifier which is unique
within a feature layer.
Reader only
SDE_LAYER The layer number from which the
feature was read.
Reader only
ESRI SDE READER/WRITER Safe Software Inc.
17-18 FME Reference Manual Version 2.0
Aside from the predefined attributes given in the table above, the SDE correlation
lines are the same as the correlation lines for the other formats used by the FME.
Using the default prefix of SDE for illustration purposes, a typical SDE line is as
follows.
SDE <layerName> [<attribute name> <attribute value>]*
For example, a compatible correlation line for the SDE_DEF line given above is:
SDE Township::$(BaseName)PPID %ppid \
TOWNSHIPIDENTIFIER %tpid \
TOWNSHIP %tcode \
RANGE %range \
MERIDIAN %meridian \
DATEOFCHANGE %date
17.9 SDE Control File Examples
This section presents two samples of complete SDE control files.
17.9.1 Example 1: SDE <-> MapInfo
This first example shows an SDE control file that can be used to convert files to and
from the MapInfo Interchange Format (MIF). The liberal use of macros, shown in this
example, greatly enhances the readability of the FME mapping files.
LOG_FILENAME c:\tmp\mifsde.log
WRITER_TYPE SDE
READER_TYPE MIF
# Stuff the MIF reader needs to know.
MIF_DATASET c:\tmp\mergdata
SDE_GEOMETRY_
TYPE
The type of geometric entity stored
within the feature. The valid values
are listed below, with the
corresponding SDE Application
Programming Interface (API) entity
type number in parentheses:
sde_point (1)
sde_spaghetti (2)
sde_linestring (3)
sde_ring (4)
sde_polygon (5)
sde_donutpolygon (6)
sde_pointcluster (7)
Reader only
Attribute Name Contents SDE Module
Applicability
17-19 FME Reference Manual Version 2.0
Safe Software Inc. ESRI SDE READER/WRITER
# Stuff the SDE needs to know about.
SDE_DATASET testdset
SDE_SERVER tuvok
SDE_USERID dcm
SDE_PASSWORD test
SDE_TRANSACTION 0
SDE_LOGFILE mergtest
# A few macros to simplify the rest of the tables.
MACRO BaseName MIFTest
MACRO BaseLayer 1050
#---------------------------------------------------------------
# Color macros -- nice names for the 24 bit integers which are 8 bits of RGB
MACRO red 16711680
MACRO yellow 16776960
MACRO green 65280
MACRO blue 255
MACRO black 0
MACRO magenta 16711935
MACRO cyan 65535
MACRO grey 12632256
MACRO purple 8388736
MACRO white 16777215
#---------------------------------------------------------------
# Pen pattern macros -- give names to some common line types
MACRO forwardArrow 59
MACRO railLine 69
MACRO thickRoad 74
MACRO thinRoad 77
MACRO solidPen 2
MACRO dotted 3
MACRO dashed 5
MACRO wideDashed 7
MACRO widestDashed 8
#---------------------------------------------------------------
# Pen thickness macros -- give names to some thicknesses
MACRO thick 1
MACRO thin 0
#---------------------------------------------------------------
# Symbol macros -- give names to some symbols
MACRO solidStar 35
MACRO solidCircle 34
MACRO solidSquare 32
MACRO solidDiamond 33
MACRO clearStar 41
MACRO clearCircle 40
MACRO clearSquare 38
MACRO clearDiamond 39
MACRO plus 49
MACRO asterisk 51
MACRO tower 63
MACRO building 60
ESRI SDE READER/WRITER Safe Software Inc.
17-20 FME Reference Manual Version 2.0
MACRO plane 52
MACRO dock 58
MACRO monument 66
MACRO landmark 67
MACRO ex 50
# 10 meter symbols
MACRO symbolSize 10
#---------------------------------------------------------------
# Brush patterns
MACRO smallCheckers 47
MACRO bigGravel 48
MACRO speckles 49
MACRO rightDiag 32
MACRO leftDiag 37
MACRO solid 2
MACRO clear 1
MACRO darkMesh 45
MACRO heavy 15
MACRO horizontal 23
MACRO vertical 28
# The file used for input
MIF_IDs roads
#
# The MIF definition which defines the look of the feature when
# stored in MIF.
#
MIF_DEF roads \
numberOfLanes smallint \
surfaceType char(5) \
underConstruction logical \
divided logical \
travelDirection char(6)
# The layer to use for input.
SDE_IDs Roads::$(OutputBaseName)
#
# The following definition defines the layer within the
# SDE in which the features are to be stored.
#
SDE_DEF Roads::$(BaseName) \
SDE_BASE_LAYER $(BaseLayer) \
SDE_LAYER 1 \
SDE_GRID{0} 100000 \
SDE_DIMENSION 2 \
SDE_AVERAGE_PTS 75 \
SDE_INIT_NUM_FEATS 500 \
SDE_CONFIG_KEYWORD MAPS \
SDE_GEOMETRY (sde_linestring,sde_polygon) \
SURFACETYPE char(5),required \
NUMBEROFLANES integer,optional \
TRAVELDIRECTION char(6),optional \
17-21 FME Reference Manual Version 2.0
Safe Software Inc. ESRI SDE READER/WRITER
DIVIDED char(5),optional \
UNDERCONSTRUCTION char(5),optional
#
# This defines a correlation line used to transfer features
# between the SDE to MapInfo MIF.
#
SDE Roads::$(BaseName)SURFACETYPE %surfaceType \
NUMBEROFLANES %numberOfLanes \
TRAVELDIRECTION %travelDirection \
DIVIDED %divided \
UNDERCONSTRUCTION %underConstruction
MIF roads numberOfLanes %numberOfLanes \
surfaceType %surfaceType \
underConstruction %underConstruction \
divided %divided \
travelDirection %travelDirection \
@SupplyAttriutes(mif_type,polyline,mif_pen_width,$(thick)) \
@SupplyAttributes(mif_pen_pattern,$(thickRoad)) \
@SupplyAttributes(mif_pen_color,$(magenta))
17.9.2 Example 2: SDE<->SDE
The second example shows an FME mapping file for controlling SDE<-> SDE
transformations. This mapping file example is used to perform generalization
operations on features stored within the SDE.
#
#This is the mapping file which demonstrates the use of an SDE to SDE
#translation.
#
LOG_FILENAME c:/gensde.txt
READER_TYPE SDE
WRITER_TYPE SDE
READER_KEYWORD SDE_INPUT
WRITER_KEYWORD SDE_OUTPUT
# A few macros to simplify the rest of the tables.
MACRO OutputBaseName Generalized
MACRO InputBaseName TownShip
MACRO BaseLayer 4000
#
# First the global stuff.
#
# This section specifies the SDE global information
Both reader and writer types are the same!
SDE_DATASET testdset
SDE_IDs Township::$(InputBaseName)
SDE_SERVER tuvok
ESRI SDE READER/WRITER Safe Software Inc.
17-22 FME Reference Manual Version 2.0
SDE_USERID dcm
SDE_PASSWORD x
SDE_TRANSACTION 0
#
# We log all of the generalized features.
SDE_LOGFILE genrlize2.log
# Define an output layer. This is the layer which is used for
# the output generalized features.
#
SDE_DEF Township::$(OutputBaseName) \
SDE_BASE_LAYER $(BaseLayer) \
SDE_LAYER 23 \
SDE_GRID{0} 100000 \
SDE_DIMENSION 2 \
SDE_AVERAGE_PTS 15 \
SDE_INIT_NUM_FEATS 200 \
SDE_CONFIG_KEYWORD small \
SDE_GEOMETRY (sde_polygon, sde_point) \
PPID char(10),required \
TOWNSHIPIDENTIFIER char(4),optional \
TOWNSHIP char(3),optional \
RANGE char(3),optional \
MERIDIAN char(1),optional \
DATEOFCHANGE integer,optional
#
# define the input feature
SDE_INPUT Township::$(InputBaseName) PPID %ppid \
TOWNSHIPIDENTIFIER %townshipIdent \
TOWNSHIP %township \
RANGE %range \
MERIDIAN %meridian \
DATEOFCHANGE %dateOfChange \
SDE_INSIDEPOINT.X %x \
SDE_INSIDEPOINT.Y %y \
SDE_AREA %area \
SDE_LENGTH %length \
BOUNDARYELMENTS %boundary
# define the output feature value. All attributes are passed
# across.
# The output feature is also generalized by calling the generalize
# function.
SDE_OUTPUT Township::$(OutputBaseName) PPID %ppid \
TOWNSHIPIDENTIFIER %townshipIdent \
TOWNSHIP %township \
RANGE %range \
MERIDIAN %meridian \
SDE_INSIDEPOINT.X %x \
SDE_INSIDEPOINT.Y %y \
DATEOFCHANGE %dateOfChange \
@Generalize(Douglas,0.5) \
@Log()
18-1 FME Reference Manual Version 2.0
18
18 GIF IMAGE WRITER
The Graphics Interchange Format (GIF) writer enables the Feature
Manipulation Engine (FME) to be used in conjunction with the world wide
web to translate vector data on-the-fly for display in web browsers. It also
enables the FME to be used as a powerful gateway between vector geographic
data and raster-based Geographical Information Systems (GIS). In the future,
more raster output formats and georeferencing control will be added to the
FME.
18.1 Overview
GIF files are compressed raster images files. CompuServe designed the
format long ago as an efficient means of transporting images across low speed
networks. The format is one of two standard image formats used by most
world wide web browsers.
GIF images consist of eight bit pixels. The value of each pixel is an index to
a color table, having eight bits each of red, green and blue. Therefore, a single
GIF image may have at most 256 different colors in it, although these colors
are chosen from a range of 2^24 different colors.
GIF images support the notion of a transparent color. A special code is
appended to the GIF image stating that a certain color index is to be
considered transparent. Applications understanding this code not all do
then allow the background to appear through the transparent pixels. This is
often used to create attractive world wide web displays, since most web
browsers understand the transparent color directive. The FME GIF writer
GIF IMAGE WRITER Safe Software Inc.
18-2 FME Reference Manual Version 2.0
module allows a transparent color index to be specified and it honours the transparent
pixel when GIFs are used as point symbols, line styles, or tiling fill patterns for
polygons.
A GIF image background may be a solid color or it may be a tiled background pattern.
The FME GIF writer supports either choice although if a background pattern is to be
used, the pattern must come from another GIF file.
GIF images may be interlaced or non-interlaced. Interlaced GIF images download
into many web browsers faster because the coarse image is displayed first, followed
by more detail. The FME GIF writer supports both interlaced and non-interlaced
output.
The FME does not allow raster formats to be used as input, therefore there is no GIF
reader module.
18.2 Writer Overview
The FME GIF writer creates a single GIF image and draws points, lines, and polygons
into it. The filename, window, size, background, color table, transparency, and
interlacing of the output image are all determined by mapping file settings. Each
feature written to the image contains special attributes used to determine the
appearance of the feature.
Feature types in GIFs are color entries. The color table entries are defined in
GIF_DEF statements. All GIF features with the specified color name are drawn in
that color.
18.3 Writer Keywords
The following table lists the keywords processed by the GIF writer. The table shows
only the suffixes prefixed by the current <WriterKeyword> in a mapping file.
By default, the <WriterKeyword> for the GIF writer is GIF.
Keyboard Suffix Value Required/
Optional
DATASET Contains the filename of the output GIF file. Required
DEF Defines a color to be used in the output GIF file. The
defined color will be used as the feature type of each GIF
feature to determine its color setting. Each color must be
defined before it can be used. There may be many DEF
lines, one for each color appearing in the output image.
Required
18-3 FME Reference Manual Version 2.0
Safe Software Inc. GIF IMAGE WRITER
18.3.1 DATASET
The value for this keyword is the name of the GIF file to be created. If a file of this
name exists, it is replaced by the new GIF. A typical mapping file fragment specifying
an output GIF dataset looks like:
GIF_DATASET /tmp/92i080.gif
WIDTH Defines the width of the output GIF file in pixels. Pixels
remain square in terms of original ground units, so a
portion of the GIF produced may be filled with the
background if the aspect ratio of the desired GIF did not
match the aspect ratio of the input datas bounding box.
Required
HEIGHT Defines the height of the output GIF file in pixels. Required
GROUND_
RANGE
Defines the area of coverage in ground units of the GIF
image. If this is not specified, then the coverage area is
determined from the minimum bounding rectangle of the
data.
Optional
BACKGROUND_
COLOR
Defines the background color for the GIF image. The
color must have previously been defined in a GIF_DEF
line. One of BACKGROUND_COLOR or
BACKGROUND_IMAGE must be supplied.
Optional
BACKGROUND_
IMAGE
Contains the filename of a GIF file to be used as the
background for the produced image. Lines, polygons,
text, and points are drawn on top of this image. If the
image is smaller than the size of the output GIF, it is tiled
to fill the output image. One of BACKGROUND_COLOR or
BACKGROUND_IMAGE must be supplied.
Optional
INTERLACE Controls whether or not the created GIF will be
interlaced. If the value is YES, the GIF will be interlaced.
If the value is NO, then the GIF will not be interlaced. The
default is YES.
Interlacing is used most often in web applications, as an
interlaced GIF gives the illusion of being displayed
quicker than a non-interlaced GIF.
Optional
TRANSPARENT_
COLOR
This optional parameter defines the name of the color that
will be considered transparent by applications using the
produced GIF. Not all applications support a transparent
color which allows the background to shine through the
GIF.
Optional
SQUARE_PIXELS If this is specified as YES, each pixel in the generated GIF
will have the same height as width.
If it is specified as NO, then the pixel height and width are
adjusted to completely fit the ground range of the data
into the GIF.
The default is YES.
Optional
Keyboard Suffix Value Required/
Optional
GIF IMAGE WRITER Safe Software Inc.
18-4 FME Reference Manual Version 2.0
18.3.2 DEF
The GIF writer uses GIF_DEF lines to define colors. The names given to colors are
used as the feature types of features destined for the GIF writer. The GIF writer will
allocate a color index in the GIFs color table for this color, and this index will be used
the pixel value for features whose feature type matches the color name.
Up to 255 different 24 bit colors may be defined. If the GIF writer cannot allocate a
color exactly perhaps due to the color table being partially filled with a background
images colors it assigns a color value as close as possible to the one requested.
The syntax of a GIF DEF line is:
<WriterKeyword>_DEF <colorName> \
GIF_RED <redValue> \
GIF_BLUE <blueValue> \
GIF_GREEN <greenValue>
The red, green, and blue values must be between 0 (low intensity) and 255 (highest
intensity), and if they are not specified, then 0 is assumed. The color components be
specified in any order.
The mapping file fragment below defines two GIF colors:
GIF_DEF white GIF_RED 255 GIF_GREEN 255 GIF_BLUE 255
GIF_DEF black GIF_RED 0 GIF_GREEN 0 GIF_BLUE 0
18.3.3 WIDTH
This keyword controls the width of the output GIF image. The syntax of a GIF
WIDTH line is:
<WriterKeyword>_WIDTH <widthInPixels>
18.3.4 HEIGHT
This keyword controls the height of the output GIF image. The syntax of a GIF
HEIGHT line is:
<WriterKeyword>_HEIGHT <heightInPixels>
The GIF writer scales the source feature data to fit it into the desired image size.
However, it ensures that all pixels remain square in terms of the original ground units
of the features. This results in a blank band of background being present across either
the bottom or the right-hand side of the produced image if the aspect ratio of the
image did not match the aspect ratio of the input source data. In the future, an option
to clip off this blank band will be introduced in to the software.
18-5 FME Reference Manual Version 2.0
Safe Software Inc. GIF IMAGE WRITER
18.3.5 GROUND_RANGE
This keyword fixes the area that the GIF image will cover in ground units. If this is
not specified, the GIF covers the minimum bounding rectangle of the feature data. If
necessary, the ground coverage is adjusted, not the size of the image in pixels, to
maintain squareness of pixels. For this reason, the aspect ratio of the
GROUND_RANGE setting must be the same as the aspect ratio of the height and width
to ensure that the image provides exactly the desired coverage. The syntax of a GIF
GROUND_RANGE line is:
<WriterKeyword>_GROUND_RANGE <xmin> <xmax> <ymin>\
<ymax>
18.3.6 SQUARE_PIXELS
This flag controls whether the pixels of the GIF produced will have the same height
as width. If the value is YES, which is the default, the ground range is fit into the
output GIF image. If necessary, some of the output image is left in the background
color providing the aspect ratio of the input data did not match that of the output
image. If the value is NO, then the pixels are stretched to fill the entire output image.
The syntax of a GIF SQUARE_PIXELS line is:
<WriterKeyword>_SQUARE_PIXELS (YES|NO)
18.3.7 BACKGROUND_COLOR
This setting establishes the color index of the image background and is required if a
BACKGROUND_PATTERN is not specified. The syntax of a GIF
BACKGROUND_COLOR line is:
<WriterKeyword>_BACKGROUND_COLOR <colorName>
The colorName must be defined in a GIF_DEF statement.
18.3.8 BACKGROUND_PATTERN
When this is specified, it names a GIF file to be used as a background pattern for the
image. If the pattern is smaller than the image, it will be tiled. If it is larger, it will be
clipped. In either case, the features will be drawn on top of the background pattern.
The syntax of a GIF BACKGROUND_PATTERN line is:
<WriterKeyword>_BACKGROUND_PATTERN <backgroundGIF>
The backgroundGIF must be the name of a valid GIF file.
GIF IMAGE WRITER Safe Software Inc.
18-6 FME Reference Manual Version 2.0
18.3.9 INTERLACE
This setting determines the interlacing of the output image. The syntax of a GIF
INTERLACE line is:
<WriterKeyword>_INTERLACE (YES|NO)
The default is YES.
18.3.10 TRANSPARENT_COLOR
This flag sets the transparent color index of the image. Applications that interpret this
will show the background through any pixels with this color when the image is
displayed. The syntax of a GIF TRANSPARENT_COLOR line is:
<WriterKeyword>_TRANSPARENT_COLOR <colorName>
The colorName must have been previously defined in a GIF_DEF statement.
18.4 Feature Representation
The FME considers the FME feature type of a GIF-destined feature to be its color.
The feature type must match a color name defined by a GIF_DEF line.
Special FME feature attributes direct the GIF writer as it renders the feature into the
image. The most important of these is the gif_type attribute because it controls the
overall interpretation of the feature. The acceptable values for gif_type are
gif_text, gif_line, gif_polygon, and gif_point. The parameters
specified to each of these are described in subsequent sections.
18.4.1 Polygons
gif_type: gif_polygon
The GIF writer renders polygonal features first, so as not to obscure any linear, text,
or point features.
The boundary is rendered in the same manner as a gif_line. It is drawn in the color
named by the polygonal features feature type. The gif_line attributes
described in the next subsection are all interpreted when a gif_polygon is
output.
In addition to rendering the boundary of a polygon, the GIF writer also fills the
polygon with either a solid color or a pattern. The feature attributes, described in the
18-7 FME Reference Manual Version 2.0
Safe Software Inc. GIF IMAGE WRITER
following table, control the filling of a polygonal feature. If neither attribute is
specified, the polygon is not filled.
The GIF writer correctly renders donut polygons by drawing the hole boundaries in
the same color as the outer boundary and not filling them.
18.4.2 Lines
gif_type: gif_line
The GIF writer renders linear features into the image after all polygons have been
drawn. Linear features must have at least two points.
The GIF writer supports a variety of line rendering options, controlled by the features
attributes. The color for the line is taken from the features feature type. By default,
if none of the attributes listed below are specified, a single pixel-width solid line is
drawn.
Attribute Name Contents
gif_fill_color This attribute holds the name of the color used
to fill the polygon. This attribute must not be
present if the gif_fill_image is set.
Range: Any defined color name
Optional: Yes
gif_fill_image The GIF writer can fill the polygon using an
arbitrary pattern as a brush. The value of this
attribute is the name of a GIF file to be used as
the brush. If the brush image contains any
transparent pixels, they will be interpreted
correctly and will not obscure any image data
already present in the image. If the image is
too large to fit into the polygon, it is clipped
and if it is too small, it will be tiled. This
attribute must not be present if the
gif_fill_color is set.
Range: Any valid GIF file
Optional: Yes.
Attribute Name Contents
gif_brush_width By default, the line drawn is one pixel wide. If
a thicker line is desired, this attribute is used to
set the width. This attribute must not be
present if the gif_brush_image is set.
Range: Integer > 1
Optional: Yes
GIF IMAGE WRITER Safe Software Inc.
18-8 FME Reference Manual Version 2.0
18.4.3 Points
gif_type: gif_point
The GIF writer renders point features into the image after all polygons and lines have
been drawn. Point features must not have more than one coordinate.
By default, a point is rendered as a single pixel in the color named by the feature type
of the point feature. The attributes below may be set to alter this rendering.
gif_brush_image The GIF writer draws the line using an
arbitrary pattern as a brush. The value of this
attribute is the name of a GIF file to be used as
the brush. If the brush image contains any
transparent pixels, they are correctly
interpreted and will not obscure any image
data already present in the image. This
attribute must not be present if the
gif_brush_width is set.
Range: Any valid GIF file
Optional: Yes
gif_dash_on The number of pixels to be used as the on
part of the dashed line used to draw the
feature. If gif_brush_width or
gif_brush_image are specified, then this
value is multiplied by the size of the brush to
determine the number of pixels.
Range: Integer > 0
Optional: Yes
gif_dash_off The number of pixels to be used as the off
part of the dashed line used to draw the
feature. If gif_brush_width or
gif_brush_image have been specified, this
value is multiplied by the size of the brush to
determine the number of pixels.
Range: Integer > 0
Optional: Yes.
Attribute Name Contents
gif_dot_size By default, the point drawn is drawn as a one
pixel dot. If a thicker dot is desired, this
attribute is used to set the width and height of
a square box drawn at the points location.
This attribute must not be present if the
gif_symbol_image is set.
Range: Integer > 1
Optional: Yes
Attribute Name Contents
18-9 FME Reference Manual Version 2.0
Safe Software Inc. GIF IMAGE WRITER
18.4.4 Text
gif_type: gif_text
The GIF writer renders text features into the image after all polygons, points, and
lines have been drawn. Currently, the text cannot be rotated, but this may be
supported in a future release. As well, the font selection is limited to five predefined
fonts.
Text features must have a single point as their coordinate. The text string is output
centered around this point. If the text string would extend past the bounds of the
image, it is clipped. Future releases may allow more flexible justification of the text.
GIF text features have the following attributes:
gif_symbol_image The GIF writer can draw the point using an
arbitrary symbol. The value of this attribute is
the name of a GIF file to be used as the
symbol. If the symbol contains any transparent
pixels, they will be interpreted correctly and
will not obscure any image data already
present in the image. This attribute must not be
present if the gif_dot_size is set.
Range: Any valid GIF file
Optional: Yes
gif_symbol_scale_x When the gif_symbol_image is specified,
this parameter is used to scale the image in the
x direction. A value of 1 leaves the symbol
unchanged. A value between zero and one
shrinks the image, while a value greater than
one increases the image.
Range: Integer > 0
Default: 1
Optional: Yes (allowed only when
gif_symbol_image is set)
gif_symbol_scale_y When the gif_symbol_image is specified,
this parameter is used to scale the image in the
y direction.
Range: Integer > 0
Default: 1
Optional: Yes (only allowed when
gif_symbol_image is set)
Attribute Name Contents
gif_text_string The text string to be drawn into the image. It
may contain blanks and there is no limit on its
length.
This attribute must be present for all
gif_text features.
Attribute Name Contents
GIF IMAGE WRITER Safe Software Inc.
18-10 FME Reference Manual Version 2.0
18.5 Example
The example below shows an FME mapping file used to render the Road features
in a SAIF dataset into a GIF.
# -----------------------------------------------------------------------
# Set up for SAIF to GIF translation
READER_TYPE SAIF
WRITER_TYPE GIF
# -----------------------------------------------------------------------
# Define the input and output files
SAIF_DATASET h:/saifdata/92c090/92c090.zip
GIF_DATASET c:/tmp/roads.gif
# -----------------------------------------------------------------------
# Only extract the roads from the SAIF file
SAIF_IDs Roads
# -----------------------------------------------------------------------
# Keep a log of the activity
LOG_FILENAME c:/tmp/gif.log
# -----------------------------------------------------------------------
# Define some GIF colors
GIF_DEF white GIF_RED 255 GIF_BLUE 255 GIF_GREEN 255
GIF_DEF green GIF_RED 0 GIF_BLUE 0 GIF_GREEN 255
GIF_DEF black GIF_RED 0 GIF_BLUE 0 GIF_GREEN 0
# -----------------------------------------------------------------------
# Set the background color of the GIF
GIF_BACKGROUND_COLOR white
# -----------------------------------------------------------------------
# Make a square GIF, 400 pixels by 400 pixels
GIF_WIDTH 400
GIF_HEIGHT 400
# -----------------------------------------------------------------------
# Now correlate the SAIF roads into out GIF.
# First, make all the rough roads come out in 4 pixel wide black dotted
# lines
SAIF Road::TRIM surfaceType rough
GIF black gif_type gif_line gif_dash_on 2 gif_dash_off 2 gif_brush_width 4
# -----------------------------------------------------------------------
# For loose roads, well draw a solid black line whose width will be the
# number of lanes
gif_font The font to be used to render the text.
Range: One of:
gif_font_tiny
gif_font_small
gif_font_medium
gif_font_large
gif_font_giant
Attribute Name Contents
18-11 FME Reference Manual Version 2.0
Safe Software Inc. GIF IMAGE WRITER
SAIF Road::TRIM surfaceType loose numberOfLanes %numLanes
GIF black gif_type gif_line gif_brush_width %numLanes
# -----------------------------------------------------------------------
# For paved roads, well draw a dashed green line whose width, (and
# dash interval) will be the number of lanes
SAIF Road::TRIM surfaceType paved numberOfLanes %numLanes
GIF green gif_type gif_line gif_brush_width %numLanes \
gif_dash_on %numLanes \
gif_dash_off %numLanes
GIF IMAGE WRITER Safe Software Inc.
18-12 FME Reference Manual Version 2.0
19-1 FME Reference Manual Version 2.0
19
19 MAPINFO DATA INTERCHANGE
FORMAT READER/WRITER
The MapInfo Data Interchange Format (MIF) reader and writer modules
provide the Feature Manipulation Engine (FME) with the ability to read and
write MapInfo import and export files. The MIF is a published ASCII format
used by the MapInfo product for input and export. The MapInfo Reference
Manual describes the MIF format and all constants it uses for color, style,
symbol, and fill patterns.
MapInfo Interchange Format Files are often called mif or mif/mid files.
19.1 Overview
MapInfo is a two-dimensional system with no provision for transferring
elevation data for each vertex in a MapInfo feature. However, point features
can define an elevation attribute to store their elevation.
MIF files store both feature geometry and attribution. A logical MIF file
consists of two physical files, having the following filename extensions:
Filename Extension Contents
.mif Vector geometric data.
.mid Attributes for the geometric data.
MAPINFO DATA INTERCHANGE FORMAT READER/WRITER Safe Software Inc.
19-2 FME Reference Manual Version 2.0
These extensions are added to the basename of the MIF file.
The MapInfo reader and writer support the storage of point, line, polyline, arc, ellipse,
rectangle, rounded rectangle, region (polygon), and text geometric data in .mif
files. The MIF format also stores features with no geometry. Features having no
geometry are referred to as having a geometry of none.
Each geometric entity present in a .mif file has display properties such as pen and
brush width, pattern, and color. In addition, each entity has a row of attributes stored
in an associated .mid file. A single .mif file contains many different types of
geometry however, the associated attribute in the .mid file must have the same
number and type of fields for each entity in the .mif file. The order of the entries in
the two files is synchronized. For example, the second geometric entity in the .mif
file has the attributes held in the second row of the .mid file.
The number and type of attributes associated with each entity is specified by the user.
There must be at least one attribute field in the .mid file.
The following example shows a MIF file containing three region entities in it. Note
that the second polygon contains a hole, and the third polygon is an aggregate of two
disjoint polygons, one of which contains a hole. Each geometric entity in turn
corresponds with one record in the attribute table.
The FME considers a MIF dataset to be a collection of MIF files in a single directory.
The attribute definitions for each MIF file must be defined in the mapping file before
it can be read or written.
.mif Geometry File .mid Attribute File
Pen 1,1,12
Brush 3,2,10
Pen 1,1,12
Brush 4,3,9
Pen 2,1,13
Brush 3,2,10
DEPTH LAKE_NAME
10
15
25
Smokey Lake
Beaver Hill Lake
Swan Lake
19-3 FME Reference Manual Version 2.0
Safe Software Inc. MAPINFO DATA INTERCHANGE FORMAT READER/WRITER
19.2 Reader Overview
The MIF reader first scans the directory it is given for the MIF files defined in the
mapping file. For each MIF file that it finds, it checks to see if it that file is requested
by looking at the list of IDs specified in the mapping file. If a match is made or no
IDs were specified in the mapping file, the MIF file is opened. The MIF reader then
extracts features from the file one at a time, and passes them on to the rest of the FME
for further processing. When the file is exhausted, the MIF reader starts on the next
file in the directory.
19.2.1 Reader Keywords
The following table lists the keywords processed by the MIF reader. The suffixes
shown are prefixed by the current <ReaderKeyword> in a mapping file. By
default, the <ReaderKeyword> for the MIF reader is MIF.
19.2.2 DATASET
The value for this keyword is the directory containing the MIF files to be read. A
typical mapping file fragment specifying an input MIF dataset looks like:
MIF_DATASET /usr/data/mapinfo/92i080
19.2.3 DEF
Each MIF file must be defined before it can be read. The definition specifies the base
name of the file, and the names and the types of all attributes. The syntax of a MIF
DEF line is:
<ReaderKeyword>_DEF <baseName> \
[<attrName> <attrType>]+
Keyword Suffix Value Required/
Optional
DATASET Contains the directory name of the input MIF files. Required
DEF Defines a MIF file. Each MIF file must be defined before
it can be read. The definition contains the files base
name without any of the extensions, and the definitions of
the attributes. There may be many DEF lines, one for each
file to be read.
Required
IDs Contains a list of MIF files to process. If this is not
specified, then all defined MIF files in the directory are
read.
Optional
MAPINFO DATA INTERCHANGE FORMAT READER/WRITER Safe Software Inc.
19-4 FME Reference Manual Version 2.0
The filenames of the physical MIF files is constructed by using the directory specified
by the DATASET keyword, the basename specified on the MIF DEF lines, and the
.mif (geometry) and .mid (attributes) extensions.
MIF files require at least one attribute to be defined. The attribute definition given
must match the definition of the file being read. If it does not, translation is halted and
the true definition of the MIF files attributes gets logged to the log file. There are no
restrictions on the field names of MIF attributes.
TIP: MapInfo decimal fields are analogous to DataBase Format (DBF) number fields. MapInfo also
provides float, integer, and smallint field types for storing numeric values.
The following table shows the attribute types supported.
The following mapping file fragment defines two MIF files. Notice that neither
definition specifies the geometric type of the entities it will contain since MIF files
may contain any of the valid geometry types.
MIF_DEF landcover \
area decimal(12,3) \
landcoverType char(11) \
perimeter float
MIF_DEF roads \
numberOfLanes smallint \
roadType char(5) \
underConstruction logical \
Field Type Description
char(<width>) Character fields store fixed length strings. The width
parameter controls the maximum number of characters
that can be stored by the field. No padding is required
for strings shorter than this width.
date Date fields store dates as character strings with the
format YYYYMMDD.
decimal(<width>,<decimals>) Decimal fields store single and double precision
floating point values. The width parameter is the total
number of characters allocated to the field, including
the decimal point. The decimals parameter controls
the precision of the data and is the number of digits to
the right of the decimal.
float Float fields store floating point values. There is no
ability to specify the precision and width of the field.
integer Integer fields store 32 bit signed integers.
logical Logical fields store TRUE/FALSE data. Data read or
written from and to such fields must always have a
value of either true or false.
smallint Small integer fields store 16 bit signed integers and
therefore have a range of -32767 to +32767.
19-5 FME Reference Manual Version 2.0
Safe Software Inc. MAPINFO DATA INTERCHANGE FORMAT READER/WRITER
divided logical \
travelDirection char(6)
19.2.4 IDs
This optional specification limits the available and defined MIF files read. If no IDs
are specified, then all defined and available MIF files are read.
The syntax of the IDs keyword is:
<ReaderKeyword>_IDs <baseName1> \
<baseName1> \
<baseNameN>
The basenames must match those used in DEF lines.
The example below selects only the roads MIF file for input during a translation:
MIF_IDs roads
19.3 Writer Overview
The MIF writer creates and writes feature data to MIF files in the directory specified
by the DATASET keyword. As with the reader, the directory must exist before the
translation occurs. Any old MIF files in the directory are overwritten with the new
feature data. As features are routed to the MIF writer, the MIF writer determines the
file into which the features are written and outputs them accordingly. Many MIF files
can be written during a single FME session.
19.3.1 Writer Keywords
The MIF writer processes the DATASET and DEF keywords as described in the
Reader Keywords section. It does not make use of the IDs keyword.
19.4 Feature Representation
MIF features consist of geometry and attributes. The attribute names are defined in
the DEF line and there is a value for each attribute in each MIF feature. In addition,
each MIF feature contains several special attributes to hold the type of the geometric
entity and its display parameters. All MIF features contain a mif_type attribute,
which identifies the geometric type. Depending on the geometric type, the feature
contains additional attributes specific to the geometric type. These are described in
subsequent sections.
MAPINFO DATA INTERCHANGE FORMAT READER/WRITER Safe Software Inc.
19-6 FME Reference Manual Version 2.0
19.4.1 Points
mif_type: mif_point
MIF point features specify a single x and y coordinate in addition to any associated
user-defined attributes. A MIF point also specifies a symbol. The symbol is defined
by a symbol number, a color, and a size. If no symbol is defined for a point entity, the
previous symbol is used.
The table below lists the special FME attribute names used to control the MIF symbol
settings.
1
1. MapInfo symbols cannot be rotated. However, some 3
rd
party add-ons to MapInfo rotate symbols
based on a user-defined rotation attribute.
Attribute Name Contents
mif_type The MIF geometric type of this entity.
Range: mif_point|
mif_polyline|
mif_region|
mif_text|
mif_ellipse|
mif_arc|
mif_rectangle|
mif_rounded_rectangle|
mif_none
Default: No default
Attribute Name Contents
mif_symbol_color The color of the symbol. MapInfo colors are
defined in relative concentrations of red,
green, and blue. Each color ranges from 0 to
255, and the color value is calculated
according to the formula:
(red*65536) + (green*256) + blue
Range: 02^24 - 1
Default: 0 (black)
mif_symbol_shape The number of the symbol. See the MapInfo
Reference Manual for a list of the available
symbols.
Range: 31...67
Default: 41 (a star)
mif_symbol_size The point size of the symbol. Note that this
size is not scaled depending on the zoom level.
Range: Any integer number > 0
Default: 10
19-7 FME Reference Manual Version 2.0
Safe Software Inc. MAPINFO DATA INTERCHANGE FORMAT READER/WRITER
19.4.2 Font Points
mif_type: mif_font_point
MIF font point are very similar to MIF points, but allow a symbol based on a
TrueType font to be specified. In addition to the font, may specify rotation, color,
shape number, size, and style.
The table below lists the special FME attribute names used to control the MIF font
point settings:
19.4.3 Custom Points
mif_type: mif_custom_point
MIF custom points are very similar to MIF points, but allow a bitmap image to be
specified as the symbol to be drawn. In addition to the image, color, size, and style
may be specified.
Attribute Name Contents
mif_symbol_color The color of the symbol calculated according to the
formula:
(red*65536) + (green*256) + blue
Range: 02^24 - 1
Default: 0 (black)
mif_symbol_shape The number of the shape within the TrueType font to
be used as the symbol.
Range: Integer
Default: No default
mif_symbol_size The point size of the symbol.
Range: Integer
Default: 12
mif_symbol_font The name of the TrueType font to be used for the
symbol.
Range: String
Default: No default
mif_symbol_angle The rotation angle for the symbol, measured in
degrees counter-clockwise from horizontal.
Range: -360.0..360.0
Default: 0
mif_symbol_style The display style for the symbol.
Range: 0 (Plain text)
1 (Bold text)
16 (Black border around symbol)
32 (Drop Shadow)
256 (White border around symbol)
Default: 0
MAPINFO DATA INTERCHANGE FORMAT READER/WRITER Safe Software Inc.
19-8 FME Reference Manual Version 2.0
The table below lists the special FME attribute names used to control the MIF custom
point settings:
19.4.4 Polylines
mif_type: mif_polyline
MIF polyline features specify linear features defined by a sequence of x and y
coordinates. Each polyline has a pen style associated with it specifying the color,
width, and pen pattern of the line. A polyline may also specify that it is a smoothed
line, in which case MapInfo uses a curve fitting algorithm when rendering the line
2
.
If no pen style is defined, the previous style is used.
TIP: MapInfo MIF supports a special type for two point lines. The FME transparently converts such MIF lines
into polylines, both as it reads MIF files and as it writes them.
2. MapInfo renders smoothed polylines substantially slower than unsmoothed polylines.
Attribute Name Contents
mif_symbol_color The color of the symbol calculated according to the formula:
(red*65536) + (green*256) + blue
Whether or not the color is used depends on the setting of the
style attribute.
Range: 02^24 - 1
Default: 0 (black)
mif_symbol_file_name The name of the bitmap file found in the MapInfo CustSymb
directory.
Range: String
Default: No default
mif_symbol_size The point size of the symbol.
Range: Integer
Default: 12
mif_symbol_style The display style for the symbol.
Range: 0 (White pixels in the image are transparent,
allowing whatever is beneath to show
through. Non-white pixels are drawn in the
same color as they are in the bitmap.)
1 (White pixels in the image are drawn as white.
Non-white pixels are drawn in the same
color as they are in the bitmap.)
2 (White pixels in the image are transparent.
Non-white pixels are drawn in the color
specified by mif_symbol_color.)
3 (White pixels in the image are drawn in white.
Non-white pixels are drawn in the color
specified by mif_symbol_color)
Default: 0
19-9 FME Reference Manual Version 2.0
Safe Software Inc. MAPINFO DATA INTERCHANGE FORMAT READER/WRITER
The table below lists the special FME attribute names used to control the MIF
polyline settings.
19.4.5 Regions
mif_type: mif_region
MIF region features specify area (polygonal) features. The areas that make up a single
feature may or may not be disjoint, and may contain polygons that have holes. Each
region has a pen style associated with it to control the color, width, and pen pattern
used when its boundary is drawn. In addition, a region may set its brush pattern,
foreground, and background color to control how its enclosed area will be filled. If
no pen or brush style is defined for a region entity, the previous style is used. The
following table lists the special FME attribute names used to control the MIF region
settings.
Attribute Name Contents
mif_pen_color The color of the polyline. MapInfo colors are
defined in relative concentrations of red,
green, and blue. Each color ranges from 0 to
255, and the color value is calculated
according to the formula:
(red*65536) + (green*256) + blue
Range: 02^24 - 1
Default: 0 (black)
mif_pen_pattern The pattern used to draw the line. See the
MapInfo Reference Manual for a list of the
available patterns.
Range: 177
Default: 2
mif_pen_width The width of the line rendered for the polyline
feature. This is measured as a thickness in
pixels. 0 defines the thinnest line possible.
Range: 0..7
Default: 0
mif_smooth Controls whether or not the polyline will be
smoothed when rendered.
Range: true|false
Default: false
Attribute Name Contents
mif_brush_pattern The pattern used to fill the area the region
contains. See the MapInfo Reference Manual
for a list of the available brush patterns.
Range: 171
Default: 2 (solid)
MAPINFO DATA INTERCHANGE FORMAT READER/WRITER Safe Software Inc.
19-10 FME Reference Manual Version 2.0
19.4.6 Text
mif_type: mif_text
MIF text features are used to specify annotation information. Each text feature can
have its font, color, spacing, justification, and rotation angle set independently. The
following table lists the special FME attribute names used to control the MIF text
settings.
mif_brush_foreground The foreground color used when the region is
filled. MapInfo colors are defined in relative
concentrations of red, green, and blue. Each
color ranges from 0 to 255, and the color value
is calculated according to the formula:
(red*65536) + (green*256) + blue
Range: 02^24 - 1
Default: 0 (black)
mif_brush_background The background color used when the region is
filled.
Range: 02^24 - 1
Default: 0 (black)
mif_pen_color The color of the boundary of the region.
Range: 02^24 - 1
Default: 0 (black)
mif_pen_pattern The pattern used to draw the regions
boundary. See the MapInfo Reference Manual
for a list of the available patterns.
Range: 177
Default: 2
mif_pen_width The width of the line rendered for the regions
boundary. This is measured as a thickness in
pixels. 0 defines the thinnest line possible.
Range: 0..7
Default: 0
Attribute Name Contents
mif_rotation The rotation of the text, as measured in
degrees counter-clockwise from horizontal.
Range: -360.0..360.0
Default: 0
mif_text_fontbgcolor The background color used when the text is
drawn.
Range: 02^24 - 1
Default: 255 (blue)
Attribute Name Contents
19-11 FME Reference Manual Version 2.0
Safe Software Inc. MAPINFO DATA INTERCHANGE FORMAT READER/WRITER
TIP: The font colour and style settings will not be used unless a font name is specified.
19.4.7 Ellipse
mif_type: mif_ellipse
MIF ellipse features are point features, and have only a single coordinate. This point
serves as the center of the ellipse. Additional attributes specify the primary axis and
mif_text_fontfgcolor The foreground color used when the text is
drawn. MapInfo colors are defined in relative
concentrations of red, green, and blue. Each
color ranges from 0 to 255, and the color value
is calculated according to the formula:
(red*65536) + (green*256) + blue
Range: 02^24 - 1
Default: 0 (black)
mif_text_fontname The name of the font used to draw the text. The
font named must be available on the
destination computer system.
Range: Any valid system font
Default: Helve
mif_text_fontstyle The style code of the text. This controls if the
text is bold, underlined, or italic. See the
MapInfo Reference Manual for a list of style
codes and their meanings.
Range: 07
Default: 0 (regular text)
mif_text_height The height of the text in ground units.
Range: Any real number >= 0
Default: 10
mif_text_justification The justification of the text.
Range: left|center|right
Default: left
mif_text_spacing The spacing between lines of multiline text.
The measure is expressed as a multiple of the
text height.
Range: 1.0|1.5|2.0
Default: 1.0
mif_text_string The text to be displayed.
Range: Any character string
Default: No default
mif_text_width The width of each text character in ground
units.
Range: Any real number >= 0
Default: 10
Attribute Name Contents
MAPINFO DATA INTERCHANGE FORMAT READER/WRITER Safe Software Inc.
19-12 FME Reference Manual Version 2.0
secondary axis of the ellipse. MIF ellipses currently do not support rotation. For
compatibility with other systems, the MIF reader always returns a rotation of 0. If a
rotation is specified to the writer, the ellipse is turned into a region, vectorized, and
rotated by the amount specified.
TIP: The primary ellipse axis is not necessarily the longest axis, but rather the one on the x axis.
In addition to the attributes below, ellipses also make use of the brush and pen
attributes as defined by mif_region.
19.4.8 Arc
mif_type: mif_arc
MIF arc features are linear features used to specify elliptical arcs. As such, the feature
definition for mif_arc is similar to the ellipse definition with two additional angles
to control the portion of the ellipse boundary drawn. MIF arcs currently do not
Attribute Name Contents
mif_primary_axis The length of the semi-major axis in ground units.
Range: Any real number > 0
Default: No default
mif_secondary_axis The length of the semi-minor axis in ground units.
Range: Any real number > 0
Default: No default
mif_rotation The rotation of the major axis. The rotation is measured in
degrees counter-clockwise up from horizontal.
Range: -360.0..360.0
Default: 0
Primary
Axis
Secondary
Axis
Rotation = 0
rotation
19-13 FME Reference Manual Version 2.0
Safe Software Inc. MAPINFO DATA INTERCHANGE FORMAT READER/WRITER
support rotation. For compatibility with other systems, the MIF reader always returns
a rotation of 0. In addition, if a rotation is specified to the writer, the arc is turned into
a polyline, vectorized, and rotated by the amount specified.
TIP: The function @Arc() can be used to convert an arc to a linestring. This is useful for storing Arcs in systems
not supporting them directly.
In addition to the attributes below, arcs also make use of the pen attributes as defined
on mif_polyline.
Attribute Name Contents
mif_primary_axis The length of the semi-major axis in ground
units.
Range: Any real number > 0
Default: No default
mif_secondary_axis The length of the semi-minor axis in ground
units.
Range: Any real number > 0
Default: No default
mif_start_angle The start angle defines the counterclockwise
distance from the primary axis to the starting
point of the arc. It is measured in degrees.
Range: 0.0..360.0
Default: 0
mif_sweep_angle The sweep angle defines the sweep of the arc
from the starting point along the ellipse
boundary in the counterclockwise direction. It
is measured in degrees.
Range: 0.0..360.0
Default: No default
mif_rotation The rotation of the major axis. The rotation is
measured in degrees counter clockwise up
from horizontal.
Range: -360.0..360.0
Default: 0
Secondary
Axis
Rotation = 90
Start
Angle
= 45
Sweep
Angle
= 135
Primary
Axis
rotation
MAPINFO DATA INTERCHANGE FORMAT READER/WRITER Safe Software Inc.
19-14 FME Reference Manual Version 2.0
19.4.9 Rectangle
mif_type: mif_rectangle
MIF rectangle objects are represented in the FME as closed polygons. When a MIF
rectangle is read, it is turned into a closed polygon feature. When a MIF rectangle is
written, the minimum bounding rectangle of the feature is taken and used as the four
corners of the rectangle. MIF rectangles take the same additional attributes as MIF
regions to specify their brush and pen.
19.4.10 Rounded Rectangle
mif_type: mif_rounded_rectangle
MIF rounded rectangle objects are represented in the FME as closed polygons. When
a MIF rounded rectangle is read, it is turned into a closed polygon feature and the
corners are vectorized to preserve the intended shape of the rectangle. The rounding
radius is also stored as an attribute. When a MIF rounded rectangle is written, the
minimum bounding rectangle of the feature is taken and used as the four corners of
the rectangle, and the rounding diameter is taken from an attribute of the feature. MIF
rounded rectangles take the same additional attributes as MIF regions to specify their
brush and pen.
19.5 Example of an SAIF to MIF Mapping File
The example below shows an FME mapping file used to translate some linear road
features from the SAIF format into MIF files. The mapping file defines the dataset
location and gives the MIF definitions for the file to be written. At runtime, the MIF
writer is given FME features with full attributes to output.
Attribute Name Contents
mif_rounding Contains the diameter in ground unit, of the
circle used to produce the rounded corners.
Range: Any real number > 0
Default: No default
Rounding
Diameter
19-15 FME Reference Manual Version 2.0
Safe Software Inc. MAPINFO DATA INTERCHANGE FORMAT READER/WRITER
# ----------------------------------------------------------
# Define the location of the output MIF files
MIF_DATASET /usr/data/mapinfo/92i080
# ----------------------------------------------------------
# Define the attributes and type of the MIF
# file to be created
MIF_DEF roads \
numberOfLanes smallint \
roadType char(5) \
underConstruction logical \
divided logical \
travelDirection char(6)
# ----------------------------------------------------------
# Now define the location of the SAIF file
# to be read
SAIF_DATASET /usr/data/saif/92i080.zip
# ----------------------------------------------------------
# Color macros -- nice names for the 24 bit integers
# which are 8 bits of RGB
MACRO red 16711680
MACRO yellow 16776960
MACRO green 65280
MACRO blue 255
MACRO black 0
MACRO magenta 16711935
MACRO cyan 65535
MACRO grey 12632256
MACRO purple 8388736
MACRO white 16777215
# ----------------------------------------------------------
# Pen pattern macros -- give names to some common line types
MACRO forwardArrow 59
MACRO railLine 69
MACRO thickRoad 74
MACRO thinRoad 77
MACRO solidPen 2
MACRO dotted 3
MACRO dashed 5
MACRO wideDashed 7
MACRO widestDashed 8
# ----------------------------------------------------------
# Pen thickness macros -- give names to some thicknesses
MACRO thick 1
MACRO thin 0
# ----------------------------------------------------------
# Symbol macros -- give names to some symbols
MACRO solidStar 35
MACRO solidCircle 34
MACRO solidSquare 32
MACRO solidDiamond 33
TIP:
Using macros for
the MIF colors,
symbols,
linestyles, and
fill patterns
makes mapping
file maintenance
and authoring
much simpler.
MAPINFO DATA INTERCHANGE FORMAT READER/WRITER Safe Software Inc.
19-16 FME Reference Manual Version 2.0
MACRO clearStar 41
MACRO clearCircle 40
MACRO clearSquare 38
MACRO clearDiamond 39
MACRO plus 49
MACRO asterisk 51
MACRO tower 63
MACRO building 60
MACRO plane 52
MACRO dock 58
MACRO monument 66
MACRO landmark 67
MACRO ex 50
# ----------------------------------------------------------
# Brush patterns
MACRO smallCheckers 47
MACRO bigGravel 48
MACRO speckles 49
MACRO rightDiag 32
MACRO leftDiag 37
MACRO solid 2
MACRO clear 1
MACRO darkMesh 45
MACRO heavy 15
MACRO horizontal 23
MACRO vertical 28
# ----------------------------------------------------------
# Now define transfer specifications
SAIF Road::TRIM position.geometry.Class Arc \
numberOfLanes %numberOfLanes:2 \
surfaceType %surfaceType:paved \
underConstruction %underConstruction:false \
divided %divided:false \
travelDirection %travelDirection:twoWay
MIF roads mif_type polyline \
mif_pen_width $(thick) \
mif_pen_pattern $(thickRoad) \
mif_pen_color $(red) \
numberOfLanes %numberOfLanes \
surfaceType %surfaceType \
underConstruction %underConstruction \
divided %divided \
travelDirection %travelDirection
TIP: Note how the SAIF portion of the transfer specification contains default values for the transfer variables.
This provides meaningful values for these fields when not stored in the SAIF dataset.
20-1 FME Reference Manual Version 2.0
20
20 MAPINFO NATIVE FORMAT
READER/WRITER
The MapInfo Native Format reader and writer modules provide the Feature
Manipulation Engine (FME) with the ability to read and write directly to
MapInfo files. The MapInfo Native Format is a proprietary format used by the
MapInfo Professional Desktop mapping product. MapInfo native format files
are often called tab files.
The MapInfo Native Format reader and writer are closely patterned after the
MapInfo MIF/MID reader and writer. This commonality makes it easy to
support both MIF and MapInfo native formats in the same mapping file.
20.1 Overview
MapInfo is a two-dimensional system with no provision for transferring
elevation data for each vertex in a MapInfo feature. However, point features
can define an elevation attribute to store their elevation.
MapInfo files store both feature geometry and attributes. A logical MapInfo
file consists of several physical files, having the following filename
extensions:
Filename
Extension
Contents
.tab The main file for a Mapinfo table, it is associated with the
appropriate DAT, MAP, ID, and IND files.
MAPINFO NATIVE FORMAT READER/WRITER Safe Software Inc.
20-2 FME Reference Manual Version 2.0
These extensions are added to the basename of the specified Mapinfo file.
Throughout the remainder of this section, references to file are references to the
logical MapInfo file, not the multiple physical files that make it up.
The MapInfo reader and writer support the storage of point, line, polyline, arc, ellipse,
rectangle, rounded rectangle, region (polygon), and text geometric data. The MapInfo
format also stores features with no geometry. Features having no geometry are
referred to as having a geometry of none.
Each geometric entity present in MapInfo has display properties, such as pen and
brush width, pattern, and color. In addition, each entity has a row of attributes
associated with it. A single MapInfo map file can contain many different types of
geometry however, the associated attributes must have the same number and type of
fields for each entity in the file.
The number and type of attributes associated with each entity is specified by the user.
There must be at least one attribute field defined before a MapInfo file can be created.
The following illustration shows a MapInfo file containing three region entities. Note
that the second polygon contains a hole while the third polygon is an aggregate of two
disjoint polygons, one of which contains a hole. Each geometric entity in turn
corresponds with one record in the attribute table.
The FME considers a MapInfo dataset to be a collection of tab files and related files
in a single directory. The attribute definitions for each MapInfo file set must be
defined in the mapping file before it can be read or written.
.dat Tabular data for a table in MapInfos native format.
.id An index to a MapInfo graphical objects (MAP) file.
.map Contains geographic information describing map objects.
.ind An index to a MapInfo tabular (DAT) file.
Filename
Extension
Contents
20-3 FME Reference Manual Version 2.0
Safe Software Inc. MAPINFO NATIVE FORMAT READER/WRITER
20.2 Reader Overview
The Mapinfo reader first scans the directory it is given for the MapInfo files which
have been defined in the mapping file. For each logical MapInfo file that it finds, it
checks to see if it that file is requested by looking at the list of IDs specified in the
mapping file. If a match is made (or no IDs were specified in the mapping file), the
MapInfo file is opened. The MapInfo reader then extracts features from the file one
at a time, and passes them on to the rest of the FME for further processing. When the
file is exhausted, the MapInfo reader starts on the next file in the directory.
20.2.1 Reader Keywords
The following table lists the keywords processed by the MapInfo reader. The
keywords shown will be prefixed by the current <ReaderKeyword>_ in a
mapping file. By default, the <ReaderKeyword> for the MapInfo reader is
MAPINFO.
Keyword Suffix Value Required/
Optional
DATASET Contains the directory name of the input MapInfo files. Required
Geometry Info Associated Attributes
Pen 1,1,12
Brush 3,2,10
Pen 1,1,12
Brush 4,3,9
Pen 2,1,13
Brush 3,2,10
DEPTH LAKE_NAME
10
15
25
Smokey Lake
Beaver Hill Lake
Swan Lake
MAPINFO NATIVE FORMAT READER/WRITER Safe Software Inc.
20-4 FME Reference Manual Version 2.0
20.2.2 DATASET
The value for this keyword is the directory containing the MapInfo files to be read. A
typical mapping file fragment specifying an input MapInfo dataset looks like:
MAPFINFO_DATASET /usr/data/mapinfo/92i080
20.2.3 DEF
Each MapInfo file must be defined before it can be read. The definition specifies the
base name of the file, and the names and types of all attributes. The syntax of a
MapInfo DEF line is:
<ReaderKeyword>_DEF <baseName> [<attrName> <attrType>]+
The filenames of the physical MapInfo files are constructed by using the directory
specified by the DATASET keyword, the basename specified on the MapInfo DEF
lines, and the file extensions.
MapInfo requires that at least one attribute be defined. The attribute definition given
must match the definition of the file being read. If it does not, translation is halted and
the true definition of the MapInfo file attributes are logged to the log file. There are
no restrictions on the field names of MapInfo attributes. The following table shows
the attribute types which are supported.
DEF Defines a MapInfo file. Each MapInfo file must be
defined before it can be read. The definition contains the
files base name (without any of the extensions), and the
definitions of the attributes. There may be many DEF
lines, one for each file to be read.
Required
IDs Contains a list of MapInfo files to process. If this is not
specified, then all defined MapInfo files in the directory
will be read.
Optional
Field Type Description
char(<width>) Character fields store fixed length strings. The width
parameter controls the maximum of characters stored by
the field. No padding is required for strings shorter than
this width.
date Date fields store dates as character strings with the format
dependent on your location.
Keyword Suffix Value Required/
Optional
20-5 FME Reference Manual Version 2.0
Safe Software Inc. MAPINFO NATIVE FORMAT READER/WRITER
The following mapping file fragment defines two MapInfo files. Notice that neither
definition specifies the geometric type of the entities it will contain because MapInfo
files may contain any of the valid geometry types.
MAPINFO_DEF landcover \
area decimal(12,3) \
landcoverType char(11) \
perimeter float
MAPINFO_DEF roads \
numberOfLanes smallint \
roadType char(5) \
underConstruction logical \
divided logical \
travelDirection char(6)
20.2.4 IDs
This optional specification is used to limit the MapInfo files that are read. If no IDs
are specified, then all defined and available MapInfo files are read. The syntax of the
IDs keyword is:
<ReaderKeyword>_IDs <baseName1> \
<baseName1> \
<baseNameN>
The basenames must match those used in DEF lines.
The example below selects only the roads MAPINFO file for input during a
translation:
MAPINFO_IDs roads
decimal(<width>,
<decimals>)
Decimal fields store single and double precision floating
point values. The width parameter is the total number of
characters allocated to the field, including the decimal
point. The decimals parameter controls the precision of
the data and is the number of digits to the right of the
decimal.
float Float fields store floating point values. There is no ability
to specify the precision and width of the field.
integer Integer fields store 32 bit signed integers.
logical Logical fields store boolean data. Data read or written
from/to such fields must always have a value of either
true or false.
smallint Small integer fields store 16 bit signed integers, and
therefore have a range of -32767 to +32767.
Field Type Description
MAPINFO NATIVE FORMAT READER/WRITER Safe Software Inc.
20-6 FME Reference Manual Version 2.0
20.3 Writer Overview
The MapInfo writer creates and writes feature data to MapInfo files in the directory
specified by the DATASET keyword. If the directory does not exist, the writer has to
create it. Any old MapInfo files in the directory are overwritten with the new feature
data. As features are routed to the MapInfo writer, the MapInfo writer determines the
file into which the features are to be written and outputs them accordingly. Many
MapInfo files can be written during a single FME session.
20.3.1 Writer Keywords
The MapInfo writer processes the DATASET and DEF keywords as described in the
Reader Keywords section. It does not make use of the IDs keyword.
20.4 Feature Representation
MapInfo features consist of geometry and attributes. The attribute names are defined
in the DEF line and there is a value for each attribute in each FME MapInfo feature.
In addition, each MapInfo FME feature contains several special attributes to hold the
type of the geometric entity and its display parameters. All MapInfo FME features
contain the mapinfo_type attribute, which identifies the geometric type.
Depending on the geometric type, the feature contains additional attributes specific
to the geometric type. These are described in subsequent sections.
20.4.1 Points
mapinfo_type: mapinfo_point
MapInfo point features specify a single x and y coordinate in addition to any
associated user-defined attributes.
Attribute Name Contents
mapinfo_type The MapInfo geometric type of this entity.
Range: mapinfo_point|
mapinfo_polyline|
mapinfo_region|
mapinfo_text|
mapinfo_ellipse|
mapinfo_arc|
mapinfo_rectangle|
mapinfo_rounded_rectangle|
mapinfo_none
Default: No default
20-7 FME Reference Manual Version 2.0
Safe Software Inc. MAPINFO NATIVE FORMAT READER/WRITER
A MapInfo point also specifies a symbol. The symbol is defined by a symbol number,
a color, and a size.
1
If no symbol is defined for a point entity, the previous symbol is
used. The table below lists the special FME attribute names used to control the
MapInfo symbol settings.
20.4.2 Font Points
mapinfo_type: mapinfo_font_point
MIF font points are very similar to MIF points, but allow a symbol based on a
TrueType font to be specified. In addition to the font, a rotation, color, shape number,
size, and style may be specified.
The table below lists the special FME attribute names used to control the MIF font
point settings:
1. MapInfo symbols cannot be rotated. However, some 3
rd
party add-ons to MapInfo will rotate symbols
based on a user-defined rotation attribute.
Attribute Name Contents
mapinfo_symbol_color The color of the symbol. MapInfo colors are
defined in relative concentrations of red,
green, and blue. Each color ranges from 0 to
255, and the color value is calculated
according to the formula:
(red*65536) + (green*256) + blue
Range: 02^24 - 1
Default: 0 (black)
mapinfo_symbol_shape The number of the symbol. See the MapInfo
Reference Manual for a list of the available
symbols.
Range: 31...67
Default: 41 (a star)
mapinfo_symbol_size The point size of the symbol. Note that this
size is not scaled depending on the zoom level.
Range: Any integer number > 0
Default: 10
Attribute Name Contents
mapinfo_symbol_color The color of the symbol calculated according to the
formula:
(red*65536) + (green*256) + blue
Range: 02^24 - 1
Default: 0 (black)
MAPINFO NATIVE FORMAT READER/WRITER Safe Software Inc.
20-8 FME Reference Manual Version 2.0
20.4.3 Custom Points
mapinfo_type: mapinfo_custom_point
MIF custom points are very similar to MIF points, but allow a bitmap image to be
specified as the symbol to be drawn. In addition to the image color, size, and style
may be specified.
The table below lists the special FME attribute names used to control the MapInfo
custom point settings:
mapinfo_symbol_shape The number of the shape within the TrueType font to
us as the symbol.
Range: Integer
Default: No default
mapinfo_symbol_size The point size of the symbol.
Range: Integer
Default: 12
mapinfo_symbol_font The name of the TrueType font to be used for the
symbol.
Range: String
Default: No default
mapinfo_symbol_angle The rotation angle for the symbol, measured in
degrees counterclockwise from horizontal.
Range: -360.0..360.0
Default: 0
mapinfo_symbol_style The display style for the symbol.
Range: 0 (Plain text)
1 (Bold text)
16 (Black border around symbol)
32 (Drop Shadow)
256 (White border around symbol)
Default: 0
Attribute Name Contents
mapinfo_symbol_color The color of the symbol calculated according to the
formula:
(red*65536) + (green*256) + blue
Whether or not the color is used, depends on the
setting of the style attribute.
Range: 02^24 - 1
Default: 0 (black)
mapinfo_symbol_file_name The name of the bitmap file found in the MapInfo
CustSymb directory.
Range: String
Default: No default
Attribute Name Contents
20-9 FME Reference Manual Version 2.0
Safe Software Inc. MAPINFO NATIVE FORMAT READER/WRITER
20.4.4 Polylines
mapinfo_type: mapinfo_polyline
MapInfo polyline features specify linear features defined by a sequence of x and y
coordinates. Each polyline has a pen style associated with it that specifies the color,
width, and pen pattern of the line. A polyline may also specify that it is a smoothed
line
2
, in which case MapInfo uses a curve fitting algorithm when rendering the line.
If no pen style is defined, the previous style is used.
TIP: MapInfo supports a special type for two point lines. The FME transparently converts such lines into
polylines, both as it reads and as it writes them.
The table below lists the special FME attribute names used to control the MapInfo
polyline settings.
2. MapInfo renders smoothed polylines substantially slower than unsmoothed polylines.
mapinfo_symbol_size The point size of the symbol.
Range: Integer
Default: 12
mapinfo_symbol_style The display style for the symbol.
Range: 0 (White pixels in the image are
transparent, allowing whatever is
beneath to show through. Non-white
pixels are drawn in the same color as
they are in the bitmap.)
1 (White pixels in the image are drawn as
white. Non-white pixels are drawn in
the same color as they are in the
bitmap.)
2 (White pixels in the image are
transparent. Non-white pixels are
drawn in the color specified by
mif_symbol_color.)
3 (White pixels in the image are drawn in
white. Non-white pixels are drawn in
the color specified by
mif_symbol_color)
Default: 0
Attribute Name Contents
MAPINFO NATIVE FORMAT READER/WRITER Safe Software Inc.
20-10 FME Reference Manual Version 2.0
20.4.5 Regions
mapinfo_type: mapinfo_region
MapInfo region features specify area (polygonal) features. The areas that make up a
single feature may or may not be disjoint, and may contain polygons which have
holes. Each region has a pen style associated with it to control the color, width, and
pen pattern used when its boundary is drawn. In addition, a region may set its brush
pattern, foreground, and background color to control how the area it encloses will be
filled. If no pen or brush style is defined for a region entity, the previous style is used.
The following table lists the special FME attribute names used to control the MapInfo
region settings.
Attribute Name Contents
mapinfo_pen_color The color of the polyline. MapInfo colors are
defined in relative concentrations of red,
green, and blue. Each color ranges from 0 to
255, and the color value is calculated
according to the formula:
(red*65536) + (green*256) + blue
Range: 02^24 - 1
Default: 0 (black)
mapinfo_pen_pattern The pattern used to draw the line. See the
MapInfo Reference Manual for a list of the
available patterns.
Range: 177
Default: 2
mapinfo_pen_width The width of the line rendered for the polyline
feature. This is measured as a thickness in
pixels. 0 defines the thinnest line possible.
Range: 0..7
Default: 0
mapinfo_smooth Controls whether or not the polyline will be
smoothed when rendered.
Range: true|false
Default: false
Attribute Name Contents
mapinfo_brush_pattern The pattern used to fill the area the region
contains. See the MapInfo Reference Manual
for a list of the available brush patterns.
Range: 171
Default: 2 (solid)
20-11 FME Reference Manual Version 2.0
Safe Software Inc. MAPINFO NATIVE FORMAT READER/WRITER
20.4.6 Text
mapinfo_type: mapinfo_text
MapInfo text features are used to specify annotation information. Each text feature
can have its font, color, spacing, justification, and rotation angle set independently.
The following table lists the special FME attribute names used to control the MapInfo
text settings.
mapinfo_brush_
foreground
The foreground color used when the region is
filled. MapInfo colors are defined in relative
concentrations of red, green, and blue. Each
color ranges from 0 to 255, and the color value
is calculated according to the formula:
(red*65536) + (green*256) + blue
Range: 02^24 - 1
Default: 0 (black)
mapinfo_brush_
background
The background color used when the region is
filled.
Range: 02^24 - 1
Default: 0 (black)
mapinfo_pen_color The color of the boundary of the region.
Range: 02^24 - 1
Default: 0 (black)
mapinfo_pen_pattern The pattern used to draw the regions
boundary. See the MapInfo Reference Manual
for a list of the available patterns.
Range: 177
Default: 2
mapinfo_pen_width The width of the line rendered for the regions
boundary. This is measured as a thickness in
pixels. 0 defines the thinnest line possible.
Range: 0..7
Default: 0
Attribute Name Contents
mapinfo_rotation The rotation of the text, as measured in
degrees counter-clockwise from horizontal.
Range: -360.0..360.0
Default: 0
mapinfo_text_fontbgcolor The background color used when the text is
drawn.
Range: 02^24 - 1
Default: 255 (blue)
Attribute Name Contents
MAPINFO NATIVE FORMAT READER/WRITER Safe Software Inc.
20-12 FME Reference Manual Version 2.0
mapinfo_text_fontfgcolor The foreground color used when the text is
drawn. MapInfo colors are defined in relative
concentrations of red, green, and blue. Each
color ranges from 0 to 255, and the color value
is calculated according to the formula:
(red*65536) + (green*256) + blue
Range: 02^24 - 1
Default: 0 (black)
mapinfo_text_fontname The name of the font used to draw the text. The
font named must be available on the
destination computer system.
Range: Any valid system font
Default: Helve
mapinfo_text_height The height of the text in ground units.
Range: Any real number >= 0
Default: 10
mapinfo_text_justification The justification of the text.
Range: left|center|right
Default: left
mapinfo_text_spacing The spacing between lines of multiline text.
The measure is expressed as a multiple of the
text height.
Range: 1.0|1.5|2.0
Default: 1.0
mapinfo_text_linetype The spacing between lines of multiline text.
The measure is expressed as a multiple of the
text height.
Range: 1.0|1.5|2.0
Default: 1.0
mapinfo_text_fontstyle_bold Indicates if the text is bold or not.
Range: true | false
Default: false
mapinfo_text_fontstyle_italic Indicates if the text is in italics
Range: true | false
Default: false
mapinfo_text_fontstyle_underline Indicates if the text is underlined.
Range: true | false
Default: false
mapinfo_text_fontstyle_strikeout Indicates if the text has a line through the
middle of it.
Range: true | false
Default: false
mapinfo_text_fontstyle_outline Indicates if the text is outlined
Range: true | false
Default: false
Attribute Name Contents
20-13 FME Reference Manual Version 2.0
Safe Software Inc. MAPINFO NATIVE FORMAT READER/WRITER
20.4.7 Ellipse
mapinfo_type: mapinfo_ellipse
MapInfo ellipse features are point features, and only have a single coordinate. This
point serves as the center of the ellipse. Additional attributes specify the primary axis
and the secondary axis of the ellipse. MapInfo ellipses currently do not support
rotation. For compatibility with other systems, the MapInfo reader always returns a
rotation of 0. If a rotation is specified to the writer, the ellipse is turned into a region,
vectorized, and rotated by the amount specified.
mapinfo_text_fontstyle_shadow Indicates if the text has a shadow.
Range: true | false
Default: false
mapinfo_text_fontstyle_inverse Indicates if the text is shown in inverse.
Range: true | false
Default: false
mapinfo_text_fontstyle_blink Indicates if the text is blinking.
Range: true | false
Default: false
mapinfo_text_fontstyle_opaque Indicates if the text is opaque.
Range: true | false
Default: false
mapinfo_text_string The text to be displayed.
Range: Any character string
Default: No default
mapinfo_text_width The width of each text character in ground
units.
Range: Any real number >= 0
Default: 10
Attribute Name Contents
rotation
Primary
Axis
Secondary
Axis
Rotation = 0
MAPINFO NATIVE FORMAT READER/WRITER Safe Software Inc.
20-14 FME Reference Manual Version 2.0
TIP: The primary ellipse axis is not necessarily the longest axis, but rather the one on the x axis.
In addition to the attributes below, ellipses also make use of the brush and pen
attributes as defined by mapinfo_region.
20.4.8 Arc
mapinfo_type: mapinfo_arc
MapInfo arc features are linear features used to specify elliptical arcs. As such, the
feature definition for mapinfo_arc is similar to the ellipse definition with two
additional angles to control the portion of the ellipse boundary drawn. MapInfo arcs
currently do not support rotation. For compatibility with other systems, the MapInfo
reader always returns a rotation of 0. In addition, if a rotation is specified to the writer,
the arc is turned into a polyline, vectorized, and rotated by the amount specified.
TIP: The function @Arc() can be used to convert an arc to a linestring. This is useful for storing Arcs in systems
that do not support them directly.
Attribute Name Contents
mapinfo_primary_axis The length of the semi-major axis in ground units.
Range: Any real number > 0
Default: No default
mapinfo_secondary_axis The length of the semi-minor axis in ground units.
Range: Any real number > 0
Default: No default
mapinfo_rotation The rotation of the major axis. The rotation is measured
in degrees counter-clockwise up from horizontal.
Range: -360.0..360.0
Default: 0
Secondary
Axis
Rotation = 90
Start
Angle
= 45
Sweep
Angle
= 135
Primary
Axis
rotation
20-15 FME Reference Manual Version 2.0
Safe Software Inc. MAPINFO NATIVE FORMAT READER/WRITER
In addition the attributes below, arcs also make use of the pen attributes as defined on
mapinfo_polyline.
20.4.9 Rectangle
mapinfo_type: mapinfo_rectangle
MapInfo rectangle objects are represented in the FME as closed polygons. When a
MapInfo rectangle is read, it is turned into a closed polygon feature. When a MapInfo
rectangle is written, the minimum bounding rectangle of the feature is taken and used
as the four corners of the rectangle. MapInfo rectangles take the same additional
attributes as MapInfo regions to specify their brush and pen.
20.4.10 Rounded Rectangle
mapinfo_type: mapinfo_rounded_rectangle
MapInfo rounded rectangle objects are represented in the FME as closed polygons.
When a MapInfo rounded rectangle is read, it is turned into a closed polygon feature
and the corners are vectorized to preserve the intended shape of the rectangle. The
Attribute Name Contents
mapinfo_primary_axis The length of the semi-major axis in ground
units.
Range: Any real number > 0
Default: No default
mapinfo_secondary_axis The length of the semi-minor axis in ground
units.
Range: Any real number > 0
Default: No default
mapinfo_start_angle The start angle defines the counterclockwise
distance from the primary axis to the starting
point of the arc. It is measured in degrees.
Range: 0.0..360.0
Default: 0
mapinfo_sweep_angle The sweep angle defines the sweep of the arc
from the starting point along the ellipse
boundary in the counterclockwise direction.
It is measured in degrees.
Range: 0.0..360.0
Default: No default
mapinfo_rotation The rotation of the major axis. The rotation is
measured in degrees counter clockwise up
from horizontal.
Range: -360.0..360.0
Default: 0
MAPINFO NATIVE FORMAT READER/WRITER Safe Software Inc.
20-16 FME Reference Manual Version 2.0
rounding radius is also stored as an attribute. When a MapInfo rounded rectangle is
written, the minimum bounding rectangle of the feature is taken and used as the four
corners of the rectangle, and the rounding diameter is taken from an attribute of the
feature. MapInfo rounded rectangles take the same additional attributes as MapInfo
regions to specify their brush and pen.
20.5 Example of an SAIF to MAPINFO Mapping File
The example below shows an FME mapping file used to translate some linear road
features from the SAIF format into MapInfo files. The mapping file defines the
dataset location and gives the MapInfo definitions for the file to be written. At run
time, the MapInfo writer is given FME features with full attribution to output.
# ----------------------------------------------------------
# Define the location of the output MAPINFO files
# MAPINFO_DATASET /usr/data/mapinfo/92i080
# ----------------------------------------------------------
# Define the attributes and type of the MAPINFO
# file to be created
MAPINFO_DEF roads \
numberOfLanes smallint \
roadType char(5) \
underConstruction logical \
divided logical \
travelDirection char(6)
# ----------------------------------------------------------
# Now define the location of the SAIF file
# to be read
SAIF_DATASET /usr/data/saif/92i080.zip
Attribute Name Contents
mapinfo_rounding_width Contains the width, in ground units, of the ellipse used to
produce the rounded corners.
Range: Any real number > 0
Default: No default
mapinfo_rounding_height Contains the height, in ground units, of the ellipse used to
produce the rounded corners.
Range: Any real number > 0
Default: value of mapinfo_rounding_width
Rounding
Rounding
Height
Width
20-17 FME Reference Manual Version 2.0
Safe Software Inc. MAPINFO NATIVE FORMAT READER/WRITER
# ----------------------------------------------------------
# Color macros -- nice names for the 24 bit integers
# which are 8 bits of RGB
MACRO red 16711680
MACRO yellow 16776960
MACRO green 65280
MACRO blue 255
MACRO black 0
MACRO magenta 16711935
MACRO cyan 65535
MACRO grey 12632256
MACRO purple 8388736
MACRO white 16777215
# ----------------------------------------------------------
# Pen pattern macros -- give names to some common line types
MACRO forwardArrow 59
MACRO railLine 69
MACRO thickRoad 74
MACRO thinRoad 77
MACRO solidPen 2
MACRO dotted 3
MACRO dashed 5
MACRO wideDashed 7
MACRO widestDashed 8
# ----------------------------------------------------------
# Pen thickness macros -- give names to some thicknesses
MACRO thick 1
MACRO thin 0
# ----------------------------------------------------------
# Symbol macros -- give names to some symbols
MACRO solidStar 35
MACRO solidCircle 34
MACRO solidSquare 32
MACRO solidDiamond 33
MACRO clearStar 41
MACRO clearCircle 40
MACRO clearSquare 38
MACRO clearDiamond 39
MACRO plus 49
MACRO asterisk 51
MACRO tower 63
MACRO building 60
MACRO plane 52
MACRO dock 58
MACRO monument 66
MACRO landmark 67
MACRO ex 50
# ----------------------------------------------------------
NOTE:
Using macros for
the MAPINFO
colors, symbols,
linestyles, and fill
patterns makes
mapping file
maintenance and
authoring much
simpler.
MAPINFO NATIVE FORMAT READER/WRITER Safe Software Inc.
20-18 FME Reference Manual Version 2.0
# Brush patterns
MACRO smallCheckers 47
MACRO bigGravel 48
MACRO speckles 49
MACRO rightDiag 32
MACRO leftDiag 37
MACRO solid 2
MACRO clear 1
MACRO darkMesh 45
MACRO heavy 15
MACRO horizontal 23
MACRO vertical 28
# ----------------------------------------------------------
# Now define transfer specifications
SAIF Road::TRIM position.geometry.Class Arc \
numberOfLanes %numberOfLanes:2 \
surfaceType %surfaceType:paved \
underConstruction %underConstruction:false \
divided %divided:false \
travelDirection %travelDirection:twoWay
MAPINFO roads mapinfo_type polyline \
mapinfo_pen_width $(thick) \
mapinfo_pen_pattern $(thickRoad) \
mapinfo_pen_color $(red) \
numberOfLanes %numberOfLanes \
surfaceType %surfaceType \
underConstruction %underConstruction \
divided %divided \
travelDirection %travelDirection
TIP: Notice how the SAIF portion of the transfer specification contains default values for the transfer variables.
This provides meaningful values for these fields when they were not stored in the SAIF dataset.
21-1 FME Reference Manual Version 2.0
21
21 MULTI-READER
The Multi-Reader gives the Feature Manipulation Engine (FME) the ability
to combine several different datasets, possibly of different types, into one
logical input dataset. Though this capability is most often used to merge data
from adjacent mapsheet datasets into a single dataset, it is also used to
integrate data from several different sources. For example, linework from an
Interactive Graphics Design System (IGDS) design file could be formed into
polygons using the PolygonFactory, merged with point data and attributes
from a Shape file using the DonutFactory, and output to ESRIs Spatial
Database Engine (SDE).
21.1 Overview
The Multi-Reader is completely configured in the mapping file. Each reader
it uses is identified and configured. At run time, the Multi-Reader cycles
through each reader it is given, and sends features on to the rest of the FME.
When the first reader reaches the end of its data, the second reader is
activated. This continues until the Multi-Reader runs out of readers. Figure
21-1 illustrates this concept.
MULTI-READER Safe Software Inc.
21-2 FME Reference Manual Version 2.0
Figure 21-1 Multi-Reader Process
21.2 Keywords
The Multi-Reader processes several keywords in the mapping file, as shown here.
21.3 Feature Representation
The Multi-Reader adds a single attribute to each feature it receives from its reader.
Other than the addition of this attribute, the features pass through untouched, and
maintain the attributes and geometry they were assigned by their original reader.
Keyword Value
MULTI_READER_TYPE{#} Contains the name of the #
th
reader to use. # starts at
zero and increases for each different reader that will be
used.
MULTI_READER_KEYWORD{#} Contains the keyword the #
th
reader looks for when it
scans the mapping file for its own settings.
Attribute Name Contents
multi_reader_id This attribute holds the number of the reader which produced
the feature. This corresponds to the # enclosed in {} in the
MULTI_READER_TYPE{#} keyword.
Range: Integer >= 0
Reader1
Reader 2
Reader N
.
.
.
Multi-
reader
FME
output
dataset
input
dataset
1
input
dataset
2
input
dataset
N
21-3 FME Reference Manual Version 2.0
Safe Software Inc. MULTI-READER
21.4 Example
The following mapping file example shows how the Multi-Reader is used to combine
roads from two SAIF datasets into a single Shape file.
# Declare the reader as being a Multi-Reader. In the
# transfer specifications, the SOURCE type will appear
# to be MULTI-READER, even though the data will be coming
# from several SAIF datasets.
READER_TYPE MULTI_READER
# Set up the first reader used by the Multi-Reader.
# This reader is a SAIF reader.
MULTI_READER_TYPE{0} SAIF
# Indicate the keyword that the first SAIF reader should
# use when it looks for its parameters in the mapping file:
MULTI_READER_KEYWORD{0} SAIF{0}
# Now configure the first SAIF reader. Note that the
# SAIF readers keywords are prefixed by the first
# Multi-Reader keyword defined above (SAIF{0}).
SAIF{0}_DATASET c:\saifdata\92i080.zip
# And extract only the roads from this dataset
SAIF{0}_IDs Roads
# Now do the same thing for the second SAIF dataset
# to be read.
MULTI_READER_TYPE{1} SAIF
MULTI_READER_KEYWORD{1} SAIF{1}
SAIF{1}_DATASET c:\saifdata\92c090.zip
SAIF{1}_IDs Roads
# -----------------------------------------------
# Now define the writer
WRITER_TYPE SHAPE
# Set the destination directory for the Shape file
SHAPE_DATASET roadset
# And set up the definition of the output Shape file
SHAPE_DEF roads SHAPE_GEOMETRY shape_arc \
NUMLANES number(2,0) \
TYPE char(5) \
UNDERCNST logical \
DIVIDED logical \
TRVLDIR char(6)
# -----------------------------------------------
# Now the transfer specification. Note that the
# source for the data is the MULTI_READER
NOTE:
The choice of
SAIF{0} and
SAIF{1} as the
reader keywords
is arbitrary. They
just as easily have
been called
FIRST_FILE
and SECOND_
FILE.
MULTI-READER Safe Software Inc.
21-4 FME Reference Manual Version 2.0
MULTI_READER Road::TRIM position.geometry.Class Arc \
numberOfLanes %numberOfLanes:2 \
surfaceType %surfaceType:paved \
underConstruction %underConstruction:false \
divided %divided:false \
travelDirection %travelDirection:twoWay
SHAPE roads NUMLANES %numberOfLanes \
TYPE %surfaceType \
UNDERCNST %underConstruction \
DIVIDED %divided \
TRVLDIR %travelDirection
22-1 FME Reference Manual Version 2.0
22 PHOCUS PHODAT READER
The PHOCUS PHODAT (PHOCUS) reader provides the FME with the
ability to import PHOCUS data and export it to any of the FME output
formats. PHOCUS PHODAT is a published ASCII format output by the
Karl-Zeiss PHOCUS system.
22.1 Overview
The PHODAT files may contain both two-dimensional (2D) and three-
dimensional (3D) features. The PHODAT files do not explicitly store
attribute values but rather use a feature coding approach whereby unique
feature codes are assigned to different types of features stored within the
dataset. The FME looks for an extension of .pdt for the input PHODAT
files, but will accept any PHODAT file as input regardless of the filename or
extension.
The PHOCUS reader currently supports the reading of point, line, area, and
text geometric data in PHOCUS files.
Each geometric entity present in a PHOCUS file is assigned an object code
and an item code. Together these codes define the type of feature being read.
The FME considers a PHOCUS dataset to be a single PHOCUS PHODAT file.
PHOCUS PHODAT READER Safe Software Inc.
22-2 FME Reference Manual Version 2.0
22.2 Reader Overview
The PHOCUS reader simply opens the input file and immediately starts reading
features, returning them to the rest of the FME for processing. The reader doesnt have
any requirement for definition statements as there are no user-defined attributes.
Each feature returned has its feature type set to the value of the features object code
as defined by PHOCUS.
22.2.1 Reader Keywords
The following table lists the keywords processed by the PHOCUS reader. The
suffixes shown are prefixed by the current <ReaderKeyword> in a mapping file.
By default, the <ReaderKeyword> for the PHOCUS reader is PHOCUS.
22.2.2 DATASET
The value for this keyword is the file containing the PHOCUS dataset to be read. A
typical mapping file fragment specifying an input PHOCUS dataset looks like:
PHOCUS_DATASET /usr/data/phocus/db84.pdt
22.3 Feature Representation
PHOCUS features consist of geometry and feature code information. All PHOCUS
FME features contain the phocus_type attribute that identifies the geometric type.
Depending on the geometric type, the feature contains additional feature coding
attributes specific to the geometric type. These are described in subsequent
subsections.
Keyword Suffix Value Required/
Optional
DATASET Contains the file name of the input PHOCUS
dataset.
Required
SPLIT_INVISIBLE_LINES Indicates if lines that have visible and invisible
components are to be split apart and returned as
visible and invisible lines. If not specified or if the
value is NO, then lines with visible and invisible
components are not split up.
Optional
22-3 FME Reference Manual Version 2.0
Safe Software Inc. PHOCUS PHODAT READER
22.4 PHOCUS Attributes
The following table lists all of the different PHOCUS attributes returned by the FME
reader.
Attribute Name Contents
phocus_type The PHOCUS geometric type of this entity.
Range: phocus_point|
phocus_line|
phocus_area|
phocus_text
Default: No default
phocus_visibility This attribute is specified only when the
PHOCUS reader is run with the directive
SPLIT_INVISIBLE_LINES set to Yes.
The attribute indicates if the line is either
visible or invisible.
Field Name Description
phocus_object_state The state of the object. Valid values are:
0 = non-existent
1 = deleted before timemark
2 = deleted after timemark
3 = new before timemark
4 = new after timemark
5 = edited before timemark
6 = edited after timemark
phocus_object_number Unique number in the database.
Range: 1 - 2^31 - 1
phocus_object_class Number which indicates object class.
Range: 1 - 255
phocus_object_code Number which indicates object code.
Range: 1 - 32000
phocus_object_origin Number which indicates object origin.
Range: -32768 - 32767
phocus_object_status Number which indicates object status.
Range: - 128 - 127
phocus_object_name Object name. Maximum size is 66 characters.
PHOCUS PHODAT READER Safe Software Inc.
22-4 FME Reference Manual Version 2.0
22.4.1 Points
phocus_type: phocus_point
PHOCUS point features specify a single x and y coordinate. If the feature is 3D, a z
coordinate is specified as well.
phocus_object_item_type The type of the object item which is encountered. Values are:
2 = point
3 = line
4 = area
5 = slope (not currently supported by FME)
6 = text
phocus_object_item_num Unique number of item in the database.
Range: 1 - 2^31 - 1
phocus_object_item_class Number which indicates object item class.
Range: 1 - 32000
phocus_object_item_origin Number which indicates the origin of the object item.
Range: -32768 - 32767
phocus_object_item_stat Number which indicates the status of the object item.
Range: -128 - 128
phocus_rotation Rotation of the object item measured in degrees. The angle is
measured in a counter-clockwise direction from the x axis.
phocus_object_item_name The name of the object item in a maximum size of 66
characters.
phocus_subitem_state The state of the subitem. Valid values are:
0 = non-existent
1 = deleted before timemark
2 = deleted after timemark
3 = new before timemark
4 = new after timemark
5 = edited before timemark
6 = edited after timemark
phocus_subitem_type The subitem type. Valid values are:
1 = area
2 = cut-out
3 = upper edge
4 = lower edge
5 = text
phocus_subitem_number Unique number which identifies the subitem.
Field Name Description
22-5 FME Reference Manual Version 2.0
Safe Software Inc. PHOCUS PHODAT READER
There are no attributes specific to point features.
22.4.2 Lines
phocus_type: phocus_line
PHOCUS line features represent linear features and may be either 2D or 3D.
There are no attributes specific to point features.
22.4.3 Areas
phocus_type: phocus_area
PHOCUS area features represent polygonal features and may be either 2D or 3D.
There are no attributes specific to point features.
22.4.4 Text
phocus_type: phocus_text
PHOCUS text features are represented by these features and may be either 2D or 3D.
Text features have the following attributes.
Attribute Name Contents
phocus_justification The justification code for the text.
Range: 0..23
0 is Left Margin/Very Top
1 is Left Margin/Top
2 is Left Margin/Cap
3 is Left Margin/Center
4 is Left Margin/Base
5 is Left Margin/Bottom
6 is Left/Very Top
7 is Left/Top
8 is Left/Cap
9 is Left/Center
10 is Left/Base
11 is Left/Bottom
PHOCUS PHODAT READER Safe Software Inc.
22-6 FME Reference Manual Version 2.0
22.5 Example
The following example shows an FME mapping file used to translate some features
from the PHOCUS format into a GIF image. The mapping file defines the dataset
location and gives the correlation lines between PHOCUS features and GIF.
# ================================================================
READER_TYPE PHOCUS
WRITER_TYPE GIF
# ================================================================
# The following GUI line prompts for a file to be used as the
# source of the Phocus translation.
# The user input is stored in a MACRO, which is then used to define
# the dataset to be read.
GUI FILENAME SourceDataset
PHOCUS_FILES(*.pdt)|*.pdt|All_files(*.*)|*.* Original PHOCUS File:
# ================================================================
# Now define the factory which changes the feature type to be based
# on lines so that we dont get so many output files.
FACTORY_DEF PHOCUS SamplingFactory \
INPUT FEATURE_TYPE * @FeatureType(&phocus_type) \
SAMPLE_RATE 1
PHOCUS_DATASET $(SourceDataset)
# ================================================================
# The following GUI line prompts for a file to be used as the
# the destination for the output GIF file.
# The user input is stored in a macro, which is then used to define
# the dataset to be written.
phocus_justification
(continued)
12 is Center/Very Top
13 is Center/Top
14 is Center/Cap
15 is Center/Center
16 is Center/Base
17 is Center/Bottom
18 is Right/Very Top
19 is Right/Top
20 is Right/Cap
21 is Right/Center
22 is Right/Base
23 is Right/Bottom
phocus_text_string The text to be displayed.
Range: Any character string
Default: No default
Attribute Name Contents
22-7 FME Reference Manual Version 2.0
Safe Software Inc. PHOCUS PHODAT READER
GUI FILENAME DestDataset GIF_Files(*.gif)|*.gif|All_files(*.*)|*.*
Destination GIF Dataset
GIF_DATASET $(DestDataset)
# ================================================================
GIF_WIDTH $(_WIDTH)
GIF_HEIGHT $(_HEIGHT)
GIF_SQUARE_PIXELS $(_SQUARE)
# ================================================================
# Now define a number of colours with GIF_DEF lines.
GIF_DEF DarkRed GIF_RED 85 GIF_GREEN 0 GIF_BLUE 0
GIF_DEF MediumRed GIF_RED 170 GIF_GREEN 0 GIF_BLUE 0
GIF_DEF BrightRed GIF_RED 255 GIF_GREEN 0 GIF_BLUE 0
GIF_DEF LightRed GIF_RED 255 GIF_GREEN 85 GIF_BLUE 85
GIF_DEF BrickRed GIF_RED 160 GIF_GREEN 64 GIF_BLUE 64
# ================================================================
# Set the background color of the GIF to white.
GIF_BACKGROUND_COLOR White
Lookup IndexedColorLUT 0 DarkRed \
1 MediumRed \
2 BrightRed \
3 LightRed \
4 BrickRed \
5 CherryRed \
# ================================================================
PHOCUS phocus_line
GIF DarkRed \
gif_type gif_line
# ================================================================
PHOCUS phocus_text \
phocus_type phocus_text \
phocus_text_string %phocus_text_string
GIF MediumRed \
gif_type gif_text \
gif_font gif_font_small \
gif_text_string %phocus_text_string
# ================================================================
PHOCUS phocus_point \
phocus_type phocus_point
GIF BrightRed \
gif_type gif_point
# ================================================================
PHOCUS phocus_area \
phocus_type phocus_area
GIF LightRed \
gif_type gif_polygon
gif_fill_color Lavender
PHOCUS PHODAT READER Safe Software Inc.
22-8 FME Reference Manual Version 2.0
23-1 FME Reference Manual Version 2.0
23
23 RELATIONAL TABLE READER/
WRITER
The Relational Table reader and writer modules provide the Feature
Manipulation Engine (FME) with access to the attribute data held in a variety
of tabular data formats. This data may not necessarily have any spatial
component to it. The Relational Table reader module may be used as part of
a multi-reader to combine metadata held in database files into a Spatial
Archive and Interchange Format (SAIF) dataset. These modules may also be
used in combination with the @Relate command to translate normalized
data into an object model, or vice versa.
1
23.1 Overview
The FME considers a Relational Table dataset to be a collection of relational
files in a single directory. Relational Table files of multiple types may be read
or written by a single Relational Table reader or writer. The type and schema
of each Relational Table file must be defined in the mapping file before it can
be read or written.
Relational Table files consist of repeating tuples of attributes, formatted
according to their definition. The feature type of each row read from a
Relational Table file is defined in the mapping file.
1. The Relational Table reader and writer differs from the @Relate command. The @Relate
command is used to join attributes to existing FME features or write out feature attribute data,
while the Relational Table reader and writer create or output entire FME features.
RELATIONAL TABLE READER/WRITER Safe Software Inc.
23-2 FME Reference Manual Version 2.0
Currently, DBase (DBF), Comma Separated Value (CSV), Column Aligned Text
(CAT), and freeform ASCII relational files are supported by the Relational Table
reader and writer. In the future, support for database tables managed by Relational
DataBase Management Systems (RDBMSes) such as Oracle or Sybase will be added.
23.2 Reader Overview
The Relational Table reader module produces FME features for all data held in
Relational Table files residing in a given directory. The Relational Table reader first
scans the directory it is given for all Relational Table files defined in the mapping file.
For each Relational Table file that it finds, it checks to see if that file is requested by
looking at the list of IDs specified in the mapping file. If a match is made or no IDs
were specified in the mapping file, the Relational Table file is opened. The Relational
Table reader extracts data from the table one row at a time, produces FME features
from them, and passes them on to the rest of the FME for further processing. When
the file is exhausted, the Relational Table reader starts on the next file in the directory.
23.2.1 Reader Keywords
The following table lists the keywords processed by the Relational Table reader. The
table shows only the suffixes prefixed by the current <ReaderKeyword> in a
mapping file. By default, the <ReaderKeyword> for the Relational Table reader is
TABLE.
Keyword Suffix Value Required/
Optional
DATASET Contains the directory name of the input Relational Table
files.
Required
DEF Defines a Relational Table file. Each Relational Table
file must be defined before it can be read. The definition
contains the feature type of the file, its file name, its type,
and the definitions of each of its fields. There may be
many DEF lines, one for each file to be read.
Required
IDs Contains a list of Relational Table files to process. If
more Relational Table files are in the directory, they are
ignored. If this is not specified, then all defined
Relational Table files in the directory are read.
Optional
23-3 FME Reference Manual Version 2.0
Safe Software Inc. RELATIONAL TABLE READER/WRITER
23.2.2 DATASET
The value for this keyword is the directory containing the Relational Table files to be
read. A typical mapping file fragment specifying an input Relational Table dataset
looks like:
TABLE_DATASET /usr/data/attributes
23.2.3 DEF
Each Relational Table file must be defined before it can be read. The definition
specifies only the base name of the file and the type of geometry it contains. The
syntax of a Relational Table DEF line is:
<ReaderKeyword>_DEF <featureType> \
<tableType> <fileName> \
[<attrName> <attrType>]+
The <featureType> is used as the feature type of all features read from the table.
The <fileName> is the full filename, including the extension, of the Relational
Table file. The <fileName> does not contain any directory information and its
assumed to be located in the TABLE_DATASET directory.
TIP: In the future, databases will be supported as new <tableTypes>.
The <tableType> determines the physical structure of the table. The table below
describes the values recognized for <tableType>.
Table Type Description
ASCII Relational files of this type follow a regular, but freeform
pattern. Fields are separated by spaces or end-of-line
characters. Special attribute names and types in the table
definition control the placement of the end-of-line
characters.
CAT Column Aligned Text (CAT) often stores legacy data
produced by FORTRAN Input/Output (IO) statements.
Each field is a fixed width with no separating characters
between adjacent fields. Each line in a CAT file corresponds
to one record. Several logical CAT files can be stored in a
single physical CAT file through the use of record keys,
which are special fields on each record that determine the
records logical type.
CSV Comma Separated Value (CSV) files are ASCII files with
the record fields separated by commas. Each line in a CSV
file corresponds to one record. The default separator, a
comma, can be overridden on the files definition line.
DBF DBase Format (DBF) files are formatted according to the
DBase specification.
RELATIONAL TABLE READER/WRITER Safe Software Inc.
23-4 FME Reference Manual Version 2.0
Each different file type supports different attribute types. The following subsections
detail the allowable attribute types for each file type.
23.2.3.1 ASCII Field Types
Field Type Description
as_constant A freeform ASCII file that may contain constants as part of
each record. Such constants are not to be transferred to
features as attribute values but when the ASCII file is
written, the constant must be output. Fields of the type
as_constant are used to represent such fields to the FME.
The field name in this case is interpreted as being the value
of the constant, and not a field name within a feature.
as_special This field type is used in conjunction with one of the special
ASCII field names listed in the next subsection.
char(<width>) String fields store character strings. The width parameter
controls the maximum number of characters that can be
stored by the field.
date Date fields store dates as character strings with the format
YYYYMMDD. When date fields are read, they assign the
date in the above format to the fieldname. In addition, they
assign these fields:
<fieldName> YYYYMMDD
<fieldName >.yyyy YYYY
<fieldName >.yy YY
<fieldName >.mm MM
<fieldName >.dd DD
When a date field is written, it first looks for the complete
date to be held in the fieldname. Failing that, it looks in the
.yyyy or .yy, .mm, and .dd fields for the date portions, and
creates the date from these.
float(<width>,<decimals>) Float fields store floating point values. The width
parameter is the total number of characters allocated to the
field, including the decimal point. The decimals parameter
controls the precision of the data and is the number of digits
to the right of the decimal.
integer(<width>) Integer fields store integer values. The width parameter is
the total number of characters allocated to the field.
stringlist A stringlist field in an ASCII table consists of an integer
value indicating the number of elements in the list, followed
by a series of lines containing the string elements. Such a
field is stored or retrieved from an FME list stored in an
FME feature.
23-5 FME Reference Manual Version 2.0
Safe Software Inc. RELATIONAL TABLE READER/WRITER
23.2.3.2 ASCII Special Fields
23.2.3.3 CAT Field Types
as_lineend{#}
as_special
In freeform ASCII files, line-end characters must be
explicitly identified to indicate when line breaks
occur in the file. Line-ends are indicated by the
as_lineend special field name. Each lineend
must be assigned a unique number within the table,
and this number is appended in braces to the
as_lineend field name. The as_lineend field
names must always have a type of as_special.
as_coordinatelist
as_special
Two-dimensional feature coordinate values may be
read from or written to freeform ASCII files. Such
coordinates are preceded in the file by an integer
indicating the number of coordinates. The
coordinates are then written, in X Y pairs separated
by blanks, on consecutive lines.
Field Type Description
Integer(<width>,
<position>,
<zeroPad>)
Integer fields store integer values. The width
parameter is the total number of characters allocated to
the field. The position parameter is the starting
column of the field in the CAT record. The columns are
numbered starting from 1. If the zeroPad parameter is
Y, then the number is padded with zeros on the left to
fill out the field. If the zeroPad parameter is N, then
no zero padding is performed.
Real(<width>,<position>,
<decimals>)
Real fields store floating point values. The width
parameter is the total number of characters allocated to
the field, including the decimal point. The position
parameter is the starting column of the field in the CAT
record. The columns are numbered starting from 1. The
decimals parameter controls the precision of the data
and is the number of digits to the right of the decimal.
String(<width>,<position>) String fields store fixed length strings. The width
parameter controls the maximum of characters that can
be stored by the field. When a character field is written,
it is right-padded with blanks or truncated to fit the
width. When a character field is retrieved, any padding
blank characters are stripped. The position
parameter is the starting column of the field in the CAT
record. The columns are numbered starting from 1.
RELATIONAL TABLE READER/WRITER Safe Software Inc.
23-6 FME Reference Manual Version 2.0
23.2.3.4 CAT Special Fields
23.2.3.5 CSV/DBF Field Types
[CAT_SUBTYPE
(<start>,<length>,
<constant>)]
If the table is a CAT table, a special field may be
listed to identify the record key of the records.
This allows several different record types to be
held in the same physical CAT file. If no
CAT_SUBTYPE is identified, then no record key
is assumed to be present in the file. For this field,
fieldType is used to convey the specifics of the
record key. The parameters of this special field are
listed in the following table.
Name Range Description Optional
<start> Integer If the file is a CAT type, an
optional record key may be
specified. This allows several
different record types to be held
in the same physical CAT file.
This parameter defines the
starting column of the key.
Columns are numbered starting
with 1.
Yes
<length> Integer The length in characters of the
optional CAT record key.
Yes
<constant> String The constant used as the optional
CAT record key, which occurs in
the record at the <start>
column.
Yes
Field Type Description
number(<width>,<decimals>) Number fields store floating point values. The width
parameter is the total number of characters allocated to
the field, including the decimal point. The decimals
parameter controls the precision of the data and is the
number of digits to the right of the decimal.
23-7 FME Reference Manual Version 2.0
Safe Software Inc. RELATIONAL TABLE READER/WRITER
23.2.3.6 CSV Special Fields
23.2.4 IDs
This optional specification is used to limit the available and defined Relational Table
files that will be read. If no IDs are specified, then all defined and available
Relational Table files will be read. The syntax of the IDs keyword is:
<ReaderKeyword>_IDs <featureType1> \
<featureType2> \
<featureTypeN>
The feature types must match those used in DEF lines.
The example below selects only the History Relational Table file for input during
a translation:
TABLE_IDs History
char(<width>) Character fields store fixed length strings. The width
parameter specifies the number of characters that can be
stored. When a character field is written, it is right-
padded with blanks or truncated to fit the width. When
a character field is retrieved, any padding blank
characters are stripped.
logical Logical fields store TRUE/FALSE data. Data read or
written from/to such fields must always have a value of
either true or false.
date Date fields store dates as character strings with the
format YYYYMMDD.
[CSV_SEPARATOR
(<separator>)]
If the table is a CSV table, a special field may be
listed to identify the separator used to divide the
fields in the file. By default, a comma is used as the
separator. For this field, fieldType contains the new
separator, enclosed in parentheses. The separator
must be only 1 character long.
[CSV_SKIP_LINES
<number>]
If the table is a CSV table, a special field may be
listed to indicate the number of lines to skip at the top
of the file. By default, no lines are skipped. Each line
skipped is logged to the log file. This is useful if the
CSV file contains a header line of field names or
other descriptive material that should be skipped.
Field Type Description
RELATIONAL TABLE READER/WRITER Safe Software Inc.
23-8 FME Reference Manual Version 2.0
23.3 Writer Overview
The Relational Table writer creates and writes feature data to Relational Table files
in the directory specified by the DATASET keyword. As with the reader, the directory
must exist before the translation occurs. Any old Relational Table files in the
directory are overwritten with the new feature data. As features are routed to the
Relational Table writer by the FME, it determines which file they are to be written to
and outputs them according to the type of file. Many Relational Table files can be
written during a single FME session.
23.3.1 Writer Keywords
The Relational Table writer processes the DATASET and DEF keywords as described
in the Reader Keywords section. It does not make use of the IDs keyword.
23.4 Feature Representation
Relational Table features consist of a series of attribute values. The attribute names
are defined in the DEF line, and there is a value for each attribute in each FME
Relational Table feature. The feature type of each Relational Table feature is also
defined on its DEF line.
The example below shows an FME mapping file used to translate a Comma Separated
Value Relational Table file into an ASCII Relational Table File.
23.5 Example
This example copies a comma separated value file to a freeform ASCII
representation.
LOG_FILENAME table.log
READER_TYPE TABLE
WRITER_TYPE TABLE
WRITER_KEYWORD T_OUT
TABLE_DATASET .
T_OUT_DATASET .
23-9 FME Reference Manual Version 2.0
Safe Software Inc. RELATIONAL TABLE READER/WRITER
# -----------------------------------------------------------
# Define the input table
TABLE_DEF polygon CSV polygon.csv \
mapsheetId char(10) \
polygonId number(3,0) \
inopCode string(2) \
layerCount number(3,0) \
historyCount number(3,0) \
yyyymmdd date \
yy number(2,0) \
mm number(2,0) \
dd number(2,0)
# -----------------------------------------------------------
# Define the output table
T_OUT_DEF polygon ASCII polygon.sa \
MAP char(10) \
POLYGONID char(4) \
AS_LINEEND{0} AS_SPECIAL \
AS_CONSTANT bananroot \
INOPCODE char(2) \
LAYERCOUNT float(2,0) \
HISTORYCNT integer(2,0) \
date1 date \
date2 date \
AS_LINEEND{1} AS_LINEEND
# -----------------------------------------------------------
# Finally, transfer specifications.
TABLE polygon \
mapsheetId %m \
polygonId %p \
inopCode %i \
layerCount %l \
historyCount %h \
yyyymmdd %d1 \
yy %yy2 \
mm %mm2 \
dd %dd2
T_OUT polygon \
MAP %m \
POLYGONID %p \
INOPCODE %i \
LAYERCOUNT %l \
HISTORYCNT %h \
date1 %d1 \
date2.yyyy %yy2 \
date2.mm %mm2 \
date2.dd %dd2
RELATIONAL TABLE READER/WRITER Safe Software Inc.
23-10 FME Reference Manual Version 2.0
24-1 FME Reference Manual Version 2.0
24
24 SPATIAL ARCHIVE AND
INTERCHANGE FORMAT (SAIF)
READER/WRITER
The Spatial Archive and Interchange Format (SAIF) features a powerful
object-oriented data model described in an easy to use data definition
language called Class Syntax Notation (CSN). SAIF is the standard archive
and interchange format for geographic data in the province of British
Columbia. SAIF was developed to address both data interchange and data
archival issues.
1
As a result, SAIF is an excellent format for storing
geographic data in a vendor-neutral manner. The Feature Manipulation
Engine (FME) enables data stored in SAIF to be easily translated to any of the
popular vendor formats.
TIP: There is a wealth of material describing SAIF on the World Wide Web at www.env.gov.bc.ca/
gdbc.
24.1 Overview
SAIF uses the latest paradigm in data modeling. It employs an object-oriented
data model supporting multiple inheritance. SAIF was designed to be user-
extensible allowing users to easily create new class definitions. While
designed with spatial data in mind, SAIF can be used just as effectively to
model any type of data.
1. SAIF datasets are self-contained. A single SAIF dataset contains both the data and the data
model which describes the data.
SPATIAL ARCHIVE AND INTERCHANGE FORMAT (SAIF) READER/WRITER Safe Software Inc.
24-2 FME Reference Manual Version 2.0
SAIF also supports other advanced data modeling concepts not found in any of the
other formats.
Object Referencing: SAIF enables objects within a single dataset to reference
component objects. For example, if the geometry of a linear feature defines both
a river bank and a lot boundary, then SAIF enables both the river and the lot
boundary to reference the same linear feature.
Direct Support for Multimedia Datatypes: SAIF enables multimedia
datatypes such as JPEG, Graphic Interchange Format (GIF), Sound Files, or any
other type of file to be stored directly within a dataset. Attributes which describe
the embedded information are also stored in the file.
Object Linking: SAIF enables objects within a SAIF dataset to refer to other
objects and to associate attributes with these links.
SAIF datasets have the following structure.
24.1.1 SAIF Directory
SAIF datasets are composed of a collection of addressable objects. Each addressable
object is identified with a unique identifier stored in the SAIF directory, along with
the objects class information and the objects location within the dataset.
Unlike other file-based data storage formats, SAIF uses the directory to support
random retrieval of data. For example, if a SAIF dataset contains Roads,
SAIF Directory
SAIF Schema
(CSN)
SAIF
Object
Definitions
(OSN)
SAIF Dataset Structure
24-3 FME Reference Manual Version 2.0
Safe Software Inc. SPATIAL ARCHIVE AND INTERCHANGE FORMAT (SAIF) READER/WRITER
Railroads, Rivers, and so on, you can quickly retrieve the Roads objects from
the dataset without having to read features of any other type. Each addressable object
in SAIF is generally used to hold a collection of features of the same type. For
example, one addressable object may hold all of the Roads while another
addressable object holds the Railroads, and a third addressable object contains the
Rivers. This organization of data fits well with that used by most Geographical
Information Systems (GIS) products.
TIP: If a user wishes to read every feature in a SAIF dataset, then the IDs keyword can be omitted.
The <ReaderKeyword>_IDs statement within an FME mapping file is used to
identify the objects to be retrieved from a SAIF dataset.
Upon opening a SAIF Dataset, the SAIF reader logs the contents of the SAIF dataset
to the FME logfile.
24.1.2 SAIF Schema
The second major component of a SAIF dataset is the SAIF Schema. The SAIF
Schema contains the class definitions for all objects stored within the SAIF dataset.
Every SAIF feature within the dataset is defined by the data model stored in this
portion of the dataset. The class definitions are specified the Class Syntax Notation
(CSN). CSN is an easy to read notation, used specifically for defining classes in
SAIF. See the Spatial Archive and Interchange Format: Formal Specification
Release 3.2 for a complete description of SAIF and CSN.
24.1.3 SAIF Object Definitions
The third, and final, component of a SAIF dataset contains the feature data. The
feature data within SAIF is stored in Object Syntax Notation (OSN). OSN is used
specifically for defining objects in SAIF. See the Spatial Archive and Interchange
Format: Formal Specification Release 3.2 for a complete description of SAIF and
OSN.
The object definitions are broken down into smaller units called object sets. Each
object set contains a collection of objects. For discussion purposes, it is assumed that
there is a one-to-one correspondence between addressable objects and object sets,
and you can use them interchangeably. The distinction between these two concepts is
beyond the scope of this document.
For a more detailed description of the organizations of a SAIF dataset, see the SAIF
Toolkit API Programmers Reference Manual Release 1.1.
SPATIAL ARCHIVE AND INTERCHANGE FORMAT (SAIF) READER/WRITER Safe Software Inc.
24-4 FME Reference Manual Version 2.0
24.2 Reader Overview
The SAIF reader module produces FME features from the features held in a SAIF
dataset. The SAIF reader first opens the SAIF dataset, retrieving the directory
information. Then it determines the objects to be read from the dataset by comparing
the objects held in the dataset with those specified on the IDs statement of the FME
mapping file. If no IDs are specified, then the SAIF reader module returns all objects
in the SAIF dataset. The SAIF reader then extracts features from the SAIF dataset,
one at a time, and passes them on to the rest of the FME.
24.2.1 Reader Keywords
The following table lists the keywords processed by the SAIF reader. The table shows
only the suffixes prefixed by the current <ReaderKeyword> in a mapping file.
By default, the <ReaderKeyword> for the SAIF reader is SAIF.
24.2.2 DATASET
The value for this keyword is the name of the SAIF dataset file. A typical mapping
file fragment specifying an input SAIF dataset looks like:
SAIF_DATASET /usr/data/SAIF/92i080.zip
24.2.3 IDs
This optional specification is used to limit which of the available and defined SAIF
addressable objects are read. If there are no IDs specified, then all defined and
available addressable objects are read.
TIP: The SAIF Utilities package can be used to list the IDs present in a SAIF dataset.
Keyword Suffix Value Required/
Optional
DATASET Contains the name of the input SAIF Dataset. Required
IDs The list of SAIF addressable objects to be processed by
the SAIF reader. If this is not specified, all addressable
objects within the SAIF dataset are processed.
Optional
AGGREGATED_
MEASURED_
SURFACE
This flag controls whether or not SAIF Measured Surface
Objects are read into a single aggregate feature, or
returned as individual DEMpoint and Breakline features.
The default is NO, which means that the latter option is
taken.
Optional
24-5 FME Reference Manual Version 2.0
Safe Software Inc. SPATIAL ARCHIVE AND INTERCHANGE FORMAT (SAIF) READER/WRITER
The syntax of the IDs keyword is:
<ReaderKeyword>_IDs <SAIF ID1> \
<SAIF ID2> \
<SAIF ID3>
The list of IDs can also be specified across multiple <ReaderKeyword>_IDs
statements, in which case the union of all IDs statements are used.
The example below selects only the roads for input during a translation:
SAIF_IDs roads
24.3 Writer Overview
The SAIF writer creates and writes feature data to the SAIF archive identified by
SAIF_DATASET. If the output SAIF dataset existed before the writer was run, then
it is overwritten with the new data. The SAIF writer is able to have many different
SAIF object sets open at a single time. As features are routed to the SAIF writer by
the FME, it determines the object set into which the feature is destined and writes the
feature out to that object set.
24.3.1 Writer Keywords
The SAIF writer makes use of a large number of keywords which are listed in the
table below. The table shows only the suffixes prefixed by the current
<WriterKeyword> in a mapping file.
TIP: The SAIF Utilities package can be used to check the syntax and validate the definitions held in the CSN
before they are used by the FME.
By default, the <WriterKeyword> for the SAIF reader is SAIF.
Keyword Suffix Value Required/
Optional
DATASET Contains the name of the Input SAIF Dataset. Required
DEF Defines a SAIF Addressable Object. Each SAIF
Addressable Object must be defined before it can
be written.
Required
CSN The name of a file which contains SAIF CSN
definitions used for the dataset being written. This
line occurs once for each CSN required file. The
files must be ordered so that no CSN file has a
dependency on another CSN file later in the FME
mapping file. The first CSN file specified always
contains the set of SAIF base classes.
Required
SPATIAL ARCHIVE AND INTERCHANGE FORMAT (SAIF) READER/WRITER Safe Software Inc.
24-6 FME Reference Manual Version 2.0
24.3.2 DATASET
The value for this keyword is the name of the SAIF dataset file. A typical mapping
file fragment specifying an output SAIF dataset looks like:
SAIF_DATASET /usr/data/SAIF/92i080.zip
24.3.3 DEF
Before any SAIF data can be written, the SAIF addressable object, in which the
features are contained, must be specified. The syntax of the SAIF DEF line is:
SAIF_DEF <membertype> \
[SAIF_COMPOSITE_CLASS <composite type>] \
[SAIF_IDENTIFIER <identifier>] \
[SAIF_OBJECTSET <object set id>] \
[SAIF_AGGREGATE <aggregate spec>] \
[SAIF_COMPONENT_PATH <componentPath>] \
[<geoComponents spec>]* \
[<attr path> <attr value>]*
Each of the components of the SAIF_DEF statement are described below. The DEF
line attempts to make SAIF as easy to define as possible by generating defaults that
can be used in the majority of cases. See the points below for the values of these
defaults and a discussion of what they mean and when to override them.
<membertype>: This is the feature type of the objects stored within the SAIF
object being defined. In SAIF it is strongly suggested that all class names consist of
two parts; a <class name>, and <domain name> separated by a double colon (::).
<class name>: A unique class name within the current domain.
<domain name>: Each CSN definition set, except the base set, must use a domain
name. The domain name choice is left up to you.
XCOORD_TYPE The numeric type used for the x coordinate. Valid
values include STK_REAL64, STK_REAL32, and
STK_INT32.
Required
YCOORD_TYPE The numeric type used for the y coordinate.
Established values include STK_REAL64,
STK_REAL32, and STK_INT32.
Required
ZCOORD_TYPE The numeric type used for the z coordinate.
Established values include STK_REAL64,
STK_REAL32, and STK_INT32.
Required
Keyword Suffix Value Required/
Optional
24-7 FME Reference Manual Version 2.0
Safe Software Inc. SPATIAL ARCHIVE AND INTERCHANGE FORMAT (SAIF) READER/WRITER
The example below defines the member type of objects to be Roads::TRIM.
Roads is the <class name> component and TRIM is the <domain name>
component.
SAIF_DEF Roads::TRIM
SAIF_COMPOSITE_CLASS
This is the name of the composite class into which the SAIF objects of type
<membertype> are stored. This is the actual SAIF class which is addressable. Each
DEF line defines a single addressable object of the type specified here. If this is not
specified, then a default value is generated which inserts the word Composite
immediately before the double :: specified in <membertype>.
Using the above example, the default value of SAIF_COMPOSITE_CLASS is
RoadsComposite::TRIM. This value can be overridden simply by specifying
the SAIF_COMPOSITE_CLASS parameter. The example below overrides the
default value instead specifying RoadsCollection::TRIM.
SAIF_COMPOSITE_CLASS RoadsCollection::TRIM
SAIF_IDENTIFIER
This is the identifier used to identify the SAIF addressable object being defined by
this SAIF_DEF line. If not specified, the default value for the identifier is the same
as the <membertype> with the double colon and the domain name removed.
Using the example above, the default value of SAIF_IDENTIFIER is Roads. This
value can be overridden by specifying the SAIF_IDENTIIFIER parameter. The
example below overrides the default value specifying TRIMRoads.
SAIF_IDENTIFIER TRIMRoads
SAIF_OBJECTSET
This defines the object set into which the addressable object being defined is to be
stored. If not specified, the default value for the identifier is generated using the first
4 characters of the <membertype> followed by the last two characters before the
double colon (::). If the <class name> portion of the <membertype> is less
than 6 characters, the object set name is taken to be equal to <class name>.
Using the example above, the default value of SAIF_OBJECTSET is roads. This
value can be overridden by specifying the SAIF_OBJECTSET parameter. The
example below overrides the default value specifying troads.
SAIF_OBJECTSET troads
SPATIAL ARCHIVE AND INTERCHANGE FORMAT (SAIF) READER/WRITER Safe Software Inc.
24-8 FME Reference Manual Version 2.0
SAIF_AGGREGATE
This defines the aggregate into which the objects are to be placed. This parameter is
only used when the features being defined are stored within a SAIF aggregate, which
is itself stored within another aggregate. An example of when this occurs is the SAIF
DEM into which DEMpoints, Breaklines, and other aggregates are stored. See the
SAIF Formal Specification for a description of SAIF aggregates. The example below
shows how to specify the aggregate for storing DEMpoints.
SAIF_AGGREGATE geoComponents{0}.position.geometry.masspoints
The statement above gives the full path to where the features belonging to this
SAIF_DEF line are placed. They are placed within the aggregate identified by
position.geometry.masspoints which itself is stored as the first element
within the aggregate geoComponents.
Usually, this line follows immediately after one or more <geoComponents
spec> lines, which are described below.
SAIF_COMPONENT_PATH
The SAIF component path defines the path to the aggregate into which the features
belonging to this SAIF_DEF are placed. By default, the value of this parameter is
geoComponents as this is the value used in the majority of cases. An example of
when the value needs to be overridden is when the feature represents a SAIF text
object. In this case, the SAIF_COMPONENT_PATH should be specified as
annotationComponents. The example below overrides the default value and
specifies a component path of annotation components.
SAIF_COMPONENT_PATH annotationComponents
<geoComponents spec>
This portion of the SAIF_DEF line is required only when the SAIF_AGGREGATE
line is used. These specifications define the geoComponent aggregate classes
before the first feature arrives. This statement configures the aggregates so that the
features associated with this SAIF_DEF line can be inserted into SAIF. The example
below continues the example given for the SAIF_AGGREGATE line above, and
defines the two aggregates required before DEMpoints can be stored within the
SAIF dataset.
geoComponents{0}.Class PointsAndBreaklines::TRIM \
geoComponents{0}.position.geometry.Class MeasuredSurface
The first line defines the type of aggregate for the first element of the
geoComponents aggregate. It is defined to be of the type
PointsAndBreaklines::TRIM. The first part of this statement
geoComponents{0} defines the path name of the aggregate. The .Class suffix
24-9 FME Reference Manual Version 2.0
Safe Software Inc. SPATIAL ARCHIVE AND INTERCHANGE FORMAT (SAIF) READER/WRITER
instructs the underlying SAIF Toolkit, which the SAIF writer uses, that this is the
name of the class for the object that has a path of geoComponents. See the SAIF
Toolkit documentation for a full discussion of the .Class notation and the meaning
of path names in SAIF.
The second line defines the type of aggregate for the object with the path name
position.geometry within the aggregate geoComponents{0}. It is defined
to be of the type MeasuredSurface.
Once this is defined, the SAIF_AGGREGATE line follows to define the aggregate
where the DEMpoints will be stored.
<attr path> <attr value>
These lines are used to simply specify attribute path and attribute value pairs. The first
part of the line identifies the attribute path to be set and the second part of the line
specifies the value to be assigned to the attribute. These attribute values are used to
set any attribute values at the aggregate level. The SAIF_DEF line cannot be used to
set any attribute values for the features actually stored within the SAIF dataset.
24.3.4 CSN
The FME mapping file will have one or more SAIF_CSN file lines which define the
CSN files that contain the SAIF class definitions for the objects to be stored within
the SAIF dataset. If an attempt is made to define any object not of a class specified in
the CSN files, then an error results and the FME session is stopped.
The example below defines two CSN files. The first file is the SAIF base set of
classes and must always be the first CSN file specified. The second CSN file is a file
that contains a set of domain-specific definitions.
SAIF_CSN saif32.csn
SAIF_CSN forest32.csn
24.3.5 XCOORD_TYPE
This is the numeric domain of the x coordinate. All coordinates stored within the
SAIF dataset will have their x value in the domain specified on this line. The example
below instructs the SAIF writer module that all x coordinates are of the type integer.
SAIF_XCOORD_TYPE STK_INT32
SPATIAL ARCHIVE AND INTERCHANGE FORMAT (SAIF) READER/WRITER Safe Software Inc.
24-10 FME Reference Manual Version 2.0
24.3.6 YCOORD_TYPE
This is the numeric domain of the y coordinate. All coordinates stored within the
SAIF dataset will have their y value in the domain specified on this line. The example
below instructs the SAIF writer module that all y coordinates are single precision
floats.
SAIF_YCOORD_TYPE STK_REAL32
24.3.7 ZCOORD_TYPE
This is the numeric domain of the z coordinate. All coordinates stored within the
SAIF dataset will have their z value in the domain specified on this line. The example
below instructs the SAIF writer module that all z coordinates are double precision
floats.
SAIF_ZCOORD_TYPE STK_REAL64
24.4 Feature Representation
SAIF features consist of a feature type, a geometry or text class, attribute path and
attribute value pairs, and coordinates. A typical FME correlation line for SAIF has
two forms: geometric entity form and text entity form.
24.4.1 Geometric Entity Form
This form of FME correlation line is used for all SAIF geometric entities. The line
first specified is the <member type>. The value specified for <member type>
must match a value specified in a SAIF_DEF line. The line then stipulates the type
of geometry that the feature contains. The FME supports all SAIF geometries
permitted by SAIF-Lite. Finally, the <attribute path> <attribute
value> pairs are specified, as they are for any other formats. The only difference
with SAIF is that the <attribute path> values may be of arbitrary depth. See
the SAIF Toolkit Application Programming Interface (API) document for a
discussion of attribute paths.
2
SAIF <member type> \
position.geometry.Class <geometry class> \
[<attribute path> <attribute value>]*
2. The SAIF-Lite specification and SAIF Toolkit API document describe the allowed geometry types and
the attribute path syntax used by SAIF.
24-11 FME Reference Manual Version 2.0
Safe Software Inc. SPATIAL ARCHIVE AND INTERCHANGE FORMAT (SAIF) READER/WRITER
24.4.2 Text Entity Form
This form of the FME correlation line is used for all SAIF text entities. The line is
almost the same as the geometric entity above, except that instead of specifying a
<geometry class>, a <text class> is specified. See the SAIF Formal
Specification for a list of all the different SAIF text classes that can be specified.
SAIF <member type> \
textOrSymbol.Class <text class> \
[<attribute path> <attribute value>]*
24.5 Example
The following example shows an FME mapping file used to convert features between
IGDS and SAIF. Notice how the DEM and Breakline definitions are done using the
SAIF_AGGREGATE statement and associated aggregate definition lines.
This mapping file doesnt specify READER_TYPE or WRITER_TYPE. It must be
specified on the command line.
#=================================================================
# These SAIF entries are used when we are outputting SAIF data.
# We need to tell the SAIF writer the location of the CSN files,
# and the type of coordinates it should use.
SAIF_CSN saif32.csn
SAIF_CSN trim32.csn
SAIF_XCOORD_TYPE STK_INT32
SAIF_YCOORD_TYPE STK_INT32
SAIF_ZCOORD_TYPE STK_INT32
SAIF_ORGANIZATION 4
SAIF_DEF Island::TRIM
#
#
# The definition of Island::TRIM uses all default values whereas
# the definition of RiverStream::TRIM explicitly gives all values.
#
SAIF_DEF RiverStream::TRIM \
SAIF_COMPOSITE_CLASS RiverStreamComposite::TRIM \
SAIF_IDENTIFIER RiverStreams \
SAIF_OBJECTSET rivers \
SAIF_COMPONENT_PATH geoComponents
#
#
# Now we have some SAIF Definitions for text objects.
# Note how the only value which needs to be overridden
# is the SAIF_COMPONENT_PATH.
#
SPATIAL ARCHIVE AND INTERCHANGE FORMAT (SAIF) READER/WRITER Safe Software Inc.
24-12 FME Reference Manual Version 2.0
SAIF_DEF OtherText::TRIM \
SAIF_COMPONENT_PATH annotationComponents
#
# Finally, some SAIF Definitions for the complicated DEMpoint and
# Breakline case.
# The Breaklines and DEMPoints have to be handled specially,
# since they both go into the same composite
SAIF_DEF DEMpoint \
SAIF_COMPOSITE_CLASS PointsAndBreaklinesComposite::TRIM \
SAIF_IDENTIFIER PointsAndBreaklines \
SAIF_OBJECTSET ptsnbr \
geoComponents{0}.Class PointsAndBreaklines::TRIM \
geoComponents{0}.position.geometry.Class MeasuredSurface \
SAIF_AGGREGATE geoComponents{0}.position.geometry.masspoints
SAIF_DEF Breakline \
SAIF_COMPOSITE_CLASS PointsAndBreaklinesComposite::TRIM \
SAIF_IDENTIFIER PointsAndBreaklines \
SAIF_OBJECTSET ptsnbr \
geoComponents{0}.Class PointsAndBreaklines::TRIM \
geoComponents{0}.position.geometry.Class MeasuredSurface \
SAIF_AGGREGATE geoComponents{0}.position.geometry.breaklines
# Now we have the actual FME correlation lines which identify how
# we go between IGDS and SAIF. Notice how they all look the same
# once we finish with the SAIF_DEF line.
#
# First the DEMpoint correlation line.
IGDS 51 igds_color 1 igds_style 0 igds_class 0 igds_weight 2
igds_type igds_point
SAIF DEMpoint demPoint spotHeight
#
#
#
# Now the OtherText correlation line. Notice the use of the Macros
# to ease readability and the effort required to specify other text
# correlation lines.
#-----------------------------------------------------------------
# Define the TEXT macros
# Note our devious use of the default values for the textClass
# variable.
# There is NO textclass attribute in IGDS, so the default value
# of TextLine will always be supplied to the textClass variable.
MACRO IGDSTextSpec igds_style 0 igds_class 0 igds_weight 1
igds_type igds_text \
igds_text_size %size \
igds_text %string \
igds_font %font \
textclass %textClass:TextLine \
igds_rotation %orientation
Note:
The use of
macros to
encapsulate
correlation
values.
24-13 FME Reference Manual Version 2.0
Safe Software Inc. SPATIAL ARCHIVE AND INTERCHANGE FORMAT (SAIF) READER/WRITER
MACRO SAIFTextSpec textOrSymbol.characterHeight %size \
textOrSymbol.text %string \
textOrSymbol.Class %textClass \
textOrSymbol.fontName %font \
textOrSymbol.orientation @SAIFAngle \
(%orientation)
IGDS 44 igds_color 2 $(IGDSTextSpec)
SAIF OtherText::TRIM textType hydrographic $(SAIFTextSpec)
# Now the Correlation lines for the river stream feature type.
IGDS 39 igds_color 1 igds_style 0 igds_class 1 igds_weight 2
igds_type igds_line
SAIF RiverStream::TRIM position.geometry.Class ArcDirected river-
StreamType definite
#
#
#
# Finally the correlation line for the island feature type.
IGDS 40 igds_color 11 igds_style 0 igds_class 5 igds_weight 0 \
igds_type igds_cell igds_cell_name 40011
SAIF Island::TRIM position.geometry.Class Point
SPATIAL ARCHIVE AND INTERCHANGE FORMAT (SAIF) READER/WRITER Safe Software Inc.
24-14 FME Reference Manual Version 2.0
25-1 FME Reference Manual Version 2.0
25
25 VECTOR PRODUCT FORMAT
(VPF) READER
The Vector Product Format (VPF) reader module provides the FME with
access to data in any of the number of formats that follow the VPF
specification, MIL-STD-2407. This includes, but is not limited to, data which
adhere to the Digital Chart of the World (DCW), Digital Nautical Chart
(DNC), VMap Level 0, VMap Level 1, and UVMap database standards.
25.1 Reader Overview
The VPF reader module produces FME features for all data organized into the
feature classes of a given VPF coverage. For each feature class defined by the
schema for the coverage which is defined by the coverage's FCS table
it checks to see whether that class was requested by looking at the specified
list of IDs and, if it was, reads all features for that feature class.
25.1.1 Reader Keywords
The following table lists the keywords processed by the VPF reader. The table
shows only the suffixes: these will be prefixed by the current
<ReaderKeyword> in a mapping file.
By default, the <ReaderKeyword> for this reader is VPF.
VECTOR PRODUCT FORMAT (VPF) READER Safe Software Inc.
25-2 FME Reference Manual Version 2.0
25.1.2 DATASET
The value for this keyword is the directory that defines the coverage. VPF databases
are defined as a directory hierarchy, with the database directory containing a
subdirectory for each library it contains, and each library containing a subdirectory
for each coverage in that library. The value for the DATASET keyword is the actual
directory for the coverage, which directly contains the tables that define the feature
classes of the coverage.
A typical mapping file fragment that selects the PO (political/oceans) coverage of the
North America library from the CD-ROM for the DCW would be:
VPF_DATASET e:/dcw/noamer/po
25.1.3 DEF
Each feature class must be defined before it can be read. The definition specifies the
name of the feature class, the geometry type line, point, area, text, or complex
of the feature class, and the names and types of all attributes. The syntax of a VPF
DEF line is
<ReaderKeyword>_DEF <featClass> \
VPF_GEOMETRY vpf_line|vpf_point|vpf_area| \
vpf_text|vpf_complex \
[<attrName> <attrType>]+
The VPF_GEOMETRY clause specifies the geometry type for all features in the
feature class. It corresponds to the feature type of the VPF feature class, and
corresponds directly to the type of primitive table that defines the geometry for the
Keyword Suffix Value Required/
Optional
DATASET Defines the file path of the directory that forms
the coverage whose feature classes are to be read.
Required
DEF Defines a single VPF feature class. The feature
class must be defined before it can be read. The
definition contains the feature class name, the
type of geometry it holds, and the definitions of
the attributes of its features. There is one DEF line
for each feature class being read.
Required
VPF_IDs Specifies a list of VPF feature classes to process
from the specified coverage. If this list is
specified, only the named feature classes are read;
otherwise, all feature classes in the coverage will
be read.
Optional
25-3 FME Reference Manual Version 2.0
Safe Software Inc. VECTOR PRODUCT FORMAT (VPF) READER
feature. Complex features may contain any mixture of line, point, area, and text
geometries.
The attribute definition given must match the attributes defined on the specified
feature class in the schema table for the coverage. It is not essential to define all
attributes defined on the feature class, but those defined must not conflict with their
actual definitions.
Attribute names are always translated to uppercase by the VPF reader, and should
appear as such on the DEF lines. The following table shows those attribute types
supported. Note that there is no means to specify coordinate attributes in the DEF line;
the handling of these attributes, along with some other VPF structures, are discussed
in the Special Attribute Handling section.
Field Type Description
char(<width>) All text fields are handled as variable-width strings; the
<width> parameter defines a maximum length of the
fields value.
int Field is a long (32-bit) signed integer.
short Field is a short (16-bit) signed integer.
double Field is a double-precision floating point number.
float Field is a single-precision floating point number.
triplet Field is a VPF triplet ID which refers to a primitive.
These are used in tiled VPF coverages to provide both
local and global primitive IDs for a particular
primitive. The local ID is the identifier of a primitive
within the same tile as the referring primitive, and the
global ID is the identifier of a primitive located in
another or an adjacent tile. The format for triplet ID
attribute values is <localId>, <globalTile>,
<globalId>, where <localId> is the ID of the
primitive in the current tile, <globalId> is the ID of
the primitive in the other tile, and <globalTile> is
the reference number of the other tile as defined by the
TILEREF coverage of the library containing this
coverage.
null Null fields are placeholders in VPF and have no defined
values. They are represented as empty strings in FME
features.
VECTOR PRODUCT FORMAT (VPF) READER Safe Software Inc.
25-4 FME Reference Manual Version 2.0
The following mapping file fragment defines the VPF feature class that contains the
areas from the P/O coverage of the North America coverage of the DCW database.
VPF_DEF POAREA \
VPF_GEOMETRY vpf_area \
ID int \
FAC_ID int \
POPYADMIN char(40) \
POPYCOUN char(2) \
POPYCOUNdesc char(50) \
POPYREG char(2) \
POPYREGdesc char(50) \
POPYTYPE int \
POPYTYPEdesc char(50) \
TILE_ID short
The POPYCOUNdesc, POPYREGdesc, and POPYTYPEdesc fields are the values
corresponding to the POPYCOUN, POPYREG, and POPYTYPE fields respectively, as
they are mapped by the fields respective value descriptor tables. This lookup is
performed automatically by the VPF reader and is discussed in the Special Attribute
Handling section.
25.1.4 IDs
This optional specification is used to limit the available and defined feature classes
read. If no IDs are specified, then all defined and available feature classes are read.
The syntax of the IDs keyword is:
date Dates in VPF are represented as text strings which
follow the ISO 8601 standard.
The format for date fields will be
YYYYMMDDhhmmss.ZZZZZ, where YYYY is
the year, MM is the month, DD is the day, hh is
the hour, mm is the minute, ss is the second, and
ZZZZZ specifies the time zone.
The date string may be truncated at any point, providing
every element of the string up to that point is given. (For
example, a value of 1996 represents the year 1996;
19960812 represents August 12, 1996;
19960812080000. represents 8:00:00 AM on August
12, 1996, in the local time zone; and
19960812150000.Z represents 5:00:00 PM on August
12, 1996 in GMT.)
The . separating the time and zone information may
optionally be a comma (,). The format of the time
zone specification is either Z, to represent Universal
Time, or [+-]hhmm to represent a positive or negative
time zone differential from Greenwich.
Field Type Description
25-5 FME Reference Manual Version 2.0
Safe Software Inc. VECTOR PRODUCT FORMAT (VPF) READER
<ReaderKeyword>_IDs <featClass1> \
<featClass2>... \
<featClassN>
The feature class names are either exactly the feature class names defined in the
<ReaderKeyword>_DEF lines, or are the basename of the feature class feature
table; for instance, the name of the table without the trailing .PFT, .LFT, etc.
25.1.5 Feature Representation
A feature defined in VPF can have zero or more geometries attached to it. For this
reason, all features read from a VPF coverage contain an aggregate of geometries. For
most feature class geometry types, all geometries in the resulting features are the
same type the type of the table. For complex feature classes, a single feature can
contain any mixture of text, point, line, and area features.
The attributes for each geometry are given by the attribute
component{<n>}.<attrName>, where <n> is the position of the geometry in
question with the first one being at position 0, and <attrName> is the geometry-
specific attribute in question.
The attributes defined for each geometry are totalled in the following table. Note that
these attribute names are all in lowercase allowing easier distinction from the
standard attributes, defined in the DEF lines.
Attribute Name Description Defined On
vpf_type The type of this specific geometry. This has
one of the following values: vpf_area,
vpf_line, vpf_point, or vpf_text.
All
geometries
vpf_text_string The string to be displayed for a vpf_text
geometry.
vpf_text
vpf_text_height The height of a vpf_text geometry. This is
automatically extracted from the
SYMBOL_RAT{0}.SIZE attribute. (See
Special Attribute Handling.)
vpf_text
vpf_text_font The font used to display vpf_text geometry.
This is automatically extracted from the
SYMBOL_RAT{0}.FONT or
SYMBOL_RAT{0}.FON attribute. (See Special
Attribute Handling.)
vpf_text
vpf_text_color The color used to display vpf_text
geometry. This is automatically extracted from
the SYMBOL_RAT{0}.COLOR or
SYMBOL_RAT{0}.COL attribute. (See Special
Attribute Handling.)
vpf_text
VECTOR PRODUCT FORMAT (VPF) READER Safe Software Inc.
25-6 FME Reference Manual Version 2.0
The following example lists the attributes that appear on a feature within a complex
feature class, containing both a line and a text attribute:
ID 234
RCLASS MR001
component{0}.vpf_type vpf_line
component{1}.vpf_type vpf_text
component{1}.vpf_text_string 23rd Street
component{1}.rotation 14.012
component{1}.vpf_text_font 12
component{1}.vpf_text_color 3
component{1}.vpf_text_style 5
component{1}.vpf_text_height 14.12
The features read from the feature class are normally pushed through a
DeaggregateFactory to extract the individual geometries. This is defined as:
FACTORY_DEF VPF DeaggregateFactory \
INPUT FEATURE_TYPE * fme_geometry fme_aggregate \
LIST_NAME component{} \
OUTPUT LINE FEATURE_TYPE * \
OUTPUT DONUT FEATURE_TYPE * \
OUTPUT POINT FEATURE_TYPE * \
OUTPUT POLYGON FEATURE_TYPE *
25.2 Special Attribute Handling
The structuring of VPF data allows for a very expressive schema definition, which is
somewhat difficult to capture using traditional typing information. The following
variations, from a flat table structure, are of particular interest:
VPF may contain attributes that are arrays of two-dimensional (2D) and three-
dimensional (3D) coordinates.
vpf_text_style The style used to display vpf_text geometry.
This is automatically extracted from the
SYMBOL_RAT{0}.STYLE or
SYMBOL_RAT{0}.STY attribute. (See Special
Attribute Handling.)
vpf_text
vpf_rotation The rotation at which the text is to be
displayed. This is calculated from the lower
left and lower right coordinates of the text line,
and is expressed in degrees counter-clockwise
from due east. It defaults to 0.0 if the text
geometry has only one coordinate in the VPF
data.
vpf_text
Attribute Name Description Defined On
25-7 FME Reference Manual Version 2.0
Safe Software Inc. VECTOR PRODUCT FORMAT (VPF) READER
Any integer or text attribute in a VPF table may be associated with a value
descriptor table, giving a more verbose textual description of the attribute.
Feature classes in VPF are defined by joining various tables together, leading to
a hierarchy of attribute values.
Text primitives do not themselves contain any color, style, size, or font
information, but the features often define these attributes by relating in a
symbology table, such as SYMBOL.RAT.
25.2.1 Coordinate Attributes
Arrays of VPF coordinates are decomposed into individual floating point values, and
are defined on FME features as <attrName>{<n>}.x, <attrName>{<n>}.y,
and <attrName>{<n>}.z, where <attrName> is the name of the attribute that
is defined in VPF as being an array of coordinates, and <n> is the index of the
coordinate in question.
Therefore, if a VPF table contains an attribute named COORDS which is an array of
five 3D coordinates, the FME feature read from the VPF feature class has the
following attributes defined on it:
COORDS{0}.x
COORDS{0}.y
COORDS{0}.z
COORDS{1}.x
COORDS{1}.y
COORDS{1}.z
COORDS{2}.x
COORDS{2}.y
COORDS{2}.z
COORDS{3}.x
COORDS{3}.y
COORDS{3}.z
COORDS{4}.x
COORDS{4}.y
COORDS{4}.z
If the coordinates are 2D, then there will be no <attrName>{<n>}.z attributes
defined on the resulting FME features.
At this time, there is no way to specify on the VPF_DEF lines that an attribute is a
coordinate type. However, if a feature class happens to contain a coordinate attribute,
its value is read for each feature, and defined on the FME feature as described above.
If you had a fixed-length coordinate array, you could define each attribute separately
in the VPF_DEF line:
VECTOR PRODUCT FORMAT (VPF) READER Safe Software Inc.
25-8 FME Reference Manual Version 2.0
VPF_DEF MYCLASS \
VPF_GEOMETRY vpf_text \
ID int \
COORDS{0}.x float \
COORDS{0}.y float \
COORDS{1}.x float \
COORDS{1}.y float
As the coordinates are read in regardless of the contents of the DEF line, this would
add no value to the actual translation. However, it would provide extra documentation
within the mapping file.
25.3 Value Descriptor Tables
VPF coverages typically contain two value descriptor tables, INT.VDT and
CHAR.VDT. It is possible for any number of *.VDT tables, with any names, but these
are typical. The purpose of the Value Descriptor Table (VDT) is to define, for each
feature class-attribute name pair using the VDT, a mapping of an integer or short text
string with limited number of values, and a longer text description of the attribute
value.
For example, VDTs are used to assign an English description to a feature code. An
airport might have a feature code attribute of AF001 meaning an International Air
Field. The feature table for the feature would contain a code of AF001 and a
reference to the value descriptor table. The value descriptor table then provides the
mapping from AF001 to International Air Field.
The lookups into value descriptor tables are handled automatically by the VPF reader.
An attribute named <attrName> corresponding to an entry in a VDT results in two
attributes being defined on the FME feature: <attrName> and
<attrName>desc.
In the above example, the feature code would be defined in an attribute such as FCOD
in the feature table. The resulting FME feature would contain two attributes for this:
FCOD AF001
FCODdesc International Air Field
25.3.1 Table Relations
Every VPF feature class contains a feature table to define the attributes appearing on
features of that class. It is also possible for a VPF feature class to include related
attributes from another table, by specifying that a particular column of the feature
class table relates to a primary column of another table.
25-9 FME Reference Manual Version 2.0
Safe Software Inc. VECTOR PRODUCT FORMAT (VPF) READER
Consider, for example, a mythical database which includes a list of the families of a
street and if they have a fire hydrant on their lawn. This database also allows for many
families to reside at one address. The feature class is defined as follows:
The feature table contains a special column, STRADDR.RAT_ID, used to join
to the identifier column of the STRADDR.RAT table.
The STRADDR.RAT table defines the street addresses and contains a column,
OCCUPANT.RAT_ID, that links into the OCCUPANT.RAT table.
The schema for the street feature class is something like:
Class name: STREETL
Geometry type: vpf_line
Feature table: STREETL.LFT
Table STREETL.LFT attributes:
ID int (Row identifier)
STRADDR.RAT_ID int (Link to STRADDR.RAT table.)
EDG_ID int (Link to edge primitive table.)
STRCODE int (Code for street name; refers to an
value lookup in the INT.VDT table.)
Table STRADDR.RAT attributes:
ID int (Row identifier)
ADDRESS int (Street number)
HYDRANT char(3) (Does it have a hydrant on its lawn;
Yes or No ).
OCCUPANT int (Link to occupants table.)
Table OCCUPANT.RAT attributes:
ID int (Row identifier)
FAM_NAME text(40)(Family name)
NUM_RES int (Number of residents)
CLUST_ID int (Identifies cluster of occupants.)
The feature class table relates the tables according to the following structure:
Table Foreign Attribute Related Table Join
Attribute
STREET.LFT EDG_ID EDG ID
STREETL.LFT STRADDR.RAT_ID STRADDR.RAT ID
STRADDR.RAT OCCUPANT OCCUPANT.RAT CLUST_ID
VECTOR PRODUCT FORMAT (VPF) READER Safe Software Inc.
25-10 FME Reference Manual Version 2.0
A small cul-de-sac containing two properties, one of which has two families living in
it, might be represented in the STREETL feature class with the following feature.
Note the use of nested lists and enhanced values from VDTs. The HYDRANT attribute
would normally come from a value attribute table as well.
Feature class: STREETL
Geometry: Aggregate containing one line
Attributes on feature:
ID 12
STRADDR.RAT_ID 5
EDG_ID 19
STRCODE 5
STRCODEdesc 29th Avenue
STRADDR_RAT{0}.ID 5
STRADDR_RAT{0}.ADDRESS 1234
STRADDR_RAT{0}.HYDRANT Yes
STRADDR_RAT{0}.OCCUPANT 23
STRADDR_RAT{0}.OCCUPANT{0}.ID 1
STRADDR_RAT{0}.OCCUPANT{0}.FAM_NAME Smith
STRADDR_RAT{0}.OCCUPANT{0}.NUM_RES 4
STRADDR_RAT{0}.OCCUPANT{0}.CLUST_ID 23
STRADDR_RAT{0}.OCCUPANT{1}.ID 2
STRADDR_RAT{0}.OCCUPANT{1}.FAM_NAME Jones
STRADDR_RAT{0}.OCCUPANT{1}.NUM_RES 2
STRADDR_RAT{0}.OCCUPANT{1}.CLUST_ID 23
STRADDR_RAT{0}.ID 6
STRADDR_RAT{0}.ADDRESS 2345
STRADDR_RAT{0}.HYDRANT No
STRADDR_RAT{0}.OCCUPANT 14
STRADDR_RAT{1}.OCCUPANT{0}.ID 3
STRADDR_RAT{1}.OCCUPANT{0}.FAM_NAME Murray
STRADDR_RAT{1}.OCCUPANT{0}.NUM_RES 2
STRADDR_RAT{1}.OCCUPANT{0}.CLUST_ID 14
It is important to note that the author is not certain that the VPF standard allows
databases to be structured in this way. However, the VPF reader interprets such
structures, and it provides a reasonable example to explain how related attribute
tables are expressed in FME features. If the VPF standard calls for a flatter structure,
this attribute naming scheme still applies.
25.3.2 Text Primitive Attributes
The display attributes one expects to find for text strings colour, size, style and font
are not actually defined anywhere in the VPF specification.
They are usually handled by assigning a symbology identifier attribute to the
text feature classes feature table, and relating this ID to a symbology attribute table,
typically SYMBOL.RAT. The VPF reader currently defines these text properties
according to the values in the SYMBOL.RAT table. The following attributes are
currently being used to define these values and are searched in the specified order,
and the first value found is taken as the value.
25-11 FME Reference Manual Version 2.0
Safe Software Inc. VECTOR PRODUCT FORMAT (VPF) READER
In the future, this mapping of text attributes will be made more flexible.
Text Attribute Attributed Symbology Used to Define It
text_color SYMBOL_RAT{0}.COLOR, SYMBOL_RAT{0}.COL
text_height SYMBOL_RAT{0}.SIZE, SYMBOL_RAT{0}.SIZ
text_font SYMBOL_RAT{0}.FONT, SYMBOL_RAT{0}.FON
text_style SYMBOL_RAT{0}.STYLE, SYMBOL_RAT{0}.STY
VECTOR PRODUCT FORMAT (VPF) READER Safe Software Inc.
25-12 FME Reference Manual Version 2.0
A-1 FME Reference Manual Version 2.0
A
A FME FUNCTION REFERENCE
A.1 @Abort
@Abort( [<message>] )
FUNCTION TYPE: FEATURE
ARGUMENTS:
A.1.1 Configuration
This function does not accept configuration lines.
A.1.2 Description
This function provides a mechanism for selectively aborting a data
translation. @Abort is typically used to abort a data translation when
erroneous data is encountered. This is particularly useful when using the FME
for quality assurance purposes.
Name Range Description Optional
<message> any string The string which is printed when the
abort function is invoked. This message
can be used to simply identify that the
about function was called, or print a
message which describes the reason the
translation was aborted.
Yes
@Abort FME FUNCTION REFERENCE
A-2 FME Reference Manual Version 2.0
The optional message parameter can be used to print the reason that the data
translation is aborted. For example, if there are several abort functions used
throughout a mapping file then the message should clearly state the reason the
translation was aborted, and identify the particular abort command which was
triggered. If no message is specified then the translation is aborted and no message
is printed.
TIP: Abort is almost always used on an OUTPUT clause of a factory which should never be invoked unless
the input data was bad. Using Abort ensures that the translation will fail and that there is no chance the
bad data will go unnoticed.
The @Abort function also logs the feature upon which it is invoked into the logfile.
A.1.3 Inverse Operation
This function works identically in both the forward and reverse directions.
A.1.4 Example
In the example below, @Abort is used with the ReferenceFactory to terminate the
translation when any of several different erroneous conditions is encountered.
FACTORY_DEF Shape ReferenceFactory \
INPUT REFERENCEE FEATURE_TYPE boundary \
INPUT REFERENCER FEATURE_TYPE forestCover \
REFERENCEE_FIELDS lineID \
REFERENCER_FIELDS arcs{} \
REFERENCE_INFO GEOMETRY \
OUTPUT COMPLETE FEATURE_TYPE * \
OUTPUT INCOMPLETE FEATURE_TYPE * \
@Abort(Incomplete feature found in ReferenceFactory) \
OUTPUT UNREFERENCED FEATURE_TYPE * \
@Abort(Unreferenced boundary arc found) \
OUTPUT NO_REFERENCEE_FIELD FEATURE_TYPE * \
@Abort(Boundary with no reference field) \
OUTPUT DUPLICATE_REFERENCEE FEATURE_TYPE * \
@Abort(Two Boundary arcs found with the same id)
In the second example, @Abort is used in a similar fashion with the PolygonFactory
to terminate the translation when any extraneous linework which does not play a role
in the formation of any polygons is encountered. As part of the OUTPUT LINE
clause, it will be activated as soon as any unclosed linework is output by the factory.
This can be used to flag possible overshoots or undershoots in what should otherwise
be properly noded and closed input linework.
FACTORY_DEF IGDS PolygonFactory \
END_NODED \
INPUT FEATURE_TYPE 33 igds_type igds_line \
OUTPUT POLYGON FEATURE_TYPE FormedPolygon \
OUTPUT LINE FEATURE_TYPE ExtraLines \
@Abort(Extra Linework encountered by PolygonFactory)
A-3 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @AddVertices
A.2 @AddVertices
@AddVertices((x|y|xy),<interval>)
FUNCTION TYPE: FEATURE
ARGUMENTS:
A.2.1 Configuration
This function does not accept configuration lines.
A.2.2 Description
This function adds vertices to features. It interpolates new coordinates at some
specified interval. The interval may be along only one of the two primary axes, or it
may be along the length of the line segments.
This function is most often used to densify the vertices of a feature to prepare it for
reprojection. By adding vertices to long linear segments, the feature will better
represent the original in a different coordinate system.
When used with the x or y option, the function may also be used to add tick marks to
features along an axis at the specified <interval>.
Name Range Description Optional
<axis>
(x|y|xy)
The first parameter controls the axis
which is used to determine when
vertices are added. If xy is specified,
then vertices will be added on the basis
of the 2 dimensional length of
segments. The x and y axis may be
specified to generate tic marks along
each of them at multiples of the
interval.
No
<interval> real number The second parameter specifies the
interval at which vertices will be added.
It is used differently depending on the
setting of the <axis> parameter. If the
<axis> is x or y then the new vertices
will be inserted into the feature along
the specified axis at each multiple of
<interval>. If the <axis> is xy
then new vertices will be inserted so
that no single line segment in the
feature is longer than the
<interval>.
The interval is measured in the features
ground units.
No
@AddVertices FME FUNCTION REFERENCE
A-4 FME Reference Manual Version 2.0
A.2.3 Inverse
This function has no inverse.
A.2.4 Example
In the example below, new vertices are added at even multiples of 10 along the x axis
only.
FACTORY_DEF SHAPE SamplingFactory \
INPUT FEATURE_TYPE * \
@AddVertices(x,10)
If a feature with these coordinates were input:
(7,0,15)
(13,8,25)
(34,50,45)
the feature would exit the factory with these coordinates:
(7,0,15)
(10,4,20)
(13,8,25)
(20,22,41.3333333333333)
(30,42,64.6666666666667)
(34,50,74)
In this second example, new vertices are added to ensure that no segment of any
feature is longer than 10 units.
FACTORY_DEF SHAPE SamplingFactory \
INPUT FEATURE_TYPE * \
@AddVertices(xy,10)
When the input feature from the previous example would exit this factory, it would
have these coordinates:
(7,0,15)
(13,8,25)
(17.4721359549996,16.9442719099992,35.434983894999)
(21.9442719099992,25.8885438199983,45.869967789998)
(26.4164078649987,34.8328157299975,56.3049516849971)
(30.8885438199983,43.7770876399966,66.7399355799961)
(34,50,74)
A-5 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Affine
A.3 @Affine
@Affine(<A>,<B>,<C>,<D>,<E>,<F>)
FUNCTION TYPE: FEATURE
ARGUMENTS:
A.3.1 Configuration
This function does not accept configuration lines.
A.3.2 Description
This function applies an affine transformation to the coordinates of the feature it is
invoked upon. An affine transformation preserves lines and parallelism in geometry.
That is, any lines which were parallel before the transformation will be parallel after
the transformation. As well, if a number of points that fall on a straight line are
transformed, the resulting coordinates fall on a straight line in the new coordinate
system. Affine transformations include translations, scalings, rotations, and
reflections.
A translation is a transformation that preserves the length, angle, and orientation of
all geometric entities. In this case, A = E = 1, B = D = 0, and C and F are the
amounts of the translation.
A rotation is a transformation that preserves the length and angles of all geometric
entities. Rotations also preserve one point and the distance of all entities from that
point.
Scaling transformations include those that preserve all angles and multiply all lengths
by the same factor, thereby preserving the shape of all entities. Another form of
scaling simply scales distances in the x direction by one amount and distances in the
y direction by another amount.
A reflection is a transformation that preserves lengths and magnitudes of angles but
changes their sign. The effect is equivalent to viewing the original geometry in a
mirror, or through a flipped over sheet of transparent paper.
Name Range Description Optional
<A>,<B>,<C>,<D>,
<E>,<F>
real number,
<A> and
<E> must be
non-zero
Coefficients of the affine transformation.
The transformation will result in the x and y
coordinates being modified by:
x = Ax + By + C
y = Dx + Ey + F
No
@Affine FME FUNCTION REFERENCE
A-6 FME Reference Manual Version 2.0
A special kind of affine transformation is called a shear. In a shear which preserves
horizontal lines, A = E = 1, D = 0, and B is non-zero. A shear preserving
vertical lines would have A = E = 1, B = 0, and D non-zero.
A.3.3 Inverse Operation
If applied in the inverse direction, this function will apply the inverse of the affine
transformation specified by its parameters.
In this case, A must be non-zero, as must (A*E - D*B).
A.3.4 Example
In the example below, a shearing transformation is applied to all features as the flow
through the FME:
FACTORY_DEF DWG SamplingFactory \
INPUT FEATURE_TYPE * @Affine(1,0.5,0,0,1,0)
In this second example, a scaling transformation is applied to increase all the x
coordinates by a factor of two and the y coordinates by a factor of three.
FACTORY_DEF DWG SamplingFactory \
INPUT FEATURE_TYPE * @Affine(2,0,0,0,3,0)
A-7 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Arc
A.4 @Arc
@Arc(<semi-primary axis>,<semi-secondary axis> /
[, <numberOfEdges>, <rotation>, <startAngle>, /
<sweepAngle>, <centerX>, <centerY>])
FUNCTION TYPE: FEATURE
ARGUMENTS:
Name Range Description Optional
<semi-primary
axis>
real value Length of the primary axis for the ellipse
upon which the arc is based.
No
<semi-secondary
axis>
real value Length of the secondary axis for the ellipse
upon which the arc is based.
No
<numberOfEdges> real value The number of edges in the final arc. The
default is 0.
Yes
<rotation> real value The rotation of the ellipse which defines the
arc. The rotation angle specifies the angle in
degrees from the horizontal axis to the
primary axis in a counter clockwise
direction. Default is 0.
Yes
<startAngle> real value The start angle in degrees measured
counterclockwise from horizontal. Default is
0.
Yes
<sweepAngle> real value The number of degrees on the ellipse which
define the arc measured in degrees
counterclockwise. If the sweepAngle is 360,
then the feature will be tagged as a polygon
and the first point will be equal to the last
point. Otherwise, the feature will be tagged
as a line. Default is 360.
Yes
<centerX> real value The X coordinate of the center of the ellipse.
If not specified then the first coordinate of the
feature is used.
Yes
<centerY> real value The Y coordinate of the center of the ellipse.
If not specified then the first coordinate of the
feature is used.
Yes
@Arc FME FUNCTION REFERENCE
A-8 FME Reference Manual Version 2.0
Figure A-1 Sample Arc
A.4.1 Configuration
This function does not accept configuration lines.
A.4.2 Description
This function is often used when translating from formats supporting arcs and ellipses
to those that do not by vectorizing such features.
This function replaces the geometry of the passed in feature with an arc, generated
according to the parameters passed in. If the sweep angle of the arc is 360 degrees,
then the resulting feature will be a closed polygon, shaped like an ellipse. Otherwise,
the resulting geometry of the feature will be a line.
If the number of edges is 0, then the FME will calculate the number of edges to create
by dividing the sweep_angle by the setting of the mapping file directive
FME_ARC_DEGREES_PER_EDGE (which by default is 5). In addition, if the
mapping file contains a setting for FME_ARC_EDGE_TOLERANCE, the generated
line will be thinned to remove points that do no deviate more than this tolerance from
the line connecting their neighbours. In this way, excessively large numbers of
coordinate volumes are avoided when converting arcs into linestrings.
Secondary
Axis
Rotation = 90
Start
Angle
= 45
Sweep
Angle
= 135
Primary
Axis
A-9 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Arc
A.4.3 Inverse Operation
The function has no inverse.
A.4.4 Example
In the example below, design file arc features are changed to 50 segment lines and
ellipse features are changed to 50 segment polygons as they are translated into shape
files.
IGDS * igds_type igds_arc \
igds_primary_axis %primary \
igds_secondary_axis %secondary \
igds_rotation %rotation \
igds_start_angle %start \
igds_sweep_angle %sweep
SHAPE arcs \
@Arc(%primary,%secondary,50,%rotation,%start,%sweep)
IGDS * igds_type igds_ellipse \
igds_primary_axis %primary \
igds_secondary_axis %secondary \
igds_rotation %rotation
SHAPE ellipses \
@Arc(%primary,%secondary,50,%rotation)
TIP: Since @Arc has no inverse, the above set of transfer specifications cannot be used to translate back from
shape files to a design file.
@Area FME FUNCTION REFERENCE
A-10 FME Reference Manual Version 2.0
A.5 @Area
@Area( [<multiplier>] )
FUNCTION TYPE: ATTRIBUTE
ARGUMENTS:
A.5.1 Configuration
This function does not accept configuration lines.
A.5.2 Description
The @Area function calculates the area of a polygonal feature. The function correctly
handles both polygonal features and polygonal features with holes. For point and
linear features, 0 is returned. The optional multiplier can be used to convert the return
value from ground units squared to units more useful to the caller.
A.5.3 Inverse Operation
The function has no inverse.
A.5.4 Example
In the example below, the SHAPE area attribute is set to the area of the SAIF Lake
polygon object when features are translated from SAIF to SHAPE. The units are
converted from square meters to hectares via the use of the 0.0001 multiplication
factor. When features are translated from SHAPE to SAIF, the @Area call has no
effect.
SHAPE lake area @Area(0.0001)
SAIF Lake::MOF
Name Range Description Optional
<multiplier> real number By default, the area returned is in coordinate
units squared. The multiplier, if specified, can
be used to convert to other units. The default
is 1.
Yes
A-11 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Bounds
A.6 @Bounds
@Bounds(<xMinAttr>,<xMaxAttr>,<yMinAttr>,<yMaxAttr> /
[,<zMinAttr>,<zMaxAttr>]>
FUNCTION TYPE: FEATURE
ARGUMENTS:
A.6.1 Configuration
This function does not accept configuration lines.
A.6.2 Description
This function extracts the bounds of a feature. It determines the extreme values of the
feature in each of the x and y (and optionally z) axis, and assigns these values to the
attribute names passed in as arguments.
The zMinAttr and zMaxAttr are optional, and will be set to the minimum values
on the Z axis of the feature. If the feature had only two dimensions, both zMinAttr
and zMaxAttr will be set to 0.
Name Range Description Optional
<xMinAttr> string The name of the attribute which will be
assigned the minimum value of the feature
along the X axis.
No
<xMaxAttr> string The name of the attribute which will be
assigned the maximum value of the feature
along the X axis.
No
<yMinAttr> string The name of the attribute which will be
assigned the minimum value of the feature
along the Y axis.
No
<yMaxAttr> string The name of the attribute which will be
assigned the maximum value of the feature
along the Y axis.
No
<zMinAttr> string The name of the attribute which will be
assigned the minimum value of the feature
along the Z axis.
Yes
<zMaxAttr> string The name of the attribute which will be
assigned the maximum value of the feature
along the Z axis.
Yes
@Bounds FME FUNCTION REFERENCE
A-12 FME Reference Manual Version 2.0
A.6.3 Inverse Operation
This function has no inverse.
A.6.4 Example
In the example below, each feature is passed through a SamplingFactory. As each
feature enters the factory, it has six new attributes added to it, which hold the extents
of the feature.
FACTORY_DEF SDE SamplingFactory \
SAMPLE_RATE 1 \
INPUT FEATURE_TYPE * @Bounds(xmin,xmax,ymin,ymax,zmin,zmax)
If a feature had the coordinates (1,10,100), (2,-20,150), then after leaving the factory
it would have these new attributes with these values:
Attribute Value
xmin 1
xmax 2
ymin -20
ymax 10
zmin 100
zmax 150
A-13 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Circularity
A.7 @Circularity
@Circularity()
FUNCTION TYPE: ATTRIBUTE
ARGUMENTS: NONE
A.7.1 Configuration
This function does not accept configuration lines.
A.7.2 Description
This function is responsible for computing a circularity measure for the passed in
feature. The feature should be an area-based feature, though the function will return
a value which is not particularly meaningful for line and point features. For a point
feature, a value of 1 is returned. For a linear feature a value of 0 is returned.
The function computes how elongated a polygonal feature is. A value of 1 indicates
that the feature is a circle or a point feature if the number of coordinates are 1, and 0
indicates that it is a line.
TIP: This function is often combined with the TestFactory to select features for area generalization operations.
The measure returned is:
4 * PI * area / (perimeter * perimeter)
A.7.3 Inverse Operation
The function does nothing when invoked in the inverse direction.
A.7.4 Example
In the example below the circularity is stored as an attribute named circularity
when going from SHAPE to MIF. The function has no effect when invoked in the
opposite direction.
SHAPE lakes
MIF lakes circularity @Circularity()
@Close FME FUNCTION REFERENCE
A-14 FME Reference Manual Version 2.0
A.8 @Close
@Close()
FUNCTION TYPE: FEATURE
ARGUMENTS: NONE
A.8.1 Configuration
This function does not accept configuration lines.
A.8.2 Description
This function takes a feature with linear geometry and closes it by connecting the first
point with the last point. It is used to artificially close polygons with an edge missing.
For example, some datasets do not include the map neat line, so any areas abutting
the map edge are not closed. It is in these situations that @Close is useful.
WARNING: This function should be used with cautionin most
situations simply connecting the first point with the last
point will not produce a valid polygon.
If @Close is invoked on a feature that already is a polygon, it does nothing.
A.8.3 Inverse Operation
This function has no inverse.
A.8.4 Example
In the example below, the PolygonFactory is used to form polygons from the
LandCover boundaries present in a SAIF input file. Any boundaries that did not
close are output from the PolygonFactory according to the OUTPUT LINE clause in
A-15 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Close
the factory definition. The @Close function is invoked on each such unclosed linear
feature as it emerges from the factory, turning it into a polygon.
FACTORY_DEF SAIF PolygonFactory \
INPUT FEATURE_TYPE LandCover::TRIM \
position.geometry.Class OrientedArc \
GROUP_BY landCoverType \
OUTPUT LINE FEATURE_TYPE LandCover::TRIM \
position.geometry.Class Polygon \
@Close() \
OUTPUT POLYGON FEATURE_TYPE LandCover::TRIM \
position.geometry.Class Polygon
@Concatenate FME FUNCTION REFERENCE
A-16 FME Reference Manual Version 2.0
A.9 @Concatenate
@Concatenate([<string>]+)
FUNCTION TYPE: ATTRIBUTE
ARGUMENTS:
A.9.1 Configuration
This function does not accept configuration lines.
A.9.2 Description
This function concatenates together its parameters and returns the result as a single
string.
It is similar to the inverse of the @Split function. @Split is useful in transfer
specifications where an inverse is required. @Concatenate is convenient in
conjunction with factories when no inverse is needed.
A.9.3 Inverse Operation
This function has no inverse.
A.9.4 Example
In the example below, the values of the street and city attributes are joined
together (with a dash between them) and assigned to the address attribute.
FACTORY_DEF SHAPE SamplingFactory \
INPUT FEATURE_TYPE Building \
address @Concatenate(&street, - ,&city) \
SAMPLE_RATE 1
Name Range Description Optional
<string> any string All strings passed in will be joined together to
form a single, composite string, which is
returned.
No
A-17 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @ConvertBase
A.10 @ConvertBase
@ConvertBase(<value>,<originalBase>,<destBase> \
[,<outputWidth>])
FUNCTION TYPE: ATTRIBUTE
ARGUMENTS:
A.10.1 Configuration
This function does not accept configuration lines.
A.10.2 Description
This function converts a value expressed in one base to another, and returns the result.
It does NOT handle fractions (i.e., a decimal point) currently only UNSIGNED
integer numbers are supported. Any base from base 2 (binary) to base 36 is supported.
Digits are chosen from the set:
0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ
Any lower case digits are converted to upper case by the function automatically. An
optional output width may also be specified. If the converted value has fewer digits
than the width, then it is padded on the left with 0s to fill out the width. If the
converted value has more digits than the width nothing is done.
a. Use only the first <originalBase> characters from the set
0123456789 ABCDEFGHIJKLMNOPQRSTUVWXYZ
Name Range Description Optional
<value> string
a
The string representation of the number to be
converted from the <originalBase> to
the <destBast>. The number will be
expressed in <originalBase> notation,
which means it will use only the first
<originalBase> characters from the set
as its digits.
No
<original
Base>
2..36 The base of the <value> parameter. No
<destBase> 2..36 The base to which the value will be converted. No
<output
Width>
<decimal number> The desired number of digits in the output
number. The output number will be padded on
the left with zeros to fill it out to the desired
width. If the output number has more digits
before padding that the width, it is not
trimmed but is returned untouched.
Yes
@ConvertBase FME FUNCTION REFERENCE
A-18 FME Reference Manual Version 2.0
TIP: @ConvertBase does not supported signed values. At present, only unsigned values are converted.
A.10.3 Inverse
The inverse of this function does the reverse base conversion from the specified
<destBase> to the <originalBase>. No padding is done in this case.
A.10.4 Example
The following call to @ConvertBase converts the number 255 from decimal to
hexadecimal:
@ConvertBase(255,10,16)
and would return the value FF.
This call does the same thing, but pads the result to four digits:
@ConvertBase(255,10,16,4)
and would return the value 00FF.
More commonly however, @ConvertBase will operate on the value of an attribute
rather than on a hard coded constant. In this example, the 32 digit hex string returned
by the @GOID (Geographic Object IDentifier) function is split into four eight-digit
hex numbers, which are then each converted to decimal and assigned to attributes.
# First compute the GOID, assigning it to the hexGoid attribute.
# Then split the hexGoid into four eight-digit strings
FACTORY_DEF SAIF TeeFactory \
INPUT FEATURE_TYPE * \
OUTPUT FEATURE_TYPE * hexGoid @Goid() \
@Split(&hexGoid,4s4s4s4s,hexPt1,hexPt2,hexP t3,hexPt4)
# Now convert the four eight-digit hex strings into their decimal
# equivalent
FACTORY_DEF SAIF TeeFactory \
INPUT FEATURE_TYPE * \
OUTPUT FEATURE_TYPE *int1 @ConvertBase(&hexPt1,16,10) \
int2 @ConvertBase(&hexPt2,16,10) \
int3 @ConvertBase(&hexPt3,16,10) \
int4 @ConvertBase(&hexPt4,16,10)
After leaving these two factories, each feature will have four unsigned integer
attributes available to be stored in 32 bit unsigned integers in the output format.
A-19 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @ConvertToArc
A.11 @ConvertToArc
@ConvertToArc (<primaryRadiusAttrName>, \
<secondaryRadiusAttrName>, \
<startAngleAttrName>, \
<sweepAngleAttrName>)
FUNCTION TYPE: FEATURE
ARGUMENTS:
A.11.1 Configuration
This function does not accept configuration lines.
A.11.2 Description
This function calculates the center point, radius, start angle, and sweep angle of a
circular arc that starts at the first point of the line passed in, ends at the second, and
passes through the middle point (where middle is the (n/2)th point in the line, not
the geometrically middle point). It sets attributes on the feature to hold the radius,
start, and sweep angle, and sets the geometry of the feature to be a single point that is
the center point of the circle.
If this function is called on a feature with less than 3 points, it will abort the
translation. If this function is called on a feature with exactly 3 points, the arc will be
guaranteed to pass through all of them. If it is called on a feature with more than 3
a. In the current version of the FME, only circular arcs are generated and therefore the
primary and secondary radii will always be the same.
Name Range Description Optional
<primary
RadiusAttr
Name>
string The name of the attribute that will be set to the
radius of the arc along the primary axis.
No
<secondary
RadiusAttr
Name>
string The name of the attribute that will be set to the
radius of the arc along the secondary axis.
a
No
<startAngle
AttrName>
string The name of the attribute that will be set to the
angle of the arc, as measured
counterclockwise from horizontal.
No
<sweepAngle
AttrName>
string The name of the attribute that will be set to the
sweep, or duration, of the arc. This will
always be a positive value and is
counterclockwise from the starting angle.
No
@ConvertToArc FME FUNCTION REFERENCE
A-20 FME Reference Manual Version 2.0
points, the arc will approximate the curve and will be guaranteed to pass through the
first, last, and middle point only.
A.11.3 Inverse
When called on the source line of a transfer specification, in the inverse direction, this
function will convert a point feature into a linestring which approximates an arc
defined by the values of the parameter names passed to it. See the documentation for
@Arc, Section A.2, for details.
A.11.4 Example 1
Given a feature containing these points:
2,1
1,2
0,
a call to:
@ConvertToArc(p_radius,s_radius,startAng,sweepAng)
would turn the feature into a point feature with this geometry:
0,0
and these attributes:
p_radius
s_radius
startAng 30
sweepAng 60
A.11.5 Example 2
When arc features are reprojected, the FME automatically converts them into
linestrings. However, sometimes there is a requirement to maintain the features as
arcs, even after they have been reprojected.
The below sampling factory provides the solution for such a case. It accepts only arc
features read in from an input design (IGDS) file.
As each feature enters the factory, it is first reprojected. This will turn the feature into
a line string. Then the feature is turned back into an arc using @ConvertToArc.
FACTORY_DEF MIF SamplingFactory \
SAMPLE_RATE 1 \
INPUT FEATURE_TYPE * igds_type igds_arc \
5
5
5
A-21 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @ConvertToArc
@Reproject(UTM10-27,UTM10-83) \
@ConvertToArc(igds_primary_axis, \
igds_secondary_axis, \
igds_start_angle, \
igds_sweep_angle)
@ConvertToLine FME FUNCTION REFERENCE
A-22 FME Reference Manual Version 2.0
A.12 @ConvertToLine
@ConvertToLine(<tolerance>)
FUNCTION TYPE: FEATURE
ARGUMENTS:
A.12.1 Configuration
This function does not accept configuration lines.
A.12.2 Description
This function replaces the geometry of the passed in feature with a line. The line is
generated by threading through the center of the polygonal shape. If non-area features
are passed to this function, no changes to them are made (though they are logged with
a warning). The function also takes a single parameter the tolerance. Lines
generated will have points that are no closer than this distance apart.
This function, when combined with the TestFactory, enables the FME to perform
area generalization operations.
A.12.3 Inverse Operation
This function has no inverse.
A.12.4 Example
In the example below, polygonal RoadAllowance features with areas less than
1000 square ground units and a circularity measure less than 0.5 are converted from
polygons to lines. All other RoadAllowance features are untouched. Note the use
of the @Evaluate and @Circularity functions to perform the test.
FACTORY_DEF SHAPE TestFactory \
INPUT FEATURE_TYPE RoadAllowance \
TEST @Evaluate((@Area() < 1000) && \
(@Circularity() < 0.5)) = 1 \
Name Range Description Optional
<tolerance> Any real number
greater than 0
The tolerance which defines the point density
on the resulting line. The resulting lines will
not have points closer than the specified
tolerance.
No
A-23 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @ConvertToLine
OUTPUT PASSED FEATURE_TYPE RoadLine \
@ConvertToLine(10) \
OUTPUT FAILED FEATURE_TYPE RoadAllowance
@ConvertToPoint FME FUNCTION REFERENCE
A-24 FME Reference Manual Version 2.0
A.13 @ConvertToPoint
@ConvertToPoint()
FUNCTION TYPE: FEATURE
ARGUMENTS: NONE.
A.13.1 Configuration
This function does not accept configuration lines.
A.13.2 Description
This function replaces the geometry of the passed in feature with a point. The point
is defined to be the center of the bounding box of the feature.
A.13.3 Inverse Operation
This function when combined with the TestFactory enables the FME to perform area
generalization operations.
This function has no inverse.
A.13.4 Example
In the example below, polygonal Building features with areas less than 1000
square ground units are converted from polygons to lines, and features larger than this
are untouched.
FACTORY_DEF SHAPE TestFactory \
INPUT FEATURE_TYPE Building \
TEST @Area() < 1000 \
OUTPUT PASSED FEATURE_TYPE BuildingPoint \
@ConvertToPoint() \
OUTPUT FAILED FEATURE_TYPE Building
A-25 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Coordinate
A.14 @Coordinate
@Coordinate((x|y|z),<index>)
FUNCTION TYPE: ATTRIBUTE
ARGUMENTS:
A.14.1 Configuration
This functions does not accept configuration lines.
A.14.2 Description
This function returns the value of a single coordinate of a feature.
If the feature is two dimensional, and a request is made for a value on the third axis,
zero will be returned.
If the index given is out of range, then an exception will be raised and the translation
will abort.
A.14.3 Inverse
This function has no inverse.
A.14.4 Example
In the example below, the x, y, and z coordinates for the first and last points in the
feature are extracted and stored in the attributes xFirst, yFirst, zFirst,
xLast, yLast, and zLast.
These attributes may then be used in further calculations.
Name Range Description Optional
<axis> (x|y|z) The first parameter controls the axis from
which the coordinate value will be taken.
No
<index> 0..
<@NumCoords
() - 1>
The second parameter control which value
along the axis will be returned. The first
vertex is given the index 0, and the last vertex
is at index position
@NumCoords() - 1.
No
@Coordinate FME FUNCTION REFERENCE
A-26 FME Reference Manual Version 2.0
A TestFactory is used to separate single points from multi-point lines.
FACTORY_DEF SAIF TestFactory \
INPUT FEATURE_TYPE * \
TEST @NumCoords > 1 \
OUTPUT PASSED FEATURE_TYPE * \
xFirst @Coordinate(x,0) \
yFirst @Coordinate(y,0) \
zFirst @Coordinate(z,0) \
xLast @Coordinate(x,@Evalute(@NumCoords() - 1))\
yLast @Coordinate(y,@Evalute(@NumCoords() - 1))\
zLast @Coordinate(z,@Evalute(@NumCoords() - 1))\
OUTPUT FAILED FEATURE_TYPE * \
xOnly @Coordinate(x,0) \
yOnly @Coordinate(y,0) \
zOnly @Coordinate(z,0)
If the feature had the coordinates (1,10,100), (2,-20,150), (3,50,125) then after
leaving the factory the feature would have these new attributes with these values:
Attribute Value
xFirst 1
yFirst 10
zFirst 100
xLast 3
yLast 50
zLast 125
A-27 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @CoordSys
A.15 @CoordSys
@CoordSys()
FUNCTION TYPE: ATTRIBUTE
ARGUMENTS: NONE
A.15.1 Configuration
This function does not accept configuration lines.
A.15.2 Description
This function returns the name of the coordinate system in which this features
coordinates are measured. If it returns a blank, then it means that no coordinate
system has been set for the feature data. If a coordinate system definition is created
automatically by the FME from parameters read from an input data source, its name
will begin with an _.
The FME may define coordinate systems automatically. It is possible that there may
be two different names for exactly the same coordinate system definition. The result
returned by @CoordSys should not be used in a comparison with a hardcoded
coordinate system name, since coordinate system names may be different but may be
structurally equivalent.
A.15.3 Inverse Operation
The function performs the same operation in the inverse direction.
A.15.4 Example
In the example below the feature coordinate system name is stored within the attribute
named coordSys.
SHAPE lake
MIF lake coordSys @CoordSys()
@Count FME FUNCTION REFERENCE
A-28 FME Reference Manual Version 2.0
A.16 @Count
@Count( [<domain>[,<startVal>[,<modulo>]]] )
FUNCTION TYPE: ATTRIBUTE OR FEATURE
ARGUMENTS:
A.16.1 Configuration
This function does not accept configuration lines.
A.16.2 Description
This function provides a mechanism for generating unique numbers and assigning
them to feature attributes during a translation. Because it outputs the final counts in
each of the domains to the log file, it can also be used as a feature function to count
features which matched the correlation lines. In this case, the logfile records the total
number of times that the function was invoked, even though its result was not stored
in any attribute.
The optional domain parameter can be used to have several different counters active
during a single translation. For example, unique line numbers starting at 0 can be
assigned to all lines by invoking @Count(lineCounter). During the same run,
unique polygon numbers starting at 0 can be assigned to all polygons by using
@Count(polygonCounter).
If no domain name is specified, then the default domain is assumed.
The optional startVal parameter enables the user to specify a value in which to
start the counter. This is useful for applications in which ranges of values have
meanings in the problem domain.
Name Range Description Optional
<domain> Any string A counter name. Each time @Count is invoked,
it returns and increments the count associated
with the domain name. This allows many
different counters to be used during a single
translation. If this parameter is not specified, the
default domain is assumed.
Yes
<startVal> Any Integer The starting value of the counter. The counter is
then incremented from the start value.
Yes
<modulo> Any Integer The modulo value of the counter. The counter
returns a value between zero and <modulo> - 1.
A-29 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Count
The optional modulo parameter enables a counter to be created which cycles from
0 to modulo - 1. This is useful for using counters as lookup values with the
@Lookup function.
A.16.3 Inverse Operation
This function works identically in both the forward and reverse directions.
A.16.4 Example
In the example below, when translating from IGDS to SHAPE, each line output to the
shape file has a unique number assigned to its LINENUM attribute. At the end of the
run, the logfile contains the number of times @Count() was invoked. Note that in
this case the default count domain is used.
SHAPE lines LINENUM @Count()
IGDS 42 igds_type igds_line
@Dimension FME FUNCTION REFERENCE
A-30 FME Reference Manual Version 2.0
A.17 @Dimension
@Dimension()
FUNCTION TYPE: ATTRIBUTE
ARGUMENTS: NONE
A.17.1 Configuration
This function does not accept configuration lines.
A.17.2 Description
This function returns the dimension of the feature. In the current version of the FME,
2 or 3 will be returned.
A.17.3 Inverse Operation
The function performs the same operation in the inverse direction.
A.17.4 Example
In the example below the feature dimension is stored within the attribute named
dimension.
SHAPE lake
MIF lake dimension @Dimension()
A-31 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Evaluate
A.18 @Evaluate
@Evaluate(<expression>)
FUNCTION TYPE: ATTRIBUTE
ARGUMENTS:
A.18.1 Configuration
This function does not accept configuration lines.
A.18.2 Description
This function evaluates an arithmetic expression and returns the result. The operators
permitted in the expressions to be evaluated are a subset of the operators permitted in
C expressions, and they have the same meaning and precedence as the corresponding
C operators.
TIP: If the expression contains spaces or nested parenthesis, it should be placed in quotes.
Expressions almost always yield numeric results (integer or floating-point values).
For example, the expression:
@Evaluate(8.2 + 6)
evaluates to 14.2.
@Evaluate is based on the Tool Command Language (TCL) expr command, as is
the documentation below. TCL and its documentation is copyrighted by the Regents
of the University of California, Sun Microsystems, Inc., and other parties. However,
the TCL authors have granted permission to any party to reuse and modify the code
and documentation, provided the original copyright holders are acknowledged.
A.18.3 Operands
An expression consists of a combination of operands, operators, and parentheses.
White space may be used between the operands and operators and parentheses; it is
ignored by the expression processor. Where possible, operands are interpreted as
Name Range Description Optional
<expression> Any valid
expression
(see below)
The expression may contain any of the
below operators, feature variable references
(using the value-of operator &), transfer
variables, or calls to other functions.
No
@Evaluate FME FUNCTION REFERENCE
A-32 FME Reference Manual Version 2.0
integer values. Integer values may be specified in decimal (the normal case), in octal
(if the first character of the operand is 0), or in hexadecimal (if the first two characters
of the operand are 0x). If an operand does not have one of the integer formats given
above, then it is treated as a floating-point number if that is possible. Floating-point
numbers may be specified in any of the ways accepted by an ANSI-compliant C
compiler (except that the f, F, l, and L suffixes will not be permitted in most
installations). For example, all of the following are valid floating-point numbers: 2.1,
3., 6e4, 7.91e+16. If no numeric interpretation is possible, then an operand is left as
a string (and only a limited set of operators may be applied to it).
Operands may be specified in any of the following ways:
As an numeric value, either integer or floating-point.
As a value of an attribute, using standard & notation. The attribute's value will
be used as the operand.
As an FME feature function, such as @Area(). The function will be evaluated,
an the result used as the operand.
As a mathematical function whose arguments have any of the above forms for
operands, such as sin(&x). See below for a list of defined mathematical
functions.
A.18.4 Operators
The valid operators are listed below, grouped in decreasing order of precedence:
Operator Description
- + ~ ! Unary minus, unary plus, bit-wise NOT, logical NOT. None
of these operands may be applied to string operands, and
bit-wise NOT may be applied only to integers.
* / % Multiply, divide, remainder. None of these operands may be
applied to string operands, and remainder may be applied
only to integers. The remainder will always have the same
sign as the divisor and an absolute value smaller than the
divisor.
+ - Add and subtract. Valid for any numeric operands.
<< >> Left and right shift. Valid for integer operands only.
< > <= >= Boolean less, greater, less than or equal, and greater than or
equal. Each operator produces 1 if the condition is true, 0
otherwise. These operators may be applied to strings as well
as numeric operands, in which case string comparison is
used.
A-33 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Evaluate
See the C Manual for more details on the results produced by each operator. All of
the binary operators group left-to-right within the same precedence level. For
example, the expression:
@Evaluate(4*2 < 7)
returns 0.
A.18.5 Math Functions
@Evaluate supports the following mathematical functions in expressions:
== != Boolean equal and not equal. Each operator produces a
zero/one result. Valid for all operand types.
& Bit-wise AND. Valid for integer operands only.
^ Bit-wise exclusive OR. Valid for integer operands only.
| Bit-wise OR. Valid for integer operands only.
&& Logical AND. Produces a 1 result if both operands are non-
zero, 0 otherwise. Valid for numeric operands only
(integers or floating-point).
|| Logical OR. Produces a 0 result if both operands are zero, 1
otherwise. Valid for numeric operands only (integers or
floating-point).
x?y:z If-then-else, as in C. If x evaluates to non-zero, then the
result is the value of y. Otherwise the result is the value of
z. The x operand must have a numeric value.
- + ~ ! Unary minus, unary plus, bit-wise NOT, logical NOT. None
of these operands may be applied to string operands, and
bit-wise NOT may be applied only to integers.
* / % Multiply, divide, remainder. None of these operands may be
applied to string operands, and remainder may be applied
only to integers. The remainder will always have the same
sign as the divisor and an absolute value smaller than the
divisor.
acos cos hypot sinh asin
cosh log sqrt atan exp
log10 tan atan2 floor pow
tanh ceil fmod sin
Operator Description
@Evaluate FME FUNCTION REFERENCE
A-34 FME Reference Manual Version 2.0
Each of these functions invokes the C math library function of the same name; see the
C manual entries for the library functions for details on what they do. @Evaluate
also implements the following functions for conversion between integers and
floating-point numbers:
A.18.6 Types, Overflows, Precision
All internal computations involving integers are done with the C type long, and all
internal computations involving floating-point are done with the C type double.
When converting a string to floating-point, exponent overflow is detected and results
in an error. For conversion to integer from string, detection of overflow depends on
the behavior of some routines in the local C library, so it should be regarded as
unreliable. In any case, integer overflow and underflow are generally not detected
reliably for intermediate results. Floating-point overflow and underflow are detected
to the degree supported by the hardware, which is generally pretty reliable.
Conversion among internal representations for integer, floating-point, and string
operands is done automatically as needed. For arithmetic computations, integers are
used until some floating-point number is introduced, after which floating-point is
used. For example,
@Evaluate(5 / 4)
returns 1, while
@Evaluate(5 / 4.0)
@Evaluate(5 / ( 4 + 0.0 ))
both return 1.25. Floating-point values are always returned with a . or an e so that
they will not look like integer values. For example,
@Evaluate(20.0/5.0)
rcturns 4.0', not 4.
Seventeen digits of precision are always used for floating point calculations.
Function Description
abs(arg) Returns the absolute value of arg. Arg may be either integer or floating-
point, and the result is returned in the same form.
double(arg) If arg is a floating value, returns arg, otherwise converts arg to floating and
returns the converted value.
int(arg) If arg is an integer value, returns arg, otherwise converts arg to integer by
truncation and returns the converted value.
round(arg) If arg is an integer value, returns arg, otherwise converts arg to integer by
rounding and returns the converted value.
A-35 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Evaluate
A.18.7 Inverse Operation
This function has no inverse.
A.18.8 Example
In the example below, @Evaluate is used to compute the ratio of the number of
rooms in a building to the number of stories. The result is used in a test by the
TestFactory to route the features to two different destinations based on the density of
rooms per floor in the building.
FACTORY_DEF SHAPE TestFactory \
INPUT FEATURE_TYPE Building \
TEST @Evaluate(&numRooms/&stories) < 10 \
OUTPUT PASSED FEATURE_TYPE SparseBuilding \
OUTPUT FAILED FEATURE_TYPE DenseBuilding
@FeatureType FME FUNCTION REFERENCE
A-36 FME Reference Manual Version 2.0
A.19 @FeatureType
@FeatureType( [<newType>] )
FUNCTION TYPE: ATTRIBUTE OR FEATURE
ARGUMENTS:
A.19.1 Configuration
This function does not accept configuration lines.
A.19.2 Description
This function is used as either an attribute value function or a feature function. When
used as a feature function, the optional newType parameter must be specified. In this
case, the @FeatureType function changes the feature type of the feature to the
specified value.
When used as an attribute value function, the newType parameter is not specified.
In this case, @FeatureType returns the feature type of the feature. This value is
then stored in an attribute.
This function is primarily used in conjunction with factories or the wildcard feature
type. On factory input lines, it may be used to store the feature type in an attribute for
use in a group-by clause. On a factory output line, the function may be used to set the
feature type of an output feature from one of its attributes.
When used with the wildcard feature type in a transfer specification, this function acts
as a feature function to either set the feature type (when invoked in the forward
direction), or to set a transfer variable to the type of the feature (when invoked in the
reverse direction).
TIP: The wildcard feature type matches all feature types and is denoted by an asterisk.
A.19.3 Inverse Operation
When encountered on the source line of a transfer specification, @FeatureType
does nothing if the optional newFeat parameter is not specified using a transfer
variable.
Name Range Description Optional
<newType> string A new feature type for the feature. Yes
A-37 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @FeatureType
However, when @FeatureType is called with a transfer variable on a source line
of a transfer specification, it will set the transfer variable to the feature type of the
feature.
A.19.4 Example
The example below shows how the wildcard feature type and the @FeatureType
function can be used to provide generic, no-value-added translation between IGDS
and SHAPE. In this example, all linear features, regardless of their original IGDS
feature type (level), get stored in the same Shape file. When the translation goes from
IGDS to SHAPE, the @FeatureType(%level) is run in the inverse direction,
assigning the feature type of the current feature to the %level variable. This
variable is then assigned to the LEVEL field of the output SHAPE linear feature.
When translation goes from SHAPE to IGDS, the @FeatureType(%level) is
run in the forward direction, and assigns the value in the %level variable to the
feature type of the current feature. In the IGDS case, the feature type will be
interpreted as the level when the feature is output.
SHAPE igdsline LEVEL %level COLOR %color STYLE %style
IGDS * igds_type igds_line igds_color %color \
igds_style %style \
@FeatureType(%level)
@Force2D FME FUNCTION REFERENCE
A-38 FME Reference Manual Version 2.0
A.20 @Force2D
@Force2D()
FUNCTION TYPE: ATTRIBUTE
ARGUMENTS: NONE
A.20.1 Configuration
This function does not accept configuration lines.
A.20.2 Description
This function forces the feature to be 2 dimensional and returns the original
dimensionality of the feature. If the input feature was 3D then the z dimension is
dropped. If the input feature is 2D then the feature is untouched.
TIP: @Force2D is useful when outputting data to a format such as AutoCAD files since many AutoCAD
compatible products cannot process 3D files.
A.20.3 Inverse Operation
The function performs the same operation in the inverse direction.
A.20.4 Example
In the example below a SamplingFactory is used with the Force2D function to
convert all input features to 2D. The SamplingFactory uses a sample rate of 1, which
means it will pass every feature through it.
FACTORY_DEF IGDS SamplingFactory \
INPUT FEATURE_TYPE * @Force2D() \
SAMPLE_RATE 1
A-39 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Generalize
A.21 @Generalize
@Generalize(Deveau,<tolerance>,<numWedges>,<angle>)
@Generalize(Douglas,<tolerance>)
FUNCTION TYPE: FEATURE
ARGUMENTS:
A.21.1 Configuration
This function does not accept configuration lines.
A.21.2 Description
The @Generalize function modifies a features geometry by removing its points.
Two algorithms are available for the point thinning. The Douglas algorithm takes
only a <tolerance> parameter to the amount of point thinning performed. The
Douglas algorithm removes points from the original line, but does not adjust the
location of the remaining points.
Name Range Description Optional
<tolerance> > 0 The tolerance used for point thinning. For the
Douglas algorithm, points which are less than the
tolerance from the surrounding line segment are
removed. The result is that all the points of the
original segment will be within a band of width
<tolerance> centered around the resulting line.
For the Deveau algorithm, points are kept only
when no band of width <tolerance> can be found
which contains both the original points and the
resulting line. The band is allowed to float,
resulting in a smoother result.
No
<numWedges> 1..30 For the Deveau algorithm, this controls the
number of simultaneous wedges considered
when forming floating bands around the points in
the set. When <numWedges> is 1, the Deveau
algorithm functions in the same way as the
Douglas algorithm. The larger this value is, the
more aggressive the generalization will be, and
the smoother the resulting line.
No
<angle> Between
0 and 180
This parameter sets the sharpness tolerance for
spikes that will be blunted.Vertex points at angles
less than <angle> from the previous two points
will not be moved. The angle is measured in
degrees. A value of 110 is recommended.
No
@Generalize FME FUNCTION REFERENCE
A-40 FME Reference Manual Version 2.0
TIP: The Generalize function logs statistics about the number of points it removed using each algorithm to the
logfile.
The Douglas algorithm is described in the following publication:
David H. Douglas and Thomas K. Peuker, Algorithms for the
Reduction of the Number of Points Required to Represent a Digitized
Line or Its Caricature, CANADIAN CARTOGRAPHER, Vol. 10, No.
2, December, 1973, pp. 112-122.
The Deveau algorithm both removes points and adjusts the locations of the points
which remain, resulting in a smoother generalization. In addition to the
<tolerance> parameter, the Deveau algorithm also takes <numWedges> and
<angle> parameters to control the generalization. These parameters must be tuned
for particular applications to produce aesthetically pleasing results. The Deveau
algorithm is fully described in the AutoCarto VII proceedings in the paper Reducing
the Number of Points in a Plane Curve Representation by Terry J. Deveau.
The @Generalize functions logs statistics about the number of points it removed
to the logfile.
A.21.3 Inverse Operation
This function has no inverse, and is ignored when on the source side of a
transformation specification.
A.21.4 Example
In the example below, SAIF road features are generalized before being output to a
Shape file. The Douglas algorithm is used to do the generalization.
SAIF Road::TRIM numberOfLanes %num paved %pavedFlag
SHAPE road NUMLANES %num PAVED %pavedFlag \
@Generalize(Douglas,50)
A-41 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @GeneratePoint
A.22 @GeneratePoint
@GeneratePoint()
FUNCTION TYPE: FEATURE
ARGUMENTS: NONE
A.22.1 Configuration
This function does not accept configuration lines.
A.22.2 Description
This function generates a point inside a polygon or donut polygon feature. The
generated point is added to the features in-memory representation. The feature then
becomes a point-in-polygon (PIP) feature. When generating a point for a 3
dimensional feature the z coordinate is set to the average Z value of the input feature.
This function can be used when translating data from model where polygons are
directly attached to a model where polygonal areas are implied by boundary lines and
the attribution for each area is attached to a point within that area.
A.22.3 Inverse Operation
This function has no inverse.
A.22.4 Example
In the example below, polygonal data with attached attribution is read from a Shape
file, but the attribution is to be attached to point features output to an IGDS dataset.
To perform the split, the Shape polygons are input to the PIPComponentsFactory,
and as they are input, @GeneratePoint is used to attach a point to them. This
generated point is then output by itself, along with all the attributes, by the OUTPUT
POINT clause of the factory. (Note that in this case, since no OUTPUT POLYGON
clause is present, the polygons themselves are discarded.)
FACTORY_DEF SHAPE PIPComponentsFactory \
INPUT FEATURE_TYPE polys @GeneratePoint() \
OUTPUT POINT FEATURE_TYPE points
@GOID FME FUNCTION REFERENCE
A-42 FME Reference Manual Version 2.0
A.23 @GOID
@GOID()
@GOID(VERIFY,<goid>)
FUNCTION TYPE: ATTRIBUTE
ARGUMENTS:
A.23.1 Configuration
This function does not accept configuration lines.
A.23.2 Description
This function calculates a Geographic Object IDentifier (GOID) for the feature it is
given, according to the GOID specification developed by Geographic Data BC
attached below.
The GOID is a unique 128-bit number which incorporates the position of a feature
with other numbers. The result is a unique value which may be attached to the feature
to distinguish it from any other feature.
The first form of @GOID takes no parameters. In this case, it calculates a GOID for
the feature, according the specification below, and returns it as 32 hex digits.
There are two forms of the GOID function, determined by the number of parameters
given:
Form 1: @GOID()
This form returns a 128 bit GOID for the feature as 32 hex digits in an ASCII
String. The first 16 characters correspond to the position, the next 10 to the time,
the next 4 to the sequence number, and the final 2 to the checksum. This form
operates as an attribute function, in that it returns a string.
For example, when @GOID was called on a point feature at position (-127,49)
as measured in latitude and longitude on January 23, 1997 at 10:39:26 AM PST,
it returned the value:
Name Range Description Optional
<goid> 32 digit
hexadecimal
number
This parameter is used in the second form of
@GOID, which is used to verify that a goid is
valid. The checksum of the <goid> is
validated.
No
(second form
only)
A-43 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @GOID
47B21A71B1BCC00013E280E5140000B1
TIP: For @GOID to generate a GOID, the coordinate system of the feature must be known. To ensure
this, either the @Reproject() must be called on the feature prior to calling @GOID, or the
coordinate system of the input source of the features must be known by the FME.
Form 2: @GOID(VERIFY, <goidValue>)
This form verifies that the goidValue (expressed as a string of 32 hex digits)
is valid. The verification is done by ensuring that checksum of the GOID is
correct, according the specification below. 1 is returned if the GOID checks out,
0 otherwise.
A.23.3 Inverse
This function has no inverse and does nothing if invoked on the source line of a
transfer specification.
A.23.4 Formal Specification
The GOID is composed of four parts and are described below, with the first part
(PART A) corresponding to the left-most 64 bits, the second part (PART B) the next 40
bits, the third part (PART C) the following 16 bits, and the last part (PART D) the right-
most 8 bits.
PART A:
Sixty-four bits are derived from bit interleaving binary representations of the latitude
and longitude values. They are first expressed as double-precision floats. Next the
latitude and longitude are each multiplied by 107. Each is then converted to a signed,
four-byte (32-bit) integer. Negative values are handled by two $s complement
encoding. The interleaving proceeds, from left to right, beginning with the left-most
bit of the latitude, and then the left-most bit of the longitude. Thus, from left to right,
the odd-numbered bits of Part A of the GOID are from the binary form of the latitude,
and the even-numbered bits are from the binary form of the longitude.
The GOID provides approximately 1.1 cm precision at the equator for both
coordinates. In British Columbia, the precision of the latitude and longitude are
approximately 1.1 cm and better than 0.4 cm, respectively, for a given point defined
as:
(i) the position of the object, if its geometry is a point, or
(ii) the weighted average of the first two points encountered in the objects
geometric description. In the case of an area feature, the two points come from
@GOID FME FUNCTION REFERENCE
A-44 FME Reference Manual Version 2.0
the outer boundary, as measured in a counter-clockwise (left-hand) fashion. The
first point has double the weight of the second point to distinguish the traversal
direction along the line segment. That is, for both the x and y coordinates:
new_coordinate = ((2*coordinate_first_point) +
coordinate_second_point)/ 3
PART B:
Forty bits represent time as measured in hundredths of a second, as read from the
computers clock. The time is measured with respect to Universal Coordinated Time
(UTC), also known as Greenwich Mean Time (GMT), with a zero time of
00h00m00s, January 1, 1970, but unadjusted for leap seconds.
PART C:
Sixteen bits are used as an arbitrary sequence number, to avoid the possibility of two
objects at the same place being defined in the same hundredth of a second. The
sequence number is reset to zero with each FME run.
PART D:
Eight bits are used as a check-sum. For the purpose of this (PART D) calculation only,
the highest four bits, bits 0 through 3, are moved to become bits 116 through 119; that
is, the first (i.e., left-most) hexadecimal digit becomes the 30th hexadecimal digit.
The 128 bits are then treated as 16 consecutive, one-byte unsigned integers. The last
integer is adjusted such that the sum of the 16 integers is 0, modulo 256. This rotation
of the first hex digit minimizes the chance that a four, 32-bit integer representation of
the GOID could have the position of the integers altered or reversed in some way and
remain undetected.
A.23.5 Encoding
There are two representations of the GOID: as a character string of 32 hexadecimal
digits, and as four unsigned, 32-bit integers.
1. The character string is defined from left to right, for PARTS A through D,
respectively. For each part, the left-most character is treated as the most
significant. This ensures that for PART A the correspondence between the
hexadecimal and binary representations is direct.
2. Conversion from the ASCII representation to four 32-bit base-10 integers shall
proceed from left to right. (The left-most 8 characters define the first integer,
etc. Also, the left-most character (in each group of 8 characters) represents n *
167, the next represents m * 166, and so forth for the remaining characters.
A-45 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @GOID
A.23.6 Example 1
In this example, each feature read from the input stream is assigned a GOID. The
GOID is placed in the goidString attribute, and can be further manipulated by the
FME, or transferred to the output format to be stored with the feature.
FACTORY_DEF ARCGEN TeeFactory \
INPUT FEATURE_TYPE * \
OUTPUT FEATURE_TYPE * goidString @GOID()
A.23.7 Example 2
Some implementations may store and retrieve GOIDs as 32 bit unsigned integers. To
use this GOIDs under these circumstances, a means of converting between the 32 bit
unsigned integers and the 32 hex digits of the GOID is needed. The @ConvertBase
function, combined with @Split and @Concatenate, provides the solution.
Case 1: Storing a newly computed GOID as 4 integers.
Step 1: Compute the GOID and assign it to an attribute
Step 2: Split the GOID into 4 - 8 hex digit pieces, assigning these to 4
attributes
Step 3: Use @ConvertBase to convert the 4 - 8 hex digit pieces to
unsigned integers. (See Section A.10, @ConvertBase for details.)
This can be done in two factory steps with:
FACTORY_DEF SAIF TeeFactory \
INPUT FEATURE_TYPE * \
OUTPUT FEATURE_TYPE *hexGoid @Goid() \
@Split(&hexGoid,4s4s4s4s,hexPt1,
hexPt2,hexPt3,hexPt4)
FACTORY_DEF SAIF TeeFactory \
INPUT FEATURE_TYPE * \
OUTPUT FEATURE_TYPE *int1 @ConvertBase(&hexPt1,16,10) \
int2 @ConvertBase(&hexPt2,16,10) \
int3 @ConvertBase(&hexPt3,16,10) \
int4 @ConvertBase(&hexPt4,16,10)
Case 2: Retrieve a GOID stored as 4 integers, and covert into the hex string.
Step 1: Convert each integer into hex. The example below assumes the
integers were read from the input format in the attribute names
<int1>, <int2>, <int3>, and <int4>.
Step 2: Concatenate them all together into the 32 bit string.
Step 3: Validate the result (if you want) with the @GOID function.
@GOID FME FUNCTION REFERENCE
A-46 FME Reference Manual Version 2.0
This can all be done in one factory with:
FACTORY_DEF IGDS TestFactory \
INPUT FEATURE_TYPE * hexPt1 @ConvertBase(&int1,10,16,8) \
hexPt2 @ConvertBase(&int2,10,16,8) \
hexPt3 @ConvertBase(&int3,10,16,8) \
hexPt4 @ConvertBase(&int4,10,16,8) \
goidHexString @Concatenate
(&hexPt1,&hexPt2,&h exPt3,&hexPt4) \
TEST @GOID(VERIFY,goidHexString) = 1 \
OUTPUT PASSED FEATURE_TYPE * \
OUTPUT FAILED FEATURE_TYPE * @Abort(Failed GOID validation
-- &goidHexString is not a valid GOID)
A-47 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @KeepAttributes
A.24 @KeepAttributes
@KeepAttributes(<attrName>[,<attrName>]*)
FUNCTION TYPE: FEATURE
ARGUMENTS:
A.24.1 Configuration
This function does not accept configuration lines.
A.24.2 Description
The function takes a list of attribute names and simply removes all attributes from the
feature which are not specified in the list. This function is used to reduce the number
of attributes which are associated with a feature. This function is only necessary if
features are being created with an extremely large number of attributes (> 1000) and
the lifetime of the features is long due to the features being blocked in FME factories
for processing. The function is also useful when transferring structures into SAIF
when the SAIF definition of a structure is a subset of the features structure attribute.
It may also be used in conjunction with AutoCAD extended entity output to reduce
the number of attributes stored.
A.24.3 Inverse Operation
This function does nothing when invoked in the reverse direction, which happens
when it appears on the source portion of a transfer specification.
A.24.4 Example
When executed in the forward direction the @KeepAttributes function is used
to keep attributes mif_type and mif_pen_width. All the features which enter
the ListFactory will be reduced to carrying only two attributes. The output will be a
single feature for every combination of mif_type and mif_pen_width.
FACTORY_DEF MIF ListFactory \
INPUT FEATURE_TYPE bigFeature \
@KeepAttributes(mif_type,mif_pen_width) \
Name Range Description Optional
<attrName> String The name of the attribute which is to be
remain in the feature.
No
@KeepAttributes FME FUNCTION REFERENCE
A-48 FME Reference Manual Version 2.0
GROUP_BY mif_type mif_pen_width
LIST_NAME dummyList{}
OUTPUT POLYGON FEATURE_TYPE *
A-49 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Length
A.25 @Length
@Length( [<dimension> [, <multiplier>] ] )
FUNCTION TYPE: ATTRIBUTE
ARGUMENTS:
A.25.1 Configuration
This function does not accept configuration lines.
A.25.2 Description
The @Length function calculates the length of features. For polygonal features the
length is equal to the sum of its perimeter and the perimeter of any holes within it.
The optional multiplier is used to convert the return value from ground units to units
more useful to the caller.
A.25.3 Inverse Operation
This function has no inverse.
A.25.4 Example
In the below example, the SHAPE len attribute is set to the 3d length of the SAIF
Road when features are translated from SAIF to SHAPE. However, when features
are translated from SHAPE to SAIF, the @Length call is ignored.
SHAPE roads len @Length(3)
SAIF Road::MOF
Name Range Description Optional
<dimension> 2|3 Specifies whether the 3
rd
dimension is used in
the length calculation. The default is 2,
meaning only the x and y coordinates will be
used in the calculation. If 3 is specified, and
the feature has only 2 dimensions, no error is
flagged and the length will be calculated on
the 2 available dimensions.
Yes
<multiplier> real number By default, the length returned is in ground
units. The multiplier, if specified, can be used
to convert to other units. The default is 1.
Yes
@Log FME FUNCTION REFERENCE
A-50 FME Reference Manual Version 2.0
A.26 @Log
@Log([<message>[,<maxCoords>]])
FUNCTION TYPE: FEATURE
ARGUMENTS:
A.26.1 Configuration
This function does not accept configuration lines.
TIP: Because the @Log function writes out large amounts of data to the log file, it will significantly slow a
translation and so it should be used only during testing and debugging. The LOG_MAX_FEATURES
mapping file directive limits the number of features which may be logged in a single FME session.
A.26.2 Description
The @Log function outputs features to the FME log file. This function is primarily
used during testing and debugging of transformation specifications, so the complete
state of a feature can be viewed before and after it is transformed. It can also be used
to log a feature before and after a feature function is applied.
The function is also useful for logging erroneous features to the logfile when the FME
is used as a QA tool for processing data.
Name Range Description Optional
<message> Any string An optional message may be specified. If
present, this message is output to the log
file before each feature is logged. This is
useful to identify features if the @Log
command is used in many places in a single
mapping file.
Yes
<maxCoords Integer >= -1 The number of coordinates which are to be
logged.
If not specified then the first 5 and last 5
coordinates are logged.
If -1 is specified then all coordinates are
logged.
If 0 is specified then no coordinates are
logged.
If any other value is specified then only the
first <maxCoords> coordinates are logged.
Yes
A-51 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Log
A.26.3 Inverse Operation
The inverse is the same as the forward operation in both cases, the feature is output
to the log file.
A.26.4 Example
In the below example, the feature will be logged both as a SAIF feature and an IGDS
feature:
SAIF Contour::TRIM \
position.geometry.value %value \
@Generalize(10) @Log()
IGDS 12 igds_type igds_line igds_color 3 \
@Elevation(%value) @Log()
In this second example, when IGDS is the destination, the IGDS feature is logged
before and after the generalization function is applied. When IGDS is the source, the
@Generalize function does nothing and the feature is logged twice, looking the
same both times:
SAIF Contour::TRIM \
position.geometry.value %value
IGDS 12 igds_type igds_line igds_color 3 \
@Elevation(%value) \
@Log(Before Generalization:) \
@Generalize(10) \
@Log(After Generalization:)
TIP: Note the use of the optional message parameter to identify the logged features in the log file.
@Lookup FME FUNCTION REFERENCE
A-52 FME Reference Manual Version 2.0
A.27 @Lookup
@Lookup( <lut name>, <value> )
FUNCTION TYPE: ATTRIBUTE
ARGUMENTS:
A.27.1 Configuration
Lookup <lut name> [<source> <rep value>]+
A.27.2 Description
The @Lookup function applies look up tables to attribute values during
transformation. The look up tables are first defined in the mapping file on their own
configuration lines. Many to one lookups are supported, however, information will be
lost when the inverse operation is performed using such look up tables.
If a value to be looked up is not found in the table, then the translation is aborted and
the error is reported. However, since such situations may occur legitimately, the
special source value consisting of a blank string is the default. When a source value
cannot be found in the list, then this default will be used if it is available. In addition,
any occurrences of the special word KEY in the default replacement string will be
substituted with the original source value.
Name Range Description Optional
<lut name> String Identifies the lookup table. It must have been
defined by a Lookup configuration line.
No
<value> String The value to be looked up in the named
lookup table. The function will then return the
found value, or blank if none was found.
No
Name Range Description Optional
<lut name> string The name of the lookup table (lut), which
used as the first argument to the @Lookup
function.
No
<source> string The value which is mapped to its replacement
value when the @Lookup is invoked in the
forward direction.
No
<rep value> string The value which will be returned when the
source value is passed to the @Lookup
function invoked in the forward direction.
No
A-53 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Lookup
The @Lookup function is an attribute value function, which means that it is used to
supply a value to an attribute as opposed to modifying a whole feature.
A.27.3 Inverse Operation
When executed in the inverse direction (on the source line of a transformation
specification), the value of the attribute will be looked up among the replacement
values of the lookup table, and the transfer variable will be assigned the appropriate
source value. This allows the same lookup statement to be used for both directions
of a translation.
If the lookup table mapped several source values to the same replacement value,
information will be lost on the inverse operation. Only the last of the source value
corresponding to the replacement value will be output.
A.27.4 Example 1
In the below example, the parkTypeLut defines a lookup table from codes used as
shape file attributes to their SAIF enumeration equivalents. When SAIF is the
destination system, the value of the %pk transfer variable is looked up in the table and
its mapping is returned. For example, if a SHAPE feature had a pkType of HP,
@Lookup would return historicPark.
When translation occurs from SAIF back to SHAPE, the @Lookup runs in the
reverse direction. In this case, it scans the right hand side of the lut for a match to the
value of the SAIF features parkType attribute. When a match is found, it sets the
%pk transfer variable to the left-hand side lut value. For example, if a SAIF feature
had a parkType value of nationalPark, %pk would be set to NP.
# -------------------------------------------------
# Define the parkType lookup table. It maps values
# held in a shape file to their SAIF enumeration tag
Lookup parkTypeLut HP historicPark \
NE naturalEnvironmentPark \
NP nationalPark \
PA protectedArea
SHAPE parks pkType %pk
SAIF Park::MOF position.geometry.Class Point \
parkType @Lookup(parkTypeLut,%pk)
A.27.5 Example 2
In this example, the default lookup is used to allow data outside the expected range
of source values to pass through without causing the translation to abort. The output
data can then be analyzed to see what source values were not handled by the lookup
@Lookup FME FUNCTION REFERENCE
A-54 FME Reference Manual Version 2.0
table by selecting out all records that have the string "Unknown Ownership
Code" in them.
Lookup ownershipCodeLut \
NM "Northwest Mounted Police" \
FW "Fisheries and Wildlife" \
MF "Forestry" \
"" "Unknown Ownership Code KEY"
SHAPE parcels OWNCODE %code
MIF mifparcel ownership @Lookup(ownershipCodeLut,%code)
A-55 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @NumCoords
A.28 @NumCoords
@NumCoords()
FUNCTION TYPE: ATTRIBUTE
ARGUMENTS: NONE
A.28.1 Configuration
This function does not accept configuration lines.
A.28.2 Description
This function returns the number of coordinates which define the features geometry.
A.28.3 Inverse Operation
The function performs the same operation in the inverse direction.
A.28.4 Example
In the example below the MapInfo numCoords attribute is set to the number of
coordinates which are stored in the feature when going from SHAPE to MIF. When
going from MIF to SHAPE the command has no effect.
SHAPE lake
MIF lake numCoords @NumCoords()
@NumElements FME FUNCTION REFERENCE
A-56 FME Reference Manual Version 2.0
A.29 @NumElements
@NumElements( [<listName>] )
FUNCTION TYPE: ATTRIBUTE
ARGUMENTS:
A.29.1 Configuration
This function does not accept configuration lines.
A.29.2 Description
This function returns a count of the number of elements in an attribute list. Certain
legacy systems, most often those using the Column-Aligned-Text (CAT) format,
require such a count be output. Consequently, this function is most commonly used
to compute a value for a TRANSFER clause in a relation definition (see the @Relate
documentation in this appendix for details).
A.29.3 Inverse Operation
This function has no inverse.
A.29.4 Example
Given the below feature:
Name Range Description Optional
<listName> any feature
attribute list
The function will return the number of
elements present in this attribute list. The
name should contain an {} pair to indicate
that it is a list.
No
Feature Type: ForestStand::BCFOR
Attribute Name Value
stand{0}.species birch
stand{0}.age 30
stand{1}.species birch
stand{1}.age 30
A-57 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @NumElements
@NumElements(stand{}) would return 2, since there are two elements
(stand{0} and stand{1}) in the stand attribute list.
The 1:M example in the @Relate section contains a complete example of
@NumElements used in conjunction with @Relate.
Coordinates: 50321, 5022321, 35
Feature Type: ForestStand::BCFOR
Attribute Name Value
@NumHoles FME FUNCTION REFERENCE
A-58 FME Reference Manual Version 2.0
A.30 @NumHoles
@NumHoles()
FUNCTION TYPE: ATTRIBUTE
ARGUMENTS: NONE
A.30.1 Configuration
This function does not accept configuration lines.
A.30.2 Description
This function returns the number of holes in a polygonal feature. If the feature was
not polygonal, or it had no holes, it returns 0. If the feature contained disjoint
polygons, then the number returned is the total number of holes in all the pieces of the
feature.
A.30.3 Inverse
When invoked on the source line of a transfer specification, @NumHoles does
nothing.
A.30.4 Example
In this example, all polygons read from a SHAPE file are tested to see if they have
holes. Those with holes are given a feature type on output of hasHoles, while those
without are given the feature type noHoles.
FACTORY_DEF SHAPE TestFactory \
INPUT FEATURE_TYPE * SHAPE_GEOMETRY shape_polygon \
TEST @NumHoles() > 0 \
OUTPUT PASSED FEATURE_TYPE hasHoles \
OUTPUT FAILED FEATURE_TYPE noHoles
A-59 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Offset
A.31 @Offset
@Offset(<offset>)
@Offset(<xOffset>, <yOffset>)
@Offset(<xOffset>, <yOffset>, <zOffset>)
FUNCTION TYPE: FEATURE
ARGUMENTS:
A.31.1 Configuration
This function does not accept configuration lines.
A.31.2 Description
This command adds the offsets to the coordinates of the feature. If just one value is
specified, then X, Y, and Z are all offset by that amount. If two values are specified,
then X and Y are offset as specified and the Z component is left untouched. If three
values are specified, then X, Y, and Z are offset as specified.
A.31.3 Inverse Operation
The function subtracts the offsets from the feature coordinates.
A.31.4 Example
In the example below the building coordinates are offset by 100 when going from
SHAPE to MIF. When going from MIF to SHAPE the building coordinates are
subtracted by 100.
SHAPE building
MIF building @Offset(100.0)
Name Range Description Optional
<offset> real value All X, Y, and Z coordinates are offset by
this value.
No
<xOffset> real value The X offset to be applied to the feature. No
<yOffset> real value The Y offset to be applied to the feature. No
<zOffset> real value The Z offset to be applied to the feature. No
@Orient FME FUNCTION REFERENCE
A-60 FME Reference Manual Version 2.0
A.32 @Orient
@Orient (<orientation>)
FUNCTION TYPE: FEATURE
ARGUMENTS:
A.32.1 Configuration
This function does not accept configuration lines.
A.32.2 Description
This function adjusts the orientation of a polygonal feature. If the feature was not
polygonal, it logs a warning, and leaves the feature untouched.
It takes only one parameterthe orientation to set for the feature. The values allowed
are: RIGHT_HAND_RULE and LEFT_HAND_RULE. If RIGHT_HAND_RULE is
specified, then the area of the polygon is always on an observers right hand as the
observer traverses the boundary. For the outer boundary, this means that the vertices
are in a clockwise direction, and for holes, their vertices are in a counterclockwise
direction.
The opposite is true when LEFT_HAND_RULE is specified. When the
LEFT_HAND_RULE is specified, the feature will be returned so that the outer
boundarys vertices are in a counterclockwise order, and the holes have a clockwise
ordering.
When REVERSE is specified, the features coordinates are flipped so that the first
coordinate becomes the last one, and vice-versa. This option is intended for use with
features that are not polygonal.
A.32.3 Inverse
When invoked on the source line of a transfer specification, @Orient orients the
feature in the opposite direction of the parameter it is passed.
Name Range Description Optional
<orientation> RIGHT_HAND_RULE|
LEFT_HAND_RULE
REVERSE
This parameter controls what
orientation the feature will have when
the function has completed.
No
A-61 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Orient
A.32.4 Example:
In this example, all polygons read from a MIF file are adjusted to follow right-hand-
rule orientation.
FACTORY_DEF SHAPE SamplingFactory \
SAMPLE_RATE 1 \
INPUT FEATURE_TYPE * mif_type mif_region \
@Orient(RIGHT_HAND_RULE)
@Relate FME FUNCTION REFERENCE
A-62 FME Reference Manual Version 2.0
A.33 @Relate
@Relate( <relationId>, (DestReadSrcWrite|DestWriteSrcRead) )
FUNCTION TYPE: FEATURE
ARGUMENTS:
A.33.1 Description
The @Relate function combines relational data held in auxiliary databases with
FME features. The function can be configured to perform simple single-table joins,
or complex, multi-table, multi-record joins. The relational data may be held in one or
more of the four supported file formats, and in the future live database support will
be added.
The @Relate function is a feature function which adds data from a relational table
to the FME feature when it is reading. When it is writing, it extracts data from the
FME feature and writes it to a relational table.
This function requires considerable configuration before it may be invoked.
The location of the table must be specified using the TABLE_LOCATION
configuration option.
The structure of each table used by the relation definition must be specified using
the TABLE_DEF configuration option. Presently, four table file formats are
supported, and in the future live database tables will be allowed.
The relation itself must be defined. The relation operates on a logical table name,
and is independent of the actual physical structure of the table. The relation is
defined using the RELATION_DEF configuration option.
Name Range Description Optional
<relationId> must be defined Identifies the relation definition to
execute. Relations are defined by
Relate RELATION_DEF
statements.
No
<direction> DestReadSrcWrite
or
DestWriteSrcRead
Indicates the direction of the relation.
DestReadSrcWrite means that the
Relate will read data from the relational
tables into the feature when it is
invoked on a destination transfer
specification line (or on a factory input
or output clause). It will write data
when it is invoked on a source line.
DestWriteSrcRead means the
opposite.
No
A-63 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Relate
Relations may be one to one, in which case a single record will be extracted from the
table and added to the FME feature when the relation is executed in the forward
direction. One to many relations will add 0 or more table records to the FME feature.
The table field and feature attribute names specified in the JOIN clause of the relation
definition select the record(s) from the table. The FME feature must have previously
had values for any attributes named in a JOIN clause. Once a record is selected, the
TRANSFER clause will move the table fields into the named FME feature fields.
Once this is done, the feature functions, if any, attached to the relation are executed.
The most common feature function used is another @Relate call, which allows the
relation to pull information from several tables in the FME feature.
Attribute value functions can be used in place of table field and feature attribute
names in JOIN and TRANSFER clauses. This allows attribute value functions to be
used to calculate field values. The values of table fields and feature attributes can be
passed to commands by putting the value-of operation (an ampersand &) in front of
their name.
When the relation is executed in the forward direction, the left (table) side of the
TRANSFER clause is the source of attribute values. Any attribute functions on
this side will be executed in the forward direction. The value transferred to the
feature side of the clause will be the result of the inverse execution of the
function.
The right (feature) side of the TRANSFER clause is the destination of the table
values. Any attribute functions on this side will be executed in the inverse
direction. The value stored in the feature attribute will be the result of the forward
execution of the function.
The JOIN clause works in the opposite way when a relate is executed in the
forward direction. This is because the JOIN will look in the table for the values
specified by the feature. In this case, then, the right hand (feature) side of the
JOIN clause is the source of the key values. Any attribute functions on this side
will be executed in the inverse direction. The resulting value is passed as the key
value to the table side of the clause.
The left (table) side of the JOIN clause is the destination of the key values. Any
attribute functions on this side will be executed in the forward direction, since
functions on the destination side always executed in this way. The value
computed will then be searched for in the table to identify the record to be
extracted.
When the relation is 1 to many, several rows may be pulled from the relational
table. The TRANSFER clauses and feature functions of the relation will be
executed for each row. Any attribute list field names on the feature side will be
expanded to include the row number in their {}. Rows are numbered starting at 0.
@Relate FME FUNCTION REFERENCE
A-64 FME Reference Manual Version 2.0
A.33.2 Inverse Operation
When a relation is executed in the inverse direction, information is extracted from the
FME feature and output to the table. In the case of a one to one relation, a single
record will be output to the table, while one to many relations will add 0 or more
records to the table.
The inverse execution makes use of the field combinations listed in the UNIQUE
clause to prevent writing duplicate records to the output tables. For some tables and
relation combinations, this is not an issue. In these cases, the NOTUNIQUE keyword
is used in place of the UNIQUE clause.
In the inverse case, the FME feature is the source for all the attribute data. Values are
transferred from the right hand (feature) side of both the JOIN and TRANSFER
clauses to the table field names. Once a candidate table record has been constructed,
a check is made to see if a record is already present in the table that is identical
(according to the fields listed in the UNIQUE clause), and if so, the candidate record
is discarded. Otherwise, the record is written to the table. Once the record is written,
any feature functions that were part of the relation are executed in the inverse
direction.
Attribute value functions present in the JOIN and TRANSFER clauses are executed
according to the following rules.
When the relation is executed in the inverse direction, the right hand (feature)
side of the JOIN and TRANSFER clauses is the source of attribute values. Any
attribute functions on this side will be executed in the inverse direction, since
functions on the source side are always executed backwards. The value
transferred to the table side of the clause will be the result of the inverse
execution of the function.
The left hand (feature) side of the JOIN and TRANSFER clauses is the
destination of the feature values. Any attribute functions on this side will be
executed in the forward direction, since functions on the destination side always
executed in this way. The value stored in the table will be the result of the
forward execution of the function.
When the relation is 1 to many, several rows may be output to the relational table. The
JOIN and TRANSFER clauses and feature functions of the relation will be executed
in the inverse direction for each row. Any attribute list field names on the feature side
will be expanded to include the row number in their {}. Rows are numbered starting
at 0. When no data for a row can be found in the feature, then the relate function
terminates.
A-65 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Relate
A.33.3 Configuration
Relate RELATION_DEF <relationId> <cardinal> \
TABLE <tableId> \
[UNIQUE(<tableField>[,<tableField>]+) | \
NOTUNIQUE] \
[JOIN <tableField> TO <featureField>]+ \
[TRANSFER <tableField> TO <featureField>]* \
[<featFunc>] *
TIP: The JOIN clause identifies the key fields which must match in both the FME feature and the table row.
The TRANSFER clause identifies fields which should be copied between the FME feature and the table
row.
Name Range Description Optional
<relationId> character string The name of the relation defined by the
configuration statement. This name is used
as the argument when the @Relate
function is called.
No
<cardinal> 1:1|
1:M
Defines the cardinality of the relation. 1:1
implies that there will be exactly 1 row in
the table for each feature. 1:M implies that
there will be 0 or more rows in the table for
each feature. 1:M relations make use of
feature attribute lists to store the attribute
data in FME features.
No
<tableId> character string The logical name of the table used by this
relation. The tables structure and location
are defined by TABLE_LOCATION and
TABLE_DEF statements.
No
<tableField> The name of any
field in the table, or
an attribute value
function.
Table field names are used by the UNIQUE
clause to name the combinations of fields
that together are never duplicated in the
table. This is used by some 1:1 relations to
avoid writing duplicate records to tables.
1:M relations by definition are
NOTUNIQUE.
Table field names are used in JOIN and
TRANSFER clauses to identify the fields in
the table that are joined or transferred to the
corresponding fields in the FME feature.
As well, in these clauses an attribute
function may be used in place of the table
field name.
No
<featureField> The name of any
FME feature
attribute, or an
attribute value
function.
An FME feature attribute name. If the
relation is 1:M, and the feature attribute
name contains an empty set of parenthesis
{}, the parenthesis will be filled with the
current matching row number. Rows are
numbered starting at 0. In JOIN and
TRANSFER clauses, an attribute function
may be used in place of the feature attribute
name.
No
@Relate FME FUNCTION REFERENCE
A-66 FME Reference Manual Version 2.0
Relate TABLE_LOCATION <tableId> <pathname>
Relate TABLE_DEF <tableId> <tableType>\
[<fieldName> <fieldType>]+
a. Any feature function can be called, including other @Relate functions. This allows
relations to cascade across several tables.
<featFunc> any valid
a
feature
function
One or more feature functions may be
specified at the end of a relation definition.
These functions will be called after the
JOIN and TRANSFER processing has been
completed. If the relation is being executed
in the forward direction, the functions will
be called in the forward direction. If the
relation is executed in the inverse direction,
then the inverse of these functions is called.
If the relation is 1:M, then these functions
will be called once for each row that is
processed.
No
Name Range Description Optional
<tableId> character string The logical name of the table whose location
is being set. The tables structure is defined by
a subsequent TABLE_DEF statement.
No
<pathname> a valid operating
system file path
The location on the file system of the table. No
Name Range Description Optional
<tableId> character string The logical name of the table being defined.
This name will be used in
RELATION_DEF and
TABLE_LOCATION statements.
No
<tableType> ASCII|
CAT|
CSV|
DBF
The type of the table being defined.
ASCII: Repeating free form ASCII
CAT: Column Aligned Text
(FORTRAN-style file)
CSV: Comma separated value file
DBF: Dbase 4+ file
No
<fieldName> character string The name of the field. For DBF files, the
field names must be in upper case and no
more than 10 characters long. Certain table
types may reserve specific field names for
special purposes.
No
Name Range Description Optional
A-67 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Relate
A.33.4 ASCII Field Types
<fieldType> character string The type of the field. The allowable field
types depend on type of database file. The
following tables describe the allowable
field types for each of the supported
formats. Certain table types may reserve
specific field types for special purposes.
No
Field Type Description
as_constant A free-form ASCII file may contain constants as part of
each record. Such constants are not to be transferred to
features as attribute values, but when the ASCII file is
written the constant must be output. Fields of type
as_constant are used to represent such fields to the
FME. The field name in this case is interpreted as being the
value of the constant, and not a field name within a feature.
as_special This field type is used in conjunction with one of the special
ASCII field names listed in the next subsection.
char(<width>,<position>) String fields store character strings. The width parameter
controls the maximum of characters that can be stored by
the field.
date Date fields store dates as character strings with the format
YYYYMMDD. When date fields are read, they assign the
date in the above format to the fieldname. In addition, they
assign these fields:
<fieldName> YYYYMMDD
<fieldName >.yyyy YYYY
<fieldName >.yy YY
<fieldName >.mm MM
<fieldName >.dd DD
When a date field is written, it looks first for the complete
date to be held in the fieldname. Failing that, it will look in
the .yyyy or .yy, .mm, and .dd fields for the date portions,
and create the date from these.
float(<width>,<decimals>) Float fields store floating point values. The width parameter
is the total number of characters allocated to the field,
including the decimal point. The decimals parameter
controls the precision of the data, and is the number of digits
to the right of the decimal.
integer(<width>) Integer fields store integer values. The width parameter is
the total number of characters allocated to the field.
stringlist A stringlist field in an ASCII table consists of an integer
value indicating the number of elements in the list, followed
by a series of lines containing the string elements. Such a
field is stored or retrieved from an FME list stored in an
FME feature.
Name Range Description Optional
@Relate FME FUNCTION REFERENCE
A-68 FME Reference Manual Version 2.0
A.33.4.1 ASCII Special Fields
as_lineend{#} as_special
In free-form ASCII files, line end characters must be explicitly identified to indicate
when line breaks occur in the file. Line ends are indicated by the as_lineend
special field name. Each lineend must be assigned a unique number within the table,
and this number is appended in braces to the as_lineend field name. The
as_lineend field names must always have a type of as_special.
as_coordinatelist as_special
Two dimensional feature coordinate values may be read from or written to free form
ASCII files. Such coordinates are preceded in the file by an integer indicating the
number of coordinates. The coordinates are then written, in X Y pairs separated by
blanks, on consecutive lines in the file.
A.33.5 CAT Field Types
Field Type Description
Integer(<width>,
<position>,
<zeroPad>)
Integer fields store integer values. The width parameter is
the total number of characters allocated to the field. The
position parameter is the starting column of the field in
the CAT record. The columns are numbered starting from 1.
If zeroPad parameter is Y, then the number will be
padded with zeros on the left to fill out the field. If
zeroPad parameter is N, then no zero padding will be
performed.
Real(<width>,<position>,
<decimals>)
Real fields store floating point values. The width parameter
is the total number of characters allocated to the field,
including the decimal point. The decimals parameter
controls the precision of the data, and is the number of digits
to the right of the decimal. The position parameter is
the starting column of the field in the CAT record. The
columns are numbered starting from 1
String(<width>,<position>) String fields store fixed length strings. The width
parameter controls the maximum of characters that can be
stored by the field. When a character field is written, it is
right-padded with blanks or truncated to fit the width. When
a character field is retrieved, any padding blank characters
are stripped. The position parameter is the starting
column of the field in the CAT record. The columns are
numbered starting from 1.
A-69 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Relate
A.33.5.1 CAT Special Fields
[CAT_SUBTYPE (<start>,<length>,<constant>)]
If the table is a CAT table, a special field may be listed to identify the record key of
the records. This allows several different record types to be held in the same physical
CAT file. If no CAT_SUBTYPE is identified, then no record key is assumed to be
present in the file. For this field, fieldType is used to convey the specifics of the record
key. The parameters of this special field are listed in the following table:
A.33.6 CSV/DBF Field Types
Name Range Description Optional
<start> integer If the file is of type CAT, an optional record
key may be specified. This allows several
different record types to be held in the same
physical CAT file. This parameter defines the
starting column of the key. Columns are
numbered starting with 1.
Yes
<length> integer The length in characters of the optional CAT
record key.
Yes
<constant> string The constant used as the optional CAT record
key, which occurs in the record at the
<start> column.
Yes
Field Type Description
number(<width>,<decimals>) Number fields store floating point values. The width
parameter is the total number of characters allocated to the
field, including the decimal point. The decimals
parameter controls the precision of the data, and is the
number of digits to the right of the decimal.
char(<width>) Character fields store fixed length strings. The width
parameter specifies the number of characters that can be
stored. When a character field is written, it is right-padded
with blanks or truncated to fit the width. When a character
field is retrieved, any padding blank characters are stripped.
logical Logical fields store TRUE/FALSE data. Data read or
written from/to such fields must always have a value of
either true or false.
date Date fields store dates as character strings with the format
YYYYMMDD.
@Relate FME FUNCTION REFERENCE
A-70 FME Reference Manual Version 2.0
A.33.6.1 CSV Special Fields
[CSV_SEPARATOR (<separator>)]
If the table is a CSV table, a special field may be listed to identify the separator used
to divide the fields in the file. By default, a comma is used as the separator. For this
field, fieldType contains the new separator, enclosed in parentheses. The separator
must be only 1 character long.
[CSV_SKIP_LINES <number>]
If the table is a CSV table, a special field may be listed to indicate the number of lines
to skip at the top of the file. By default, no lines are skipped. Each line skipped is
logged to the log file. This is useful if the CSV file contains a header line of field
names, or other descriptive material, that should be skipped.
A.33.7 Example 1
An IGDS file contains a set of shapes on level 45. Each shape has its graphic group
set to a unique number, which can be used as a key to an associated CSV file
containing information on the forest species and logging company assigned to the
polygon. This is translated into a single SHAPE file, which will combine hold these
attributes in the elements attribute table.
# The definition of the shape file.
SHAPE_DEF forestpoly SHAPE_GEOMETRY shape_polygon \
POLYID number(4,0) \
SPECIES char(15) \
COMPANY char(6) \
AREA number(10,3)
#--------------------------------------------------
# The location of the CSV file.
Relate TABLE_LOCATION forestTable /usr/data/forest.csv
The definition of the CSV file.
Relate TABLE_DEF forestTable CSV \
polygonID number(4,0) \
forestSpecies char(15) \
companyId char(6)
# The relation definition. Notice that the left hand side of the JOIN
# and TRANSFER clauses contains field names from the CSV file, while
# the right hand side contains field names to be used by the SHAPE
# writer or reader.
Relate RELATION_DEF Poly_To_Forest 1:1 \
TABLE forestTable \
UNIQUE(polygonID) \
A-71 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Relate
JOIN polygonID TO POLYID \
TRANSFERforestSpecies TO SPECIES \
TRANSFERcompanyId TO COMPANY
#--------------------------------------------------
# The IGDS half of the transfer specification. Notice that the %pid
# transfer variable is set to the graphic group number.
IGDS 45 idgs_type igds_shape \
igds_graphic_group %pid
# The SHAPE half of the transfer specification. Notice that the
# POLYID field is set to the value of the transfer variable, the
# AREA field will be set to the result of the @Area function, and
# the @Relate function will be called to fill in values for the other
# SHAPE attributes.
SHAPE forestpoly POLYID %pid \
AREA @Area() \
@Relate(Poly_To_Forest,DestReadSrcWrite)
The results of the translation are shown below.
If the original IGDS file had exactly 2 polygons with graphic group numbers 1001
and 1002, and the original CSV file contained:
1001,fir,MACBLO
1002,spruce,CANFOR
the resulting shape file would contain two polygons, and its attribute table would look
like:
A.33.8 Example 2
Building on the previous example, an additional DBF file has been located. This file
maps the 6 character company code to the company full name. The user of the shape
file would prefer to see the long name in their data rather than the code. The below
mapping file accommodates this.
SHAPE_DEF forestpoly SHAPE_GEOMETRY shape_polygon \
POLYID number(4,0) \
SPECIES char(15) \
COMPNAME char(40) \
AREA number(10,3)
#--------------------------------------------------
POLYID SPECIES COMPANY AREA
1001 fir MACBLO 500.201
1002 spruce CANFOR 201.405
@Relate FME FUNCTION REFERENCE
A-72 FME Reference Manual Version 2.0
Relate TABLE_LOCATION forestTable /usr/data/forest.csv
# The location of the new DBF file.
Relate TABLE_LOCATION company /usr/data/company.dbf
Relate TABLE_DEF forestTable CSV \
polygonID number(4,0) \
forestSpecies char(15) \
companyId char(6)
# The definition of the new DBF file.
Relate TABLE_DEF company DBF \
COMPID char(6) \
FULLNAME char(40)
Relate RELATION_DEF CompanyID_To_Name 1:1 \
TABLE company \
UNIQUE(COMPID) \
JOIN COMPID TO compId \
TRANSFER FULLNAME TO COMPNAME
Relate RELATION_DEF Poly_To_Forest 1:1 \
TABLE forestTable \
UNIQUE(polygonID) \
JOIN polygonID TO POLYID \
TRANSFER forestSpecies TO SPECIES \
TRANSFERcompanyId TO compId \
@Relate(CompanyID_To_Name)
IGDS 45 idgs_type igds_shape \
igds_graphic_group %pid
SHAPE forestpoly POLYID %pid \
AREA @Area() \
@Relate(Poly_To_Forest,DestReadSrcWrite)
The @Relate clause will go to the company table and fetch out the companys full
name. Note that since the Poly_To_Forest relation is 1-1, the @Relate could
have been placed on the SHAPE line instead of here.
If the original IGDS file had exactly 2 polygons with graphic group numbers 1001
and 1002, and the original forestTable CSV file contained:
1001,fir,MACBLO
1002,spruce,CANFOR
and the original company DBF file contained:
A-73 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Relate
the resulting shape file would contain two polygons, and its attribute table would look
like:
A.33.9 Example 3
This example illustrates the use of the @Relate command to join forestry data from
an IGDS file and several related attribute tables into a single SAIF object. Several
one-to-many relationships are traversed to accomplish the join. The same mapping
file can be used to go both to and from SAIF.
To assist in understanding the example, the below entity relationship diagram
sketches the relationships between each of the four auxiliary data tables.
The IGDS data file uses the text node number field to store a polygon number. This
number is used as the key to the Polygon table, which in turn can be related to the
other tables.
The SAIF object model for this data is shown below, using the Class Syntax Notation
language:
COMPID FULLNAME
MACBLO MacMillan Bloedel
CANFOR Canada Forest Products
POLYID SPECIES COMPNAME AREA
1001 fir MacMillan Bloedel 500.201
1002 spruce Canada Forest Products 201.405
Polygon
Result
Layer
History
1 M
M 1
1 1
@Relate FME FUNCTION REFERENCE
A-74 FME Reference Manual Version 2.0
<AbstractObject
subclass: TreeStuff::SAFE
attributes: saif_treeCode String
// Note that the treecode could be made into an enum
saif_percentage Real
>
The HistoryStuff and LayerStuff AbstractObjects correspond to the
History and Layer tables.
<AbstractObject
subclass: HistoryStuff::SAFE
attributes: saif_actYear1 Integer
saif_actYear2 Integer
saif_activityCode String
// Of course, activityCode could also be an enum
>
<AbstractObject
subclass: LayerStuff::SAFE
attributes: saif_layerNumber Integer
saif_rank Integer
saif_trees List(TreeStuff::SAFE)
saif_history List(HistoryStuff::SAFE)
>
<Enumeration
subclass: InOpCode::SAFE
values: go nogo
>
<GeographicObject
subclass: ForestStand::SAFE
attributes: saif_id Integer
saif_mapsheetId String
saif_inopCode InOpCode::SAFE
saif_tsaNum Integer
saif_tsbNum Integer
saif_fizCode String
saif_layerStuff List(LayerStuff::SAFE)
>
<SpatialDataSet
subclass: ForestStandComposite::SAFE
restricted: geoComponents{}: ForestStand::SAFE
>
The relevant portion of the mapping file which join the IGDS spatial data to the
tabular data to produce SAIF objects is shown below.
Notice the use of macros to provide a single definition of the directory holding the
input files.
MACRO baseDir /usr/safe/forestData
MACRO MAPSHEETID 92b034
Relate TABLE_LOCATION polygon $(baseDir)/polygon.csv
Relate TABLE_LOCATION history $(baseDir)/history.csv
Relate TABLE_LOCATION layer $(baseDir)/layer.csv
Relate TABLE_LOCATION result $(baseDir)/result.csv
A-75 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Relate
# ----------------------------------------------------------------
Relate TABLE_DEF polygon CSV \
mapsheetId char(10) \
polygonId number(3,0) \
inopCode char(2) \
layerCount number(3,0) \
historyCount number(3,0)
Relate TABLE_DEF layer CSV \
mapsheetId char(10) \
polygonId number(3,0) \
layerNum number(3,0) \
rank number(3,0) \
tree1Code char(2) \
tree1Percent number(6,3) \
tree2Code char(2) \
tree2Percent number(6,3)
Relate TABLE_DEF history CSV \
mapsheetId char(10) \
polygonId number(3,0) \
layerNum number(3,0) \
activityYear1 number(4,0) \
activityYear2 number(4,0) \
activity string
Relate TABLE_DEF result CSV \
mapsheetId char(10) \
polygonId number(3,0) \
tsaNum number(3,0) \
tsbNum number(3,0) \
fizCode char(4)
# The lookup table is used to convert codes used in the original
# file to SAIF codes.
Lookup InOpCodeLUT AA go BB nogo
Relate RELATION_DEF Id_To_Polygon 1:1 \
TABLE polygon \
UNIQUE(polygonId,mapsheetId) \
JOIN polygonId TO saif_id \
JOIN mapsheetId TO saif_mapsheetId \
TRANSFER layerCount TO @NumElements(saif_layerStuff) \
TRANSFER historyCount TO @NumElements (saif_layerStuff
{}.saif_history) \
TRANSFER @Lookup(InOpCodeLUT,&inopCode) TO saif_inopCode\
@Relate(Polygon_To_Resultant,DestReadSrcWrite) \
@Relate(Polygon_To_Layer,DestReadSrcWrite)
# The Id_To_Polygon relation is the primary relation. After it is
# done transferring values, it invokes both the Polygon_To_Resultant
# and Polygon_To_Layer relations.
@Relate FME FUNCTION REFERENCE
A-76 FME Reference Manual Version 2.0
Relate RELATION_DEF Polygon_To_Resultant 1:1 \
TABLE result \
UNIQUE(polygonId,mapsheetId) \
JOIN polygonId TO saif_id \
JOIN mapsheetId TO saif_mapsheetId \
TRANSFER tsaNum TO saif_tsaNum \
TRANSFER tsbNum TO saif_tsbNum \
TRANSFER fizCode TO saif_fizCode
# This relation is 1 to many. It expects to find several rows in the
# table which match the polygonId and mapsheet id. For each row that
# matches, the {} are replaced by the row number and the values are
# transferred across. As well, for each row that matches, the
# Layer_To_History relation is invoked.
Relate RELATION_DEF Polygon_To_Layer 1:M \
TABLE layer \
NOTUNIQUE \
JOIN polygonId TO saif_id \
JOIN mapsheetId TO saif_mapsheetId \
TRANSFER layerNum TO saif_layerStuff{}.saif_layerNumber\
TRANSFER rank TO saif_layerStuff{}.saif_rank \
TRANSFER tree1Code TO saif_layerStuff{}.saif_trees{0}
.saif_treeCode \
TRANSFER tree1PercentTO saif_layerStuff{}.saif_trees{0}
.saif_percentage \
TRANSFER tree2Code TO saif_layerStuff{}.saif_trees{1}
.saif_treeCode \
TRANSFER tree2PercentTO saif_layerStuff{}.saif_trees{1}
.saif_percentage \
@Relate(Layer_To_History,DestReadSrcWrite)
Relate RELATION_DEF Layer_To_History 1:M \
TABLE history \
NOTUNIQUE \
JOIN polygonId TO saif_id \
JOIN mapsheetId TO saif_mapsheetId \
JOIN layerNum TO saif_layerStuff{}.saif_layerNumber\
TRANSFER activityYear1TO saif_layerStuff{}.saif_history{}
.saif_actYear1 \
TRANSFER activityYear2TO saif_layerStuff{}.saif_history{}
.saif_actYear2 \
TRANSFER activity TO saif_layerStuff{}.saif_history{}
.saif_activityCode
# ----------------------------------------------------------------
# Finally the transfer spec.
IGDS 14 igds_type igds_text_node igds_node_number %nodenum
SAIF ForestStand::SAFE position.geometry.Class Point \
saif_id %nodenum \
saif_mapsheetId $(MAPSHEETID) \
@Relate(Id_To_Polygon,DestReadSrcWrite) @Log(
Notice that the primary relation is activated on the SAIF line. When SAIF is the
output format, then the @Relate will go and read data into the SAIF object from the
tables. When SAIF is the source format, the Relate will write data out to the tables.
A-77 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Relate
The tables below show the original source data. A listing of the FME object which is
ultimately written out to SAIF for forest polygon 302 follows.
A.33.9.1 Polygon Table
A.33.9.2 Layer Table
A.33.9.3 History Table
mapsheetID polygonID inopCode layerCount historyCount
92b034 302 AA 2 5
92b034 303 BB 3 4
mapsheet
Id
polygon
Id
layer
Num
rank tree1
Code
tree1
Percent
tree2
Code
tree2
Percent
92b034 302 1 1 FIR 78 SPRUCE 22
92b034 302 2 0 SPRUCE 60 WILLOW 78
92b034 303 1 4 FIR 90 PINE 10
92b034 303 2 1 SPRUCE 65 FIR 35
92b034 303 3 8 PINE 70 WILLOW 30
mapsheetId polygonId layerNum activity
Year1
activity
Year2
activity
92b034 302 1 1990 1991 HARVEST
92b034 302 1 1992 1993 GROOM
92b034 302 1 1993 1994 HARVEST
92b034 302 2 1993 1994 HARVEST
92b034 302 2 1991 1993 GROOM
92b034 303 1 1993 1994 HARVEST
92b034 303 1 1990 1993 HARVEST
92b034 303 2 1990 1994 GROOM
92b034 303 3 1990 1994 GROOM
@Relate FME FUNCTION REFERENCE
A-78 FME Reference Manual Version 2.0
A.33.9.4 Result Table
A.33.9.5 Resulting FME Object (id=302)
mapsheetId polygonId tsaNum tsbNum fizCode
92b034 302 30 4 BUBBLY
92b034 303 21 55 FLAT
Feature Type: ForestStand::SAFE
Attribute Value
saif_id 302
saif_mapsheetId 92b034
saif_inopCode go
saif_tsaNum 300
saif_tsbNum 4
saif_fizCode BUBBLY
saif_layerStuff{0}.saif_layerNumber 1
saif_layerStuff{0}.saif_rank 1
saif_layerStuff{0}.saif_trees{0}.saif_treeCode FIR
saif_layerStuff{0}.saif_trees{0}.saif_ percentage 78
saif_layerStuff{0}.saif_trees{1}.saif_ treeCode SPRUCE
saif_layerStuff{0}.saif_trees{1}.saif_ percentage 22
saif_layerStuff{0}.saif_history{0}.saif_ actYear1 1990
saif_layerStuff{0}.saif_history{0}.saif_ actYear2 1991
saif_layerStuff{0}.saif_history{0}.saif_ activityCode HARVEST
saif_layerStuff{0}.saif_history{1}.saif_ actYear1 1992
saif_layerStuff{0}.saif_history{1}.saif_ actYear2 1993
saif_layerStuff{0}.saif_history{1}.saif_ activityCode GROOM
saif_layerStuff{0}.saif_history{2}.saif_ actYear1 1993
saif_layerStuff{0}.saif_history{2}.saif_ actYear2 1994
saif_layerStuff{0}.saif_history{2}.saif_ activityCode HARVEST
A-79 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Relate
saif_layerStuff{1}.saif_layerNumber 2
saif_layerStuff{1}.saif_rank 0
saif_layerStuff{1}.saif_trees{0}.saif_treeCode SPRUCE
saif_layerStuff{1}.saif_trees{0}.saif_percentage 60
saif_layerStuff{1}.saif_trees{1}.saif_treeCode WILLOW
saif_layerStuff{1}.saif_trees{1}.saif_ percentage 78
saif_layerStuff{1}.saif_history{0}.saif_ actYear1 1993
saif_layerStuff{1}.saif_history{0}.saif_ actYear2 1994
saif_layerStuff{1}.saif_history{0}.saif_ activityCode HARVEST
saif_layerStuff{1}.saif_history{1}.saif_ actYear1 1991
saif_layerStuff{1}.saif_history{1}.saif_ actYear2 1993
saif_layerStuff{1}.saif_history{1}.saif_ activityCode GROOM
Coordinates: 602322,5930211,40
Feature Type: ForestStand::SAFE
Attribute Value
@Reproject FME FUNCTION REFERENCE
A-80 FME Reference Manual Version 2.0
A.34 @Reproject
@Reproject( <sourceCS>, <destCS>
[,<xFieldName>, <yFieldName>] )
FUNCTION TYPE: ATTRIBUTE OR FEATURE
ARGUMENTS:
A.34.1 Description
The @Reproject function is only required in rare cases during FME translations.
The recommended approach to performing coordinate conversions is to use the
<readerKeyword>_COORDINATE_SYSTEM and
<writerKeyword>_COORDINATE_SYSTEM. See Section 5, Coordinate System
Support for more details.
This function provides direct access to the coordinate conversion capabilities of the
FME. With this function, feature coordinates may be converted from one coordinate
system to another during data translation.
When executed in the forward direction (on the destination line of a feature
correlation or on an INPUT or OUTPUT clause of a factory definition) then the
coordinate conversion operation is performed in the forward direction. In this case,
coordinates are converted from the source coordinate system to the destination
coordinate system.
If xFieldName and yFieldName are specified, then a single point coordinate
conversion is performed on the values of these attributes, and the resulting new
coordinates are stored back into these same attributes. In this case, the features
geometry coordinates are left untouched.
TIP: The fieldname parameters are usually used to convert the coordinates of an inside point, often stored as an
attribute of a polygonal feature.
Name Range Description Optional
<sourceCS> coordinate system
name
The name of the source coordinate system. No
<destCS> coordinate system
name
The name of the destination coordinate
system.
No
<xFieldName> attribute name The name of the attribute containing the x
coordinate value.
Yes
<yFieldName> attribute name The name of the attribute containing the y
coordinate value.
Ye
A-81 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Reproject
When xFieldName and yFieldName are not specified, then the coordinate
conversions are performed on the geometry of the feature. This is the usual mode of
operation.
A.34.2 Inverse Operation
When executed in the reverse direction (source line of a feature correlation) then the
coordinate conversion operation converts coordinates from the destination coordinate
system to the source coordinate system.
A.34.3 Example
In the example below, the correlation line is used to convert the IGDS features from
UTM zone 10 based on Datum NAD 27 to Lat/Long coordinates based on Datum
NAD 83, for only the road features in the dataset.
# Specify the correlation lines from IGDS to Shape.
# The Reproject command is placed on the Shape line.
# When converting data from IGDS to Shape the
# coordinates are converted from UTM zone 10 based on
# NAD 27 to Lat/Long coordinates based on NAD 83. When
# converting data from Shape to IGDS the coordinates
# are converted from Lat/Long coordinates (NAD83) to
# UTM zone 10 (NAD 27).
IGDS 23 igds_type igds_line
Shape roads @Reproject(UTM27-10, LL83)
The second example illustrates how to use the coordinate conversions to change
coordinate values which are stored as attributes of a feature. When translating from
SAIF to Shape the coordinate geometry is translated as in the previous example. The
features also have inside point coordinates stored in the attributes insideX and
insideY which must also be translated. These are done using a second
@Reproject command invocation.
SAIF Lake::MOF insideX %x insideY %y
Shape lake insideX %x insideY %y \
@Reproject(UTM27-10, LL83) \
@Reproject(UTM27-10, LL83, insideX, insideY)
@Rotate2D FME FUNCTION REFERENCE
A-82 FME Reference Manual Version 2.0
A.35 @Rotate2D
@Rotate2D(<degrees> [,<rotateX>, <rotateY>])
FUNCTION TYPE: FEATURE
ARGUMENTS:
A.35.1 Configuration
This function does not accept configuration lines.
A.35.2 Description
This command rotates features in a counter-clockwise direction about the specified
point by the specified angle number of degrees. If the point around which the rotation
is to be performed is not specified then the feature is rotated about the origin.
A.35.3 Inverse Operation
The function rotates the feature in the clockwise direction when invoked on the
source line of a transformation specification.
A.35.4 Example
In the example below the building is rotated 90 degrees about the point identified by
the attributes centroidX, and centroidY. When going from SHAPE to MIF the
rotation is in the counter-clockwise direction and when going from MIF to SHAPE
the rotation is in the clockwise direction.
SHAPE building
MIF building @Rotate2D(90, ¢roidX, ¢roidY)
Name Range Description Optional
<degrees> real value Specifies the angle by which the feature will be
rotated, measured in degrees counterclockwise.
No
<rotateX> real value The x-coordinate about which features are
rotated. If not specified then the feature is
rotated about the origin.
Yes
<rotateY> real value The y-coordinate about which features are
rotated. If not specified then the feature is
rotated about the origin.
Yes
A-83 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @RoundOffCoords
A.36 @RoundOffCoords
@RoundOffCoords((x|y|z),<axis>)
FUNCTION TYPE: FEATURE
ARGUMENTS:
A.36.1 Configuration
This function does not accept configuration lines
A.36.2 Description
This function rounds off the coordinates of the passed axis to the passed in precision.
This is often used after doing a reprojection when translating to an ASCII output
format to reduce the volume of ASCII data output and to remove superfluous decimal
points.
Any consecutive points which become duplicates as a result of the rounding are
thinned by removing the redundant points.
Name Range Description Optional
<axis> (x|y|z) The first parameter controls the axis whose
coordinates will be rounded.
No
<precision> real number The second parameter controls the number of decimal
places of precision that the coordinates will be
rounded to. A value of 0 will cause all coordinates
along the specified axis to be rounded to the nearest
integer. A value of 1 will cause rounding to the
nearest tenth of a unit. Negative values are allowed.
A value of -1 will cause rounding to the nearest 10.
The precision can be a floating point number. This
can be used to snap all coordinates to an arbitrary
grid. The formula used to do the rounding is:
factor = pow(10.0,<precision>)
newCoordValue = factor *
(RoundToInt(oldCoordValue/factor))
So if precision is set to the log10(2) =
0.3010299956639812, all coordinates are
rounded to the nearest 1/2 unit.
Similarily, if precision is set to log10(0.5) =
0.3010299956639812, all coordinates are
rounded to the nearest even unit.
No
@RoundOffCoords FME FUNCTION REFERENCE
A-84 FME Reference Manual Version 2.0
A.36.3 Inverse
This function has no inverse.
A.36.4 Example
In the example below, the x and y axis have their coordinates rounded off to the
nearest hundredth of a ground unit after being projected from lat/long to UTM. The
z axis is not touched.
FACTORY_DEF SAIF SamplingFactory \
INPUT FEATURE_TYPE * \
@Reproject(LL-83,UTM10-83) \
@RoundOffCoords(x,2) \
@RoundOffCoords(y,2)
In this second example, the x coordinates are rounded to the nearest half unit, and the
y coordinates are rounded to the nearest multiple of 5. The z coordinates are
truncated to the nearest whole unit.
MACRO Log10_2 0.3010299956639812
MACRO MinusLog10_5 -0.69897000433601886
FACTORY_DEF SAIF SamplingFactory \
INPUT FEATURE_TYPE * \
@RoundOffCoords(x, $(Log10_2) ) \
@RoundOffCoords(y, $(MinusLog10_5) ) \
@RoundOffCoords(z, 0)
A-85 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @SAIFAngle
A.37 @SAIFAngle
@SAIFAngle( <angle> )
FUNCTION TYPE: ATTRIBUTE
ARGUMENTS:
A.37.1 Configuration
This function does not accept configuration lines.
A.37.2 Description
This function converts between SAIF-style angles (measured clockwise from vertical
in degrees) to angles measured counterclockwise from horizontal, which are more
widely used.
A.37.3 Inverse Operation
The inverse angle is converted from an angle measured counterclockwise from
horizontal to a SAIF style angle (measured clockwise from vertical).
A.37.4 Example
In the example below, the SAIF position.geometry.alignment attribute is
set to the @SAIFAngle equivalent of the rotation specified within the
igds_rotation attribute when features are translated from IGDS to SAIF. When
features are translated from SAIF to IGDS, the @SAIFAngle call converts the angle
back to the original IGDS value.
Name Range Description Optional
<angle> Real
Number
Angle to convert from a counterclockwise
angle oriented from the horizontal to an angle
oriented clockwise from vertical (SAIF style).
No
ccw
angle
SAIF
angle
@SAIFAngle FME FUNCTION REFERENCE
A-86 FME Reference Manual Version 2.0
IGDS 7 igds_color 37 igds_style 0 \
igds_class 0 igds_weight 1 \
igds_type igds_rotation %rot
SAIF Building::TRIM \
position.geometry.Class AlignedPoint \
position.geometry.alignment @SAIFAngle(%rot)
A-87 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Scale
A.38 @Scale
@Scale(<factor>)
@Scale(<xFactor>, <yFactor>)
@Scale(<xFactor>, <yFactor>, <zFactor>)
FUNCTION TYPE: FEATURE
ARGUMENTS:
A.38.1 Configuration
This function does not accept configuration lines.
A.38.2 Description
This command scales the coordinates of the passed in feature by the multipliers
specified. If just one value is specified, then X, Y, and Z are scaled by the specified
amount. If two values are specified, then X and Y are scaled as specified and the Z
component is left untouched. If three values are specified, then X, Y, and Z are scaled.
A.38.3 Inverse Operation
The function divides the features by the specified scaling factor(s).
A.38.4 Example
In the example below the building coordinates are multiplied by a factor of 2 when
going from SHAPE to MIF. When going from MIF to SHAPE, the building
coordinates are divided by a factor of 2.
SHAPE building
MIF building @Scale(2.0)
Name Range Description Optional
<factor> real value All X, Y, and Z coordinates are multiplied
by these scaling factors.
No
<xFactor> real value Specifies the scale factor for the x
component of the feature coordinates.
No
<yFactor> real value Specifies the scale factor for the y
component of the feature coordinates.
No
<zFactor> real value Specifies the scale factor for the z
component of the feature coordinates.
No
@Split FME FUNCTION REFERENCE
A-88 FME Reference Manual Version 2.0
A.39 @Split
@Split( <splitStr>, (<delimiter>|<formatSpec>),
<attrName1>, <attrName2> [, <attrNameN>]* )
FUNCTION TYPE: FEATURE
ARGUMENTS:
A.39.1 Configuration
This function does not accept configuration lines.
A.39.2 Description
The @Split command breaks a string into its component parts, and assign those
parts to attributes of a feature. It is used to facilitate translation when a single attribute
value in one system implies a set of attribute values in another system.
For example, when @Split is invoked on a destination line with these parameters:
@Split(top|left,|,vertical,horizontal)
Name Range Description Optional
<splitStr> string The string to split into component pieces. It
should contain enough component parts,
separated by the delimiter character, to assign
to each of the attribute names listed.
No
<delimiter> single
character
The character to be used to divide the
<splitStr> into its component pieces.
Yes
<formatSpec> #s[#s]+ A format specification may be used in place
of a delimiting character. The format
specification consists of a series of field
widths, separated by s characters. The
<splitStr> will be created or broken apart
according to the widths specified. The format
specification can be distinguished from the
delimiting character since the format string
must always have more than one character in
it.
Yes
(though either a
delimiter charac-
ter or a format
specification
must be present.)
<attrName1>,
<attrName2>,
<attrNameN>
string The names of the attributes which will be
assigned the pieces of <splitStr> when it is
split apart. The first component of
<splitStr> will be assigned to the first
attribute name, the second component to the
second attribute, and so on. The number of
attribute names must match the number of
component parts of <splitStr>.
At least two
attribute names
are required
A-89 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Split
the vertical attribute in the feature is assigned a value of top, and the
horizontal attribute is assigned a value of left.
Any character may be chosen to be the delimiter for the input string. However, it is
critical that the number of attribute names listed matches the number of component
parts present in the input string.
The field attribute names may be names of attribute lists. List attribute names contain
empty {} in their names. If the field names are lists, then the input string is assumed
to be a list itself, and each element in the input string is broken into pieces and
assigned to next element in the attribute list. The {} are filled in with element
numbers (starting at 0) as the list is unpacked.
TIP: If one attribute is a list, then they all must be.
A.39.3 Inverse Operation
When invoked on a source line of a transfer specification, @Split is invoked in the
inverse direction. In this case, it will combine the values of the attribute names listed
into a single string, separated by the delimiter character, and assign the result to the
transfer variable present as the first argument.
For example, if the below clause were invoked on the source line of a transfer
specification, the values of the vertical and horizontal attributes would be
joined together, separated by a | character, and assigned to the %allTogether
transfer variable.
@Split(%allTogether,|,vertical,horizontal)
If the attribute named are lists, then each element of the lists is joined together, and
the transfer variable is set to a list of combined values.
A.39.4 Example
In the first example, a single character string field in a Shape file is used to store the
justification code of some text features. When translation from SAIF to SHAPE
occurs, the values of the SAIF text alignment attributes are concatenated together,
separated by a |, and assigned to the %justification transfer variable. The JUST
attribute of the Shape feature then receives this value. If the vertical alignment value
in the SAIF feature originally was TOP, and the horizontal value was LEFT, then
JUST would end up being set to TOP|LEFT.
When translation from SHAPE to SAIF occurs, the %justification transfer
variable is assigned the value of the Shape features JUST attribute. The @Split
command on the SAIF line, which is the destination portion of the transfer
@Split FME FUNCTION REFERENCE
A-90 FME Reference Manual Version 2.0
specification, is run in the forward direction and breaks the %justification
value into pieces and assigns them to the text alignment attributes of the SAIF text
feature. If the JUST attribute in the Shape feature was originally BOTTOM|RIGHT,
then the vertical alignment value in the SAIF feature would be BOTTOM, and the
horizontal value would be RIGHT.
SAIF Text::TRIM @Split(%justification,|, \
textOrSymbol.alignment.vertical, \
textOrSymbol.alignment.horizontal)
SHAPE text JUST %justification
In the second example, this is extended slightly to consider translation from SAIF to
IGDS. In IGDS, a single numeric code is used to encode the horizontal and vertical
text alignments. However, in SAIF these are separated into two fields. To
accommodate this translation, the @Lookup function is used in conjunction with
Hint:
Lookup JustLUT top|left 1 bottom|right 2
SAIF Text::TRIM @Split(%justification,|, \
textOrSymbol.alignment.vertical, \
textOrSymbol.alignment.horizontal)
IGDS 23 igds_type igds_text ... \
igds_justification @Lookup(JustLUT,%justification)
When translation is done from SAIF to IGDS, the @Split runs in reverse and glues
together the values of the vertical and horizontal text alignment attributes in
the SAIF feature. The resulting string is placed into the %justification transfer
variable. To fill in the attributes for the IGDS feature, the @Lookup runs in the
forward direction since it is on a destination line. It looks up the value of the
%justification transfer variable (for example, bottom|right) in the
JustLUT, and returns the result (for example, 2), which is stored in
igds_justification.
TIP: @Split is often used in conjunction with @Lookup to decode a numeric code into its components.
When translation is done from IGDS to SAIF, things work as before but in reverse.
The IGDS line is the source, so the @Lookup runs in reverse. It looks up the value
of the igds_justification on the right hand side of the JustLUT, and places
bottom|right in the %justification transfer variable. Once the new SAIF
feature has been created, the @Split runs in the forward direction. It splits the value
of %justification, which is bottom|right, into two pieces, and assigns
them to the vertical and horizontal attributes of the SAIF feature.
The third example shows the use of @Split in conjunction with attribute lists. This
situation occurs when dealing with multi-line text data. This example works in
exactly the same manner as the previous one, except that the transfer variable contains
a list. The @Split and @Lookup operate on this list, instead of just a single value.
A-91 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Split
Lookup JustLUT top|left 1 bottom|right 2
SAIF Text::TRIM textOrSymbol.Class TextMultiLine \
@Split(%justification,|, \
textOrSymbol.textLines{}.alignment.vertical, \
textOrSymbol.textLines{}.alignment.horizontal)
IGDS 23 igds_type igds_multi_text ... \
elements{}.igds_justification @Lookup(JustLUT,%justification)
The fourth example shows the use of @Split in conjunction with date fields. In this
case, it is used to concatenate the year, month and day together into a single string,
when the original SAIF data had them in separate fields but the destination Shape file
required them to be placed in a single field. When translation from Shape back to
SAIF occurs, the split command will break the yyyymmdd data held in the Shape
attribute into the SAIF year, month, and day.
SAIF ForestStand::MOF position.geometry.Class BoundedArea \
@Split(%yyyymmdd,4s2s2s, \
measurementDate.year, \
measurementDate.month, \
measurementDate.day)
SHAPE stands MEASDATE %yyyymmdd
@SupplyAttributes FME FUNCTION REFERENCE
A-92 FME Reference Manual Version 2.0
A.40 @SupplyAttributes
@SupplyAttributes(<attrName>,<attrValue>
[,<attrName>,<attrValue>]*)
FUNCTION TYPE: FEATURE
ARGUMENTS:
A.40.1 Configuration
This function does not accept configuration lines.
A.40.2 Description
The function takes a list of (attribute name, attribute value) pairs and creates attributes
with the specified names in the feature, and assigns to them the values provided.
A.40.3 Inverse Operation
This function does nothing when invoked in the reverse direction, which happens
when it appears on the source portion of a transfer specification.
A.40.4 Example
When executed in the forward direction, the SupplyAttributes function assigns
values to the attributes mif_type and mif_pen_width. When executed in the
backward direction the SupplyAttributes function has no effect.
SDE roads
MIF roads @SupplyAttributes mif_type, polyline,
mif_pen_width, 1)
Name Range Description Optional
<attrName> string The name of the attribute which data is to be
supplied.
No
<attrValue> string The value to be assigned to the attribute. No
A-93 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @SupplyAttributes
In this second example, the SupplyAttributes function is used in conjunction
with the value-of operator (&) to copy the value of the standId attribute to the
nodeNum attribute.
FACTORY_DEF SAIF TeeFactory \
INPUT FEATURE_TYPE ForestStand::MOF \
OUTPUT FEATURE_TYPE * \
@SupplyAttributes(nodeNum,&standId)
@Timestamp FME FUNCTION REFERENCE
A-94 FME Reference Manual Version 2.0
A.41 @Timestamp
@Timestamp( <formatString> )
FUNCTION TYPE: ATTRIBUTE
ARGUMENTS:
A.41.1 Configuration
This function does not accept configuration lines.
A.41.2 Description
This functions returns the current time, formatted according to the specification
provided in the formatString parameter. Ordinary characters placed in the
format string are copied to the output without conversion. Conversion specifiers are
introduced by a ^ character, and are replaced in the formatString as follows:
Name Range Description Optional
<formatString> string Specifies how the current time will be
formatted when it is output.
No
Character Replacement
^a The abbreviated weekday name according to the current
locale.
^A The full weekday name according to the current locale.
^b The abbreviated month name according to the current
locale.
^B The full month name according to the current locale.
^c The preferred date and time representation for the current
locale.
^d The day of the month as a decimal number (range 0 to 31).
^H The hour as a decimal number using a 24-hour clock (range
00 to 23).
^I The hour as a decimal number using a 12-hour clock (range
01 to 12).
^j The day of the year as a decimal number (range 001 to 366).
^m The month as a decimal number (range 00 to 12).
^M The minute as a decimal number.
A-95 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @Timestamp
For example,
@Timestamp("^Y^m^d")
will return 19960913, if it was invoked on September 13, 1996. Similarly, on the
same day,
@Timestamp(The date is: ^c)
would return The date is: Fri Sep 13 16:32:48 PDT 1996" (without
the quotes).
A.41.3 Inverse Operation
This function does nothing if invoked in the inverse direction.
A.41.4 Example
The below example adds a timestamp attribute to each feature that flows through the
system:
FACTORY_DEF IGDS SamplingFactory \
INPUT FEATURE_TYPE * date @Timestamp(^Y^m^d) \
SAMPLE_RATE 1
^p Either am or pm according to the given time value, or the
corresponding strings for the current locale.
^S The second as a decimal number.
^U The week number of the current year as a decimal number,
starting with the first Sunday as the first day of the first
week.
^W The week number of the current year as a decimal number,
starting with the first Monday as the first day of the first
week.
^w The day of the week as a decimal, Sunday being 0.
^x The preferred date representation for the current locale
without the time.
^X The preferred time representation for the current locale
without the date.
^y The year as a decimal number without a century (range 00
to 99).
^Y The year as a decimal number including the century.
^Z The time zone or name or abbreviation.
Character Replacement
@XValue FME FUNCTION REFERENCE
A-96 FME Reference Manual Version 2.0
A.42 @XValue
@XValue( [<x-value>] [, Reset ] )
FUNCTION TYPE: ATTRIBUTE OR FEATURE
ARGUMENTS:
A.42.1 Configuration
This function does not accept configuration lines.
A.42.2 Description
This function may be used as either an attribute value function or a feature function.
When used as a feature function, the optional x-value parameter must be specified.
In this case, the @XValue function stores the specified value as the x coordinate of
the feature. If the optional Reset parameter is specified, then the coordinates of the
feature are first cleared before the x value is added. If it is not specified, then the x
value is added to the current features geometry, either extending a line if the feature
was linear, or creating a Point-In-Polygon feature out of a polygonal feature.
When used as an attribute value function, the x-value parameter is not specified.
In this case, @XValue returns the value of the first x coordinate of the feature. This
value is then stored in the attribute.
A.42.3 Inverse Operation
If the optional x-value parameter is not specified and the @XValue function is
encountered on the source line of an attribute transfer, it does nothing.
However, when @XValue is used as a feature function (the x-value parameter was
specified as a transfer variable) and it is encountered on a source line, it will extract
the value of the first x coordinate in the feature and assign this value to the transfer
variable passed to it.
Name Range Description Optional
<x-value> real number The value of the x coordinate to store in the
feature.
Yes
A-97 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @XValue
A.42.4 Example
In the first example, @XValue, @YValue, and @ZValue are used as feature
functions in conjunction with the ElementFactory. This factory takes a feature that
has an attribute list on it (in this example, textOrSymbol.characters{}), and
outputs a new feature for each element in the list. However, each output feature will
not have any coordinates unless they are added by the @XValue, @YValue, and
@ZValue functions. Since functions invoked in factory clauses are always executed
in the forward direction, these functions are invoked on the ElementFactorys
OUTPUT ELEMENT line to set each output features coordinates from its attribute
values.
The SAIF attribute names in this example have been shortened and are not accurate.
FACTORY_DEF SAIF ElementFactory \
INPUT FEATURE_TYPE Toponymy::TRIM \
textOrSymbol.Class TextOnCurve \
LIST_NAME textOrSymbol.characters{} \
OUTPUT ELEMENT FEATURE_TYPE Toponymy::TRIM \
textOrSymbol.Class TextFromMulti \
@XValue(&x) \
@YValue(&y) \
@ZValue(&z)
In this example, an input feature entering the factory looks like:
Feature Type: Toponymy::TRIM
Attribute Name Value
textOrSymbol.Class TextOnCurve
textOrSymbol.characters{0}.x 5001
textOrSymbol.characters{0}.y 40001
textOrSymbol.characters{0}.z 101
textOrSymbol.characters{0}.text Hello
textOrSymbol.characters{1}.x 5002
textOrSymbol.characters{1}.y 40002
textOrSymbol.characters{1}.z 103
textOrSymbol.characters{1}.text There
Coordinates: None
@XValue FME FUNCTION REFERENCE
A-98 FME Reference Manual Version 2.0
This feature will be broken into two output features by the ElementFactory. Before
the functions are executed, the first output feature looks like:
After the functions are run, the feature looks like:
In the second example, @Xvalue and @YValue are used as attribute value
functions in conjunction with the ListFactory. This factory takes in a number of
features, and forms their attributes into a giant attribute list on the output feature. The
@XValue and @YValue functions are used in this situation to extract the values of
the x and y coordinates, and supply them as attributes to the feature as it enters the
ListFactory.
FACTORY_DEF SHAPE ListFactory \
INPUT FEATURE_TYPE tpnymy x @XValue() y @YValue() \
LIST_NAME elements{} \
OUTPUT LIST FEATURE_TYPE tpnymylist
Feature Type: Toponymy::TRIM
Attribute Name Value
textOrSymbol.Class TextFromMulti
x 5001
y 40001
z 101
text Hello
Coordinates: None
Feature Type: Toponymy::TRIM
Attribute Name Value
textOrSymbol.Class TextFromMulti
x 5001
y 40001
z 101
text Hello
Coordinates: 5001,40001,101
A-99 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @XValue
In this example, an input feature about to enter the factory looks like:
Notice the addition of the x and y attributes after the functions are run as the element
enters the factory:
Feature Type: Toponymy::TRIM
Attribute Name Value
textOrSymbol.Class TextLine
text Hello
Coordinates: 5001,40001
Feature Type: Toponymy::TRIM
Attribute Name Value
textOrSymbol.Class TextLine
x 5001
y 40001
text Hello
Coordinates: 5001,40001
@YValue FME FUNCTION REFERENCE
A-100 FME Reference Manual Version 2.0
A.43 @YValue
@YValue( [<y-value>] )
FUNCTION TYPE: ATTRIBUTE OR FEATURE
ARGUMENTS:
A.43.1 Configuration
This function does not accept configuration lines.
A.43.2 Description
This function is identical in its operation to the @XValue function, except that it
operates on the Y coordinate rather than the X coordinate. It may be used as either an
attribute value function or a feature function. When used as a feature function, the
optional y-value parameter must be specified. In this case, the @YValue function
stores the specified value as the y coordinate of the feature.
When used as an attribute value function, the y-value parameter is not specified.
In this case, @YValue returns the value of the first y coordinate of the feature. This
value is then stored in the attribute.
A.43.3 Inverse Operation
If the optional y-value parameter is not specified and the @YValue function is
encountered on the source line of an attribute transfer, it does nothing.
However, when @YValue is used as a feature function (the y-value parameter was
specified as a transfer variable) and it is encountered on a source line, it will extract
the value of the first y coordinate in the feature and assign this value to the transfer
variable passed to it.
A.43.4 Example
See the example for @XValue.
Name Range Description Optional
<y-value> real number The value of the y coordinate to store in the
passed in feature.
Yes
A-101 FME Reference Manual Version 2.0
FME FUNCTION REFERENCE @ZValue
A.44 @ZValue
@ZValue( z-value )
FUNCTION TYPE: ATTRIBUTE
ARGUMENTS:
A.44.1 Configuration
This function does not accept configuration lines.
A.44.2 Description
The @ZValue function stores the specified value as the z coordinate in the feature.
If the feature contains multiple coordinates then all of the coordinates are set to the
specified z-value.
A.44.3 Inverse Operation
When executed in the inverse direction (on the source line of a transformation
specification), the z value of the feature is assigned to the transfer variable passed to
the @ZValue function. This allows the same ZValue statement to be used for both
directions of a translation.
A.44.4 Example
In the below example, when the translation proceeds from SHAPE to SAIF, the value
of the SHAPE height attribute is assigned to the transfer variable %height. It is
then passed to the ZValue function, resulting in the z coordinate of the SAIF feature
being set to the attribute value of height.
In the inverse direction the z coordinate value of the SAIF feature is placed into the
transfer variable %height which is then stored in the height attribute of the
outgoing SHAPE feature.
SHAPE roads height %height
SAIF Roads::TRIM @ZValue(%height)
Name Range Description Optional
<z-value> real number The value of the z coordinate stored in the
feature.
No
@ZValue FME FUNCTION REFERENCE
A-102 FME Reference Manual Version 2.0
B-1 FME Reference Manual Version 2.0
B
B FACTORY REFERENCE
B.1 AggregateFactory
B.1.1 Syntax
FACTORY_DEF <ReaderKeyword> AggregateFactory \
[INPUT FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* \
]* \
[LIST_NAME <list name>{}] \
[GROUP_BY [<attribute name>]+]* \
[OUTPUT AGGREGATE|SINGLETON \
FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function>]* ]*
B.1.2 Overview
This factory takes a series of features matching an input specification and
aggregates their geometries together based on attribute values specified by the
GROUP_BY clause. One feature is output for each group resulting from the
GROUP_BY clause. If no GROUP_BY clause is specified then all features fall
into the same group and a single feature is output.
The features output from the AggregateFactory have will have the combined
attribution from all the features which were combined to make up the
aggregate.
AggregateFactory FACTORY REFERENCE
B-2 FME Reference Manual Version 2.0
The optional LIST_NAME clause is used to associate attributes with each member of
the aggregate. When the aggregate is created, all attributes of each feature joining the
aggregated are added as members of the attribute list specified. The index in the list
corresponds to the index of the features geometry in the aggregate.
This provides functionality very similar to the ListFactory. Either the
ElementFactory or the DeaggregateFactory can then be used to extract the attributes
from the list.
TIP: When large aggregates are created, the list can require a great deal of memory. In some situations, the
@KeepAttributes should be used in the input clause to the AggregateFactory to reduce the number of
attributes which will become part of the list.
TIP: This factory is similar to the ListFactory. The ListFactory aggregates attribution, while the
AggregateFactory aggregates geometry.
Features with geometries aggregrated by this factory may be routed to formats which
accommodate aggregates for output. Currently, only SAIF and Shape support
geometric aggregate features. SAIF supports heterogeneous aggregation, allowing
points, polygons, donuts, point-in-polygons, and lines to be aggregated together into
single features. Shape supports only homogenous aggregates of either polygons/
donut polygons or lines.
TIP: The DeaggregateFactory is used to split aggregates up into their components.
If the output SINGLETON clause is specified, features that are the only members
of their group are output unchanged. If it is not specified, an aggregate containing
only one geometry will be output for the group.
B.1.3 Assumptions
None.
B.1.4 Output Tags
The AggregateFactory supports the following output tags.
Tag Description
AGGREGATE The features which have aggregate geometry. If the SINGLETON tag is
specified then each of these features will have at least two geometries in
it.
SINGLETON Applies to features which are the only members in a group. If this isnt
specified then such features are output using the AGGREGATE tag
creating a geometric aggregate with only one geometry in it. If an
OUTPUT SINGLETON clause is specified, such features are output
unchanged.
B-3 FME Reference Manual Version 2.0
FACTORY REFERENCE AggregateFactory
B.1.5 Example
The following example illustrates the use of the AggregateFactory to merge linear
contour features together based on their elevation value.
FACTORY_DEF SAIF AggregateFactory \
INPUT FEATURE_TYPE Contour::TRIM \
GROUP_BY position.geometry.value \
OUTPUT AGGREGATE FEATURE_TYPE ContourAggregate
TIP: Since no OUTPUT SINGLETON clause is specified, groups which have only 1 element in them will still
be output as an aggregate.
The below features match the input specification of this factory definition, and will
enter the factory:
The factory will merge the above features together, producing the below aggregate
feature. This feature could be output to Shape or SAIF.
TIP: The qualifier attribute was copied from the first feature that was encountered in the group.
Feature Type: Contour::TRIM
Attribute Name Value
position.geometry.qualifier definite
position.geometry.value 20
Coordinates: (477553,5360181,20) (477554,5360182,20)
Feature Type: Contour::TRIM
Attribute Name Value
position.geometry.qualifier indefinite
position.geometry.value 20
Coordinates: (377553,4360181,20) (377554,4360182,20)
Feature Type: ContourAggregate
Attribute Name Value
position.geometry.qualifier definite
position.geometry.value 20
Coordinates:
Line 1: (477553,5360181,20) (477554,5360182,20)
Line 2: (377553,4360181,20) (377554,4360182,20)
ArcFactory FACTORY REFERENCE
B-4 FME Reference Manual Version 2.0
B.2 ArcFactory
B.2.1 Syntax
FACTORY_DEF <ReaderKeyword> ArcFactory \
[INPUT FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* \
]* \
[GROUP_BY [<attribute name>]+]* \
(END_NODED|VERTEX_NODED) \
[OUTPUT LINE FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function>]* \
]
B.2.2 Overview
This factory takes linear or polygonal features, puts them into a topology model, and
outputs their component arcs with all duplicates removed. This factory is useful for
determining the arcs required to divide a surface into regions, or to join together arcs
which have the same attribute values. The input features may be grouped into separate
topology models based on attribute values specified in the GROUP_BY clause. No
attributes are carried across from the INPUT features to the output features. However,
all OUTPUT features will have the GROUP_BY attributes added to them before being
output.
The END_NODED and VERTEX_NODED directives tell the factory about the topology
of the input features. END_NODED indicates that all features begin and end at
topologically significant points, and that none of their vertices connects with any
other features. VERTEX_NODED indicates that every vertex may be topologically
significant, and must be considered when looking to join features together.
TIP: END_NODED does not make sense when polygons are input to the ArcFactory.
B.2.3 Assumptions
This factory assumes that all input lines are already topologically noded. The factory
assumes that the input polygons and arcs have already been processed by a GIS
product which has ensured that the data is clean. The ArcFactory does not provide
any snapping capabilities.
B-5 FME Reference Manual Version 2.0
FACTORY REFERENCE ArcFactory
B.2.4 Output Tags
The ArcFactory supports the following output tags.
B.2.5 Example
The following example defines an ArcFactory which will join together all road
features which have the same number of lanes. The factory is activated only when
reading from SAIF. When features leave the factory the only attribute which they will
have is numberOfLanes.
FACTORY_DEF SAIF ArcFactory \
INPUT FEATURE_TYPE Road::TRIM \
GROUP_BY numberOfLanes \
END_NODED \
OUTPUT LINE FEATURE_TYPE Road::TRIM
Tag Description
LINE All linear features produced by this factory are output according to the
OUTPUT clause identified by this tag.
ChoppingFactory FACTORY REFERENCE
B-6 FME Reference Manual Version 2.0
B.3 ChoppingFactory
B.3.1 Syntax
FACTORY_DEF <ReaderKeyword> ChoppingFactory \
[INPUT FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* \
]* \
MAX_VERTICES <maxvertices> \
[CHOP_POLYGONS] \
[OUTPUT (UNTOUCHED|CHOPPED) \
FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function>]* \
]*
B.3.2 Overview
This factory ensures that all features it outputs have less than or equal to
<maxvertices> vertices.
If an input feature has more than this number of vertices, it will be chopped into
several smaller features. Each new feature will have <maxvertices> vertices,
except for the last one, which may have fewer than <maxvertices> vertices. All
the new features will have the same attributes as the original feature had, and will be
output via the CHOPPED clause.
If the feature had fewer than <maxvertices> vertices, then it is output via the
UNTOUCHED clause.
If the CHOP_POLYGONS directive is specified, then polygonal features (possbily
with holes) which enter the factory and have more than <maxvertices> vertices
will be sliced into smaller polygons. The original polygon will be cut be horizontal
and vertical lines, until each resulting polygon has less than the maximum allowed
number of vertices. All polygons produced with this method will have the same
attributes as the original polygon before the chopping. If the resulting polygons were
dissolved back together, the original polygon would be the result.
This factory is used to reduce the number of coordinates in a single feature so that it
may later be stored in a system which limits feature sizes.
B.3.3 Assumptions
None
B-7 FME Reference Manual Version 2.0
FACTORY REFERENCE ChoppingFactory
B.3.4 Output Tags
The ChoppingFactory supports the following output tags.
B.3.5 Example
In this example, a shape file containing linear features is converted into a DBF file
that holds the feature coordinates, on pair of coordinates per row. Each feature is
assigned a unique ID before it is broken into two point fragments.
The result is a table looking like this:
# ------------------------------------------------------------
# These macros control the type of the feature ID that is assigned
# to each feature as it goes by. They also control the
# method of generation of the feature ID.
# These settings generate sequential numbers, which will be unique
# within this translation. The @GOID function could be used
# to generate globally unique identifiers if this was required.
MACRO _FeatIdType number(8,0)
MACRO _FeatIdGeneration @Count(FeatureNumber)
# ------------------------------------------------------------
READER_TYPE SHAPE
WRITER_TYPE TABLE
SHAPE_DATASET .
TABLE_DATASET .
LOG_FILENAME dbf.log
Tag Description
UNTOUCHED All input features which have <= MAX_VERTICES vertices are output
untouched here.
CHOPPED Features created by chopping the original feature into smaller pieces are
output here. Each feature will contain <= MAX_VERTICES vertices, but
will have all the attributes of the original feature.
Feature ID X1 Y1 X2 Y2
id0 x0_1 y0_1 x0_2 y0_2
id0 x0_2 y0_2 x0_3 y0_3
id0 x0_3 y0_3 x0_4 y0_4
id1 x1_1 y1_1 x1_2 y1_2
id1 x1_2 y1_2 x1_3 y1_3
ChoppingFactory FACTORY REFERENCE
B-8 FME Reference Manual Version 2.0
# ------------------------------------------------------------
# Define the input data source
SHAPE_DEF road \
SHAPE_GEOMETRY shape_arc \
LENGTH number(12,3) \
ROADTYPE char(30)
# ------------------------------------------------------------
# This table holds the geometry of the roads
TABLE_DEF roadgeom DBF roadgeom.dbf \
FEAT_ID $(_FeatIdType) \
X1 number(32,15) \
Y1 number(32,15) \
X2 number(32,15) \
Y2 number(32,15)
# ------------------------------------------------------------
# Now, take the geometry and chop it into features each containing
# two points. As the feature enters the factory it is assigned
# a unique ID. This ID is replicated on each of the output
# CHOPPED features.
FACTORY_DEF SHAPE ChoppingFactory \
INPUT FEATURE_TYPE * id $(_FeatIdGeneration) \
MAX_VERTICES 2 \
OUTPUT UNTOUCHED FEATURE_TYPE * \
OUTPUT CHOPPED FEATURE_TYPE *
# ------------------------------------------------------------
# Now set up the transfer specifications to route the features
# to their final resting spot.
SHAPE roadGeometry \
id %fid
TABLE roadgeom \
FEAT_ID %fid \
X1 @Coordinate(X,0) \
Y1 @Coordinate(Y,0) \
X2 @Coordinate(X,1) \
Y2 @Coordinate(Y,1)
B-9 FME Reference Manual Version 2.0
FACTORY REFERENCE ClippingFactory
B.4 ClippingFactory
B.4.1 Syntax
FACTORY_DEF <ReaderKeywordClippingFactory> \
[ INPUT CLIPPER FEATURE_TYPE <featureType \
[<attrName> <attrValue>]* ] * \
[ INPUT CLIPPEE FEATURE_TYPE <featureType \
[<attrName> <attrValue>]* ] * \
[ OUTPUT CLIPPED_INSIDE FEATURE_TYPE <featureType \
[<attrName> <attrValue>]* ] \
[ OUTPUT CLIPPED_OUTSIDE FEATURE_TYPE <featureType \
[<attrName> <attrValue>]* ] \
[ OUTPUT INSIDE FEATURE_TYPE <featureType \
[<attrName> <attrValue>]* ] \
[ OUTPUT OUTSIDE FEATURE_TYPE <featureType \
[<attrName> <attrValue>]* ] \
[ OUTPUT NONPOLY_CLIPPER FEATURE_TYPE <featureType \
[<attrName> <attrValue>]* ] \
[ OUTPUT EXTRA_CLIPPER FEATURE_TYPE <featureType \
[<attrName> <attrValue>]* ]
B.4.2 Overview
This factory is used to perform a geometric clipping operation on input features. It
takes two types of features identified by the CLIPPER and CLIPPEE input tags.
A clipping feature is identified by the tag CLIPPER. This feature identifies the area
against which all the CLIPPEE features are processed. This feature must be a
polygon. Any non-polygonal clipping features which are encountered are output via
the NONPOLY_CLIPPER tag. For each instance of the factory, the first polygonal
feature which matches the CLIPPER specification is used as the clipping polygon,
and other polygonal features are output immediately via the EXTRA_CLIPPER
tagged output clause.
The clippee features are identified by the tag CLIPPEE. These are clipped such that
features which are totally within the CLIPPER feature are output from the factory via
the INSIDE tagged output clause.
CLIPPEE features which intersect the CLIPPER feature are broken up into peices
with those peices on the inside of the CLIPPER feature being output via the
CLIPPED_INSIDE tags. The portions which are outside the clipping area are output
via the CLIPPED_OUTSIDE tagged output clauses.
Features which are completely outside of the CLIPPER feature are output via the
OUTSIDE tagged output clause.
All of the output tags are optional.
ClippingFactory FACTORY REFERENCE
B-10 FME Reference Manual Version 2.0
This factory is most commonly used when an input data source covers an area much
greater than the area of interest for the destination dataset. This factory enables the
FME to perform some rudimentary spatial selection operations in addition to its
attribution selection capabilities.
The factory may output aggregates, and in fact aggregates may be output in cases
where a non-aggregate is input. Imagine a windy river which crosses into and out of
the clipping region several times. The portion of the river inside the clipping region
would be output as one aggregate of linear geometries and the portion outside the
clipping region would be output as another aggregate of linear peices representing the
portion outside the clipping region.
TIP: As CLIPPEE features must be held by the factory until the CLIPPER feature arrives, care should be taken
to ensure that the CLIPPER feature arrives before any CLIPPEE features whereever possible.
B.4.3 Example
In this example there are a collection of shape files being filtered by a polygonal
feature stored in a file called boundry.
# =============================================================
# This factory is used to clip all features within the clip window
# defined by boundry and outputs the contained features and the
# portion of the features which are within the window. Features and
# portions of features which are outside the clipping window are
# discarded.
# The omission of the two output clauses dealing with outside
# features causes such features to be thrown away.
#
# The factory also uses the two error clauses to output any erroneous
# features which are encountered. The mapping file fragment shows
# how the data translation can be aborted when an erroneous
# condition occurs. If an erroneous condition occurs, the bad
# feature is logged and the translation is aborted via the
# @Abort() function
FACTORY_DEF SHAPE ClippingFactory \
INPUT CLIPPER FEATURE_TYPE boundry \
INPUT CLIPPEE FEATURE_TYPE lots \
INPUT CLIPPEE FEATURE_TYPE roads \
INPUT CLIPPEE FEATURE_TYPE water \
INPUT CLIPPEE FEATURE_TYPE sewers \
OUTPUT CLIPPED_INSIDE FEATURE_TYPE * \
OUTPUT INSIDE FEATURE_TYPE * \
OUTPUT NONPOLY_CLIPPER FEATURE_TYPE BADCLIPPER \
@Log(BadClipper) @Abort() \
OUTPUT EXTRA_CLIPPER FEATURE_TYPE ExtraClipper \
@Log(EXtraClipper) @Abort()
B-11 FME Reference Manual Version 2.0
FACTORY REFERENCE CloseFactory
B.5 CloseFactory
B.5.1 Syntax
FACTORY_DEF <ReaderKeyword> CloseFactory \
[INPUT SHARED_BOUNDARY FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* ]+ \
[INPUT INSIDE_POINT FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* ]+ \
[INPUT BOUNDARY FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* ]+ \
[GROUP_BY [<attribute name>]+]* \
END_NODED|VERTEX_NODED \
[OUTPUT (INSIDE_POINT|SHARED_BOUNDARY| \
PIP|LINE|POLYGON) \
FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function>]* \
]*
B.5.2 Overview
The CloseFactory is very similar in operation to the PolygonFactory, however, it
allows a single set of edges to be used with multiple groups of arcs to close polygons.
The PolygonFactory does not allow such reusing of arc sets.
This factory is used when a noded mapsheet boundary is present only once in a file,
but its edges must be used multiple times to close polygonal features. In such a case,
two polygons are formed when the mapsheet boundary is used to close an otherwise
unclosed polygon. In order to determine which of the two polygons is the desired one,
an internal point is paired with the polygon. This feature is then output according to
the OUTPUT PIP clause. The polygons not containing any point are output by the
OUTPUT POLYGON clause.
B.5.3 Assumptions
Within a group, there are no overlapping polygons. There must be one point for each
polygon that is to be output. The shared boundaries must be noded correctly so that
each group may use them to close polygons.
B.5.4 Input Tags
The CloseFactory uses the following input tags.
CloseFactory FACTORY REFERENCE
B-12 FME Reference Manual Version 2.0
B.5.5 Output Tags
The CloseFactory supports the following output tags.
B.5.6 Example
The following example illustrates the use of the CloseFactory to form polygons from
IGDS lines and points which are grouped by graphic group. The shared edges may be
used by all groups to close polygons.
FACTORY_DEF IGDS CloseFactory \
INPUT SHARED_BOUNDARY FEATURE_TYPE 62 igds_type igds_line \
INPUT BOUNDARY FEATURE_TYPE 26 igds_type igds_line \
INPUT INSIDE_POINT FEATURE_TYPE 26 igds_type igds_text_node \
END_NODED \
GROUP_BY igds_graphic_group \
Tag Description
SHARED_BOUNDARY These are the boundary lines used to close polygons formed in any of the
groups of BOUNDARY features.
INSIDE_POINT These are the points that must be inside the closed polygons. They will
be output with the polygons as point-in-polygon geometry.
BOUNDARY These are the boundary lines that will be grouped according to the
GROUP_BY clause, and formed into polygons making use of the
SHARED_BOUNDARY features. Resulting polygons that contain an
INSIDE_POINT from the same group will be returned as PIPs.
Tag Description
SHARED_BOUNDARY The original shared boundaries come out unchanged. If this is not
specified, then such features are discarded.
LINE After attempting to form polygons with the set of boundary and shared
boundary elements, anything that did not close and was left as a line is
output via this clause. It will have the GROUP_BY attributes added to it.
If this is not specified, then such features are discarded.
PIP The polygons formed which contained a point come out here. They will
have point-in-polygon geometry, and all the attributes of the point will be
merged with them. If this is not specified, then such features are
discarded.
INSIDE_POINT Any points that came in but were never placed inside a polygon are output
with this clause. If a point is placed in a polygon, it is not output with this
clause. If this is not specified, such unused points are discarded.
POLYGON Normally this is not specified. However, if it is, then any polygons which
were formed but did not have a point inside them are output with this
clause. It will have the GROUP_BY attributes added to it.
B-13 FME Reference Manual Version 2.0
FACTORY REFERENCE CloseFactory
OUTPUT PIP FEATURE_TYPE pips \
OUTPUT INSIDE_POINT FEATURE_TYPE rejpt \
OUTPUT POLYGON FEATURE_TYPE poly \
OUTPUT LINE FEATURE_TYPE rejects \
OUTPUT SHARED_BOUNDARY FEATURE_TYPE shared
ConnectionFactory FACTORY REFERENCE
B-14 FME Reference Manual Version 2.0
B.6 ConnectionFactory
B.6.1 Syntax
FACTORY_DEF <ReaderKeyword> ConnectionFactory \
[INPUT FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute Value>]* \
[<feature function>]*]+ \
[BREAK_BEFORE_FIELD_CHANGE [<attribute Name>]+] \
[BREAK_AFTER_FIELD_CHANGE [<attribute Name>]+ \
[FEATURE_CONNECTION ORDERED|NODED] \
[END_CURRENT_WHEN <value> <operator> <value>]+ \
[START_NEW_WHEN <value> <operator> <value>]+ \
[CLOSE_WHEN <value> <operator> <value>]+ \
OUTPUT POINT|LINE|POLYGON \
FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function>]* \
OUTPUT BAD_INPUT FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function>]* \
B.6.2 Overview
This factory is used to construct new features from a collection of input features. The
factory accepts features with point or linear geometry and outputs features which
have geometry which is the combination of the input features geometry. Any feature
which is received but which does not have a geometry of POINT or LINE is output
via the BAD_INPUT output tag.
At any given time the factory is creating only one feature. The current feature being
constructed is output whenever any of the following cases is true:
a) The values of any of the BREAK_BEFORE_FIELD_CHANGE fields changes
from one feature to the next. When this occurs the newly received input feature
is not part of the flushed feature but instead is part of the next feature which is
to be constructed.
b) The values of any of the BREAK_AFTER_FIELD_CHANGE fields changes
from one feature to the next. When this occurs the newly received input feature
is part of the flushed feature.
c) The values of any of the END_CURRENT_WHEN clauses evaluates to true.
When this occurs the newly received input feature is part of the flushed feature.
d) The values of any of the START_NEW_WHEN clauses evaluates to true. When
this occurs the newly received input feature is not part of the flushed feature but
is instead the first part of the next feature.
B-15 FME Reference Manual Version 2.0
FACTORY REFERENCE ConnectionFactory
The clause specified by CLOSE_WHEN is only evaluated when one of the clauses
described in a) through d) are true. If the CLOSE_WHEN clause is true then the output
feature is converted into a polygon provided that the featurehas at least 3 coordinates.
Closed features are output via the POLYGON output tag.
When the factory receives a point feature it merely adds the feature onto the end of
the current feature being constructed, unless of course one of the break conditions
described above is true.
When the factory receives a linear feature it does the following:
a) If LINEAR_FEATURE_CONNECTION is ORDERED then the factory merely
appends the coordinates onto the end of the feature being constructed.
b) If LINEAR_FEATURE_CONNECTION is NODED then the factory adds the
coordinates onto the end but removes the first coordinate of subsequent features
as they are duplicated from one component feature to the next.
B.6.3 Output Tags
POLYGON Polygonal features constructed by the factory are output via this tag.
LINE Linear features constructed by the factory are output via this tag.
POINT Features which remain as points are output here.
B.6.4 Example
The following example constructs linear features from point features. The input file
has the following definition.
ID X Y NODType
1 10 10 1
1 10 20 2
1 10 30 2
1 10 40 2
1 20 30 3
2 20 10 1
2 20 20 2
2 20 30 2
2 20 40 2
ConnectionFactory FACTORY REFERENCE
B-16 FME Reference Manual Version 2.0
The values of ID, X, and Y require no explanation. The values for NODTYPE are as
follows:
1 = start node
2 = interior node
3 = end node unclosed
4 = end node closed.
This factory definition would connect all the nodes into linear and polygonal features:
FACTORY_DEF TABLE ConnectionFactory \
INPUT FEATURE_TYPE * \
END_CURRENT_WHEN &NODTYPE = 4 \
END_CURRENT_WHEN &NODTYPE = 3 \
CLOSE_WHEN &NODTYPE = 4 \
OUTPUT LINE FEATURE_TYPE line \
OUTPUT LINE FEATURE_TYPE polygon
2 30 30 4
ID X Y NODType
B-17 FME Reference Manual Version 2.0
FACTORY REFERENCE DeaggregateFactory
B.7 DeaggregateFactory
B.7.1 Syntax
FACTORY_DEF <ReaderKeyword> DeaggregateFactory \
[INPUT FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* \
]* \
[LIST_NAME <list name>{}] \
[OUTPUT (DONUT|LINE|PIP|POINT|POLYGON) \
FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function>]* \
]*
B.7.2 Overview
This factory takes a feature with aggregate geometry and breaks it into several
features, one for each geometry fragment it contained. Each piece gets a complete
copy of the original aggregate features attributes.
The optional LIST_NAME clause is used to associate attributes with each member of
the aggregate. When the aggregate is broken up, any elements of the attribute list
corresponding to the geometry will be added to the feature that is output, in the same
manner as the ElementFactory.
If an aggregate had a member for a geometry type not represented in any OUTPUT
clause, that portion of the geometry is discarded.
TIP: The DeaggregateFactory is similar to the ElementFactory. The ElementFactory breaks attribute lists into
features, whereas the DeaggregateFactory breaks aggregated geometry into features.
B.7.3 Assumptions
All features entering the DeaggregateFactory must have aggregate geometry.
Aggregate geometry may be found on features coming from SAIF or Shape, or
features created by the AggregateFactory. If a feature which is not an aggregate
enters the factory then the translation operation is aborted.
DeaggregateFactory FACTORY REFERENCE
B-18 FME Reference Manual Version 2.0
B.7.4 Output Tags
The DeaggregateFactory supports the following output tags.
B.7.5 Example
The following example illustrates the use of the DeaggregateFactory to break apart
the linear aggregate contour features created in the AggregateFactory example.
FACTORY_DEF SAIF DeaggregateFactory \
INPUT FEATURE_TYPE ContourAggregate \
OUTPUT LINE FEATURE_TYPEContour::TRIM \
featNum @Count()
TIP: If the ContourAggregate feature had any point, pip, polygon, or donut geometry, it would be
discarded by this factory since only the LINE OUTPUT tag is specified.
The below feature matches the input specification of this factory definition, and will
enter the factory:
Tag Description
DONUT Donut geometries in the original feature will have this specification
applied to them as they are output.
LINE Linear geometries in the original feature will have this specification
applied to them as they are output.
PIP Point-in-polygon geometries in the original feature will have this
specification applied to them as they are output.
POINT Point geometries in the original feature will have this specification
applied to them as they are output.
POLYGON Polygon geometries in the original feature will have this specification
applied to them as they are output.
Feature Type: ContourAggregate
Attribute Name Value
position.geometry.qualifier definite
position.geometry.value 20
Coordinates:
Line 1: (477553,5360181,20) (477554,5360182,20)
Line 2: (377553,4360181,20) (377554,4360182,20)
B-19 FME Reference Manual Version 2.0
FACTORY REFERENCE DeaggregateFactory
The below two features will be output from the factory.
TIP: Note the featNum attribute which was added as each of the features left the factory.
Feature Type: Contour::TRIM
Attribute Name Value
position.geometry.qualifier definite
position.geometry.value 20
featNum 0
Coordinates: (477553,5360181,20) (477554,5360182,20)
Feature Type: Contour::TRIM
Attribute Name Value
position.geometry.qualifier definite
position.geometry.value 20
featNum 1
Coordinates: (377553,4360181,20) (377554,4360182,20)
DonutFactory FACTORY REFERENCE
B-20 FME Reference Manual Version 2.0
B.8 DonutFactory
B.8.1 Syntax
FACTORY_DEF <ReaderKeyword> DonutFactory \
[INPUT FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* \
]* \
[DROP_HOLES] \
[GROUP_BY [<attribute name>]+]* \
[OUTPUT (DONUT|LINE|PIP|POINT|POLYGON) \
FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function>]* \
]*
B.8.2 Overview
This factory takes a series of features and joins them together based on spatial
enclosure. Only features with polygon, donut polygon, or point geometry are
processed by the factory if a linear feature is found then it is output according to
the OUTPUT LINE clause. Once all the input features have been collected, the factory
produces an internal spatial ordering of all the components.
If the DROP_HOLES tag is specified, any polygons which were enclosed within
another polygon will be deleted. Holes of holes will be kept. If DROP_HOLES is not
specified, then all polygons will be output.
The factory performs the following steps:
Step 1: First, the factory determines the nesting of all input polygons.
Step 2: At the conclusion of this operation all polygons and donut
polygons have been identified.
Step 3: If there are no points input into the factory then it is done and the
polygons are output via the OUTPUT clauses tagged with
POLYGON and DONUT.
When a donut polygon is created the DonutFactory ensures that there are no
holes which share a common edge by combining abutting holes together into a
single hole.
Step 4: If points are also input into the factory, the DonutFactory then
matches points to the polygon and donut polygons determined in 1
above. Points are matched to the polygons which enclose them. At
most 1 point will be matched to any polygon.
B-21 FME Reference Manual Version 2.0
FACTORY REFERENCE DonutFactory
Step 5: Any polygons found to contain a point have the points attributes
and coordinates merged with their own.
Step 6: The resulting features are then output via the PIP-tagged OUTPUT
clause.
Step 7: Points, polygons, and donut polygons which are not matched are
output via the POINT, POLYGON, and DONUT output clauses
respectively.
TIP: The DonutFactory does not require points be input, in which case it still performs the construction of donut
polygons.
B.8.3 Assumptions
The DonutFactory assumes that the model is topologically clean, and that no
polygons within a group intersect. It is further assumed that each point is only in one
polygon, and that each polygon has only 1 point.
B.8.4 Output Tags
The DonutFactory supports the following output tags.
B.8.5 Example
The following example defines a DonutFactory which accepts two types of features.
The input polygons are of type ForestCoverPolygons, and will be nested by
the DonutFactory. The InteriorPoint features are point features which the
DonutFactory will attempt to match up to polygon features they are contained within.
The example outputs the following feature types:
Tag Description
DONUT All donut polygons which were successfully constructed but contained
no points.
LINE All line objects sent into the model. The geometry of these features will
be unchanged.
PIP All Point In Polygon features. The geometry of these features is consists
of a polygon or donut polygon and an inner point. The points attributes
are merged with the polygons.
POINT All point features which werent found to be in any polygon.
POLYGON All polygon features which contained neither any holes nor an inside
point.
DonutFactory FACTORY REFERENCE
B-22 FME Reference Manual Version 2.0
POLYGON: These are polygonal features for which no internal polygon or
internal point was input into the factory.
DONUT: These are polygonal features for which internal polygons were found.
However, no internal points were found for these.
POINT: These are the point features for which no enclosing polygon was found.
PIP: These are the output polygonal features which contain a point.
FACTORY_DEF Shape DonutFactory \
INPUT FEATURE_TYPE ForestCoverPolygon \
INPUT FEATURE_TYPE InteriorPoint \
OUTPUT POLYGON FEATURE_TYPE ForestCoverPolygon \
OUTPUT DONUT FEATURE_TYPE ForestCoverPolygon \
OUTPUT POINT FEATURE_TYPE ForestCoverPolygonPoint \
OUTPUT PIP FEATURE_TYPE ForestCoverPIP
B-23 FME Reference Manual Version 2.0
FACTORY REFERENCE DonutHoleFactory
B.9 DonutHoleFactory
B.9.1 Syntax
FACTORY_DEF <ReaderKeyword> DonutHoleFactory \
[INPUT FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* \
]* \
[OUTPUT (OUTERSHELL|HOLE) \
FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function>]* \
]+
B.9.2 Overview
This factory takes a feature which should be a donut polygon or plain polygon. It
splits out the donut polygon into its components (a containing polygon and a series of
holes), and outputs them accordingly. A single polygon is output untouched. Each
component has all the attributes of the original feature.
B.9.3 Assumptions
The DonutHoleFactory assumes that all features it gets are either single polygons, or
donut hole polygons, and not disjoint multi-polygons.
TIP: The DonutHoleFactory is often used to split complex polygons into simple geometry for output to systems
lacking support for polygons with holes.
B.9.4 Output Tags
The DonutHoleFactory supports the following output tags.
Tag Description
OUTERSHELL The outside containing ring of the original donut polygon is output with
this tag.
HOLE Each hole in the original donut polygon is output with this tag.
DonutHoleFactory FACTORY REFERENCE
B-24 FME Reference Manual Version 2.0
B.9.5 Example
The following example uses a DonutHoleFactory to split complex polygons into their
components. Note how each original polygon is assigned a unique number, which
could be used to tie the holes back to their original polygon at a later time.
FACTORY_DEF Shape DonutHoleFactory \
INPUT FEATURE_TYPE ForestCoverPolygon \
polygonNumber @Count(polygons) \
OUTPUT OUTERSHELL FEATURE_TYPE Shells \
OUTPUT HOLE FEATURE_TYPE Holes
B-25 FME Reference Manual Version 2.0
FACTORY REFERENCE ElementFactory
B.10 ElementFactory
B.10.1 Syntax
FACTORY_DEF <ReaderKeyword> ElementFactory \
[INPUT FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* \
]* \
LIST_NAME <list name>{} \
[CLONE_GEOMETRY] \
[OUTPUT (BASE|ELEMENT) \
FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function>]* \
]*
B.10.2 Overview
This factory takes a feature with a list identified by <list name> and returns one
feature for each element in the list, as well as the original feature. The list elements
are returned without geometry on them unless the CLONE_GEOMETRY clause is
specified in the factory definition. The list elements get all the other attributes of the
original feature. The original feature is output if the BASE output tag is specified.
TIP: The @XValue, @YValue, and @ZValue functions can be used to supply coordinates to element point
features.
B.10.3 Assumptions
None.
B.10.4 Output Tags
The ElementFactory supports the following output tags.
Tag Description
BASE The original feature.
ELEMENT A single feature for each element in the list. The feature is identical with
the original feature returned through the BASE output tag with the
following exceptions:
These features have no geometry unless the CLONE_GEOMETRY
clause is specified in the factory definition.
The feature only contains a single element of the input list.
ElementFactory FACTORY REFERENCE
B-26 FME Reference Manual Version 2.0
B.10.5 Example
The following example illustrates the use of the ElementFactory to break IGDS text
multiline objects apart into their components. This is needed when translating from
IGDS to a system such as Shape which cannot accommodate text multiline objects.
The definition of the ElementFactory is:
FACTORY_DEF IGDS ElementFactory \
INPUT FEATURE_TYPE 35 igds_type igds_multi_text \
LIST_NAME igds_text_elements{} \
OUTPUT ELEMENT FEATURE_TYPE 35 \
igds_type igds_text_frag
The below feature matches the input specification of this factory definition, and will
enter the factory:
TIP: Since no OUTPUT BASE clause is specified, the original feature input to the ElementFactory will be
deleted.
The factory will split the above feature into two output features, which are shown as
they emerge from the factory after having the OUTPUT ELEMENT clause applied
to them:
Feature Type: 35
Attribute Value
igds_type igds_multi_text
igds_text_elements{0}.igds_text Hello
igds_text_elements{0}.x 477556
igds_text_elements{0}.y 5360183
igds_text_elements{1}.igds_text World
igds_text_elements{1}.x 477556
igds_text_elements{1}.y 5359177
Coordinates: (477553,5360181,20)
B-27 FME Reference Manual Version 2.0
FACTORY REFERENCE ElementFactory
TIP: The shaded attributes have been added or changed. Notice that all the original attributes are still present in
each of the elements output.
TIP: Applying the @XValue(&x) and @Yvalue(&y) functions to the element feature would provide it with
coordinates that could be used by an output format.
Feature Type: 35
Attribute Name Value
igds_type igds_text_frag
igds_text Hello
x 477556
y 5360183
igds_text_elements{0}.igds_text Hello
igds_text_elements{0}.x 477556
igds_text_elements{0}.y 5360183
igds_text_elements{1}.igds_text World
igds_text_elements{1}.x 477556
igds_text_elements{1}.y 5359177
Coordinates: no coordinates
Feature Type: 35
Attribute Value
igds_type igds_text_frag
igds_text World
x 477556
y 5359177
igds_text_elements{0}.igds_text Hello
igds_text_elements{0}.x 477556
igds_text_elements{0}.y 5360183
igds_text_elements{1}.igds_text World
igds_text_elements{1}.x 477556
igds_text_elements{1}.y 5359177
Coordinates: no coordinates
ListFactory FACTORY REFERENCE
B-28 FME Reference Manual Version 2.0
B.11 ListFactory
B.11.1 Syntax
FACTORY_DEF <ReaderKeyword> ListFactory \
[INPUT FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* \
]* \
[GROUP_BY [<attribute name>]+]* \
LIST_NAME <list name> \
[OUTPUT LIST|SINGLETON \
FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function>]* ]*
B.11.2 Overview
This factory takes a series of features matching an input specification and joins them
together based on attribute values specified by the GROUP_BY clause. One feature is
output for each group resulting from the GROUP_BY clause. If no GROUP_BY clause
is specified then all features fall into the same group and a single feature is output.
The features output from the ListFactory have all of their attributes stored within the
list identified by <list name>. There is one element in the list for each feature
which is in the group from which the list is constructed. If no GROUP_BY clause is
specified then the number of elements in the list is equivalent to the number of
features which were input into the ListFactory.
The output features have NO geometry. If the OUTPUT SINGLETON clause is
specified, features that are the only members of their group are output unchanged.
B.11.3 Assumptions
None.
B.11.4 Output Tags
The ListFactory supports the following output tags.
B-29 FME Reference Manual Version 2.0
FACTORY REFERENCE ListFactory
B.11.5 Example
The following example illustrates the use of the ListFactory to merge text features
read from a Shape file into a single multi-text-line object. This is needed when
translating to systems like IGDS or SAIF which handle complex multiline text from
systems such as Shape which can only group text elements together by common
attribute values.
The definition of the ListFactory is shown below. Note that as features enter the
factory, the @XValue and @YValue functions are used to extract their coordinates
and assign them to attributes, which will be output in the list.
FACTORY_DEF Shape ListFactory \
INPUT FEATURE_TYPE text x @XValue() \
y @Yvalue() \
GROUP_BY TEXTGROUP \
LIST_NAME text_elements{} \
OUTPUT LIST FEATURE_TYPE text_multi
TIP: Since no OUTPUT SINGLETON clause is specified, groups which have only 1 element in them will still
be output as a list.
The below features match the input specification of this factory definition, and will
enter the factory:
Tag Description
LIST The features for which lists are constructed. If the SINGLETON tag is
specified then each of these features has a list with at least 2 elements.
SINGLETON Applies to features which are the only members in a group. If this isnt
specified then such features are output using the LIST tag with all their
attributes stored in an element list with only one element. If an OUTPUT
SINGLETON clause is specified, such features are output unchanged.
Feature Type: text
Attribute Name Value
TEXTSTRING Hello
TEXTGROUP 12
Coordinates: (477553,5360181,20)
ListFactory FACTORY REFERENCE
B-30 FME Reference Manual Version 2.0
The factory will merge the above features together, producing the below feature:
TIP: Notice the GROUP_BY TEXTGROUP attribute has been added to the output feature. If the @XValue and
@YValue functions were not in the INPUT clause, the {}.x and {}.y attributes would not be present
in the output feature.
Feature Type: text
Attribute Name Value
TEXTSTRING World
TEXTGROUP 12
Coordinates: (477553,5450181,20)
Feature Type: text_multi
Attribute Name Value
TEXTGROUP 12
text_elements{0}.TEXTSTRING Hello
text_elements{0}.x 477553
text_elements{0}.y 5360181
text_elements{1}.TEXTSTRING World
text_elements{1}.x 477556
text_elements{1}.y 545018
Coordinates: no coordinates
B-31 FME Reference Manual Version 2.0
FACTORY REFERENCE MatchingFactory
B.12 MatchingFactory
B.12.1 Syntax
FACTORY_DEF <ReaderKeyword> MatchingFactory \
[ INPUT FEATURE_TYPE <featureType> [<attrName> \
<attrValue>]* ] * \
[ MATCH_GEOMETRY (2D|3D|NONE) ] \
[ MATCH_ATTRIBUTES [ <attrName> ] + ] \
[ DIFFERING_ATTRIBUTES [ <attrName> ] + ] \
[ ADD_TO_MATCHED [ <attrName> <attrValue> ] + ] \
[ OUTPUT MATCHED FEATURE_TYPE <featureType> [<attrName> \
<attrValue>]* ] \
[ OUTPUT NOT_MATCHED FEATURE_TYPE <featureType> [<attrName>\
<attrValue>]* ]
B.12.2 Overview
This factory can be used to detect and flag features which are matches of each other.
Features are declared to match when they have matching geometry, matching
attribute values, differing attribute values, or any combination of the three. The
specification of the factory determines how matches will be declared.
This factory is most commonly used together with the multi-reader to identify
features which two files have in common. In this way, the factory can also be used to
perform change detection between the input files. In conjunction with the multi-
reader, it is able to identify all those features two input files have in common, and
those which are in one file and not the other (the additions and the deletions).
TIP: Because the matching factory must hold every feature until the input data source is exhausted, it requires
a large virtual memory pool for large input data sources.
B.12.3 Assumptions
The geometry matching does not consider geometries to be equivalent if their vertex
order is reversed.
B.12.4 Clauses
The MatchingFactory makes use of several additional clauses to fully specify its
operation. All are optional.
MatchingFactory FACTORY REFERENCE
B-32 FME Reference Manual Version 2.0
B.12.5 Example
In this example, the River features from two SAIF files, an original file and an
updated version of the original, are compared using the matching factory to determine
the changes which have been made.
The example shows how the factory can be used to determine features which are the
same, features which have been deleted, and features which have been added during
the update process.
#-----------------------------------------------------------------
# Set up for a multi-read of all the rivers and streams in two
# SAIF datasets
READER_TYPE MULTI_READER
MULTI_READER_TYPE{0} SAIF
MULTI_READER_KEYWORD{0} SAIF{0}
Clauses Description Optional
MATCH_GEOMETRY
(2D|3D|NONE)
Controls if 2D or 3D (or NO) geometry must be the
same before match is declared.
Default: None
Example: MATCH_GEOMETRY 2D
Yes
MATCH_ATTRIBUTES
[<attrName>] +
Controls which attributes that are part of the input
features must have the same value before a MATCH
will be declared.
Default: No Attributes
Example: MATCH_ATRIBUTES type
Yes
DIFFERING_ATTRIBUTES
[<attrName>]+]
Controls which attributes that are part of the input
feature must have the different values before a
MATCH will be declared.
Default: No Attributes
Example: DIFFERING_ATTRIBUTES
multi_reader_id
Yes
ADD_TO_MATCHED
[<attrName> <attrValue>]+
Contains a series of attribute names and values that
will be added to each matched feature.
Note: If the value was a function, it will only be
invoked once and the same return value will be
added to each matched feature. This can be used to
assign a unique ID to each group of matching
features, as the following example shows.
Default: None
Example: ADD_ATTRIBUTES
match_id @Count(Matches)
(If features a, b, and c all match, then a, b, and c
will have the same value for match_id, and no
other features will have this value
Yes
B-33 FME Reference Manual Version 2.0
FACTORY REFERENCE MatchingFactory
SAIF{0}_DATASET c:\saifdata\original.zip
SAIF{0}_IDs RiverStreams
MULTI_READER_TYPE{1} SAIF
MULTI_READER_KEYWORD{1} SAIF{1}
SAIF{1}_DATASET c:\saifdata\updated.zip
SAIF{1}_IDs RiverStreams
#-----------------------------------------------------------------
# This factory looks for matches among all the river objects
# read in that have "Arc" geometry (which in SAIF is the same as
# saying linear geometry). Only the x and y coordinates are
# compared when looking for matches, and the "type" attribute must
# have the same value for features to be matched. As well, the
# multi_reader_id attribute must be different -- this ensures that
# if the original file had two equivalent features, they are not
# matched.
# A "match_id" field is also added. It will contain the same value
# in any features which are declared as matched, though in this
# example, this value is never used.
FACTORY_DEF MULTI_READER MatchingFactory \
INPUT FEATURE_TYPE River::TRIM position.geometry.Class Arc \
MATCH_GEOMETRY 2D \
MATCH_ATTRIBUTES type \
DIFFERING_ATTRIBUTES multi_reader_id \
ADD_TO_MATCHED match_id @Count(matches) \
OUTPUT MATCHED FEATURE_TYPE * matched YES \
OUTPUT NOT_MATCHED FEATURE_TYPE * matched NO
#-----------------------------------------------------------------
# Now set up to output the features to shape files
WRITER_TYPE SHAPE
#-----------------------------------------------------------------
# This shape file gets all the rivers in the original SAIF file
# that have not been changed. This means that they were matched
# and so lived in both the first and second file. So we need only
# to save the ones from the first file, those from the second file
# can be ignored.
SHAPE_DEF unchangedRivers RIVERTYPE char(30)
SAIF River::TRIM matched YES multi_reader_id 0 type %type
SHAPE unchangedRivers RIVERTYPE %type
#-----------------------------------------------------------------
# This shape file gets all the rivers in the second SAIF file
# that were not in the first. This means they were not matched and
# have a multi_reader_id of 1. Such features are ones which have
# been "added"
SHAPE_DEF newRivers RIVERTYPE char(30)
SAIF River::TRIM matched NO multi_reader_id 1 type %type
SHAPE newRivers RIVERTYPE %type
MatchingFactory FACTORY REFERENCE
B-34 FME Reference Manual Version 2.0
#-----------------------------------------------------------------
# This shape file gets all the rivers in the first SAIF file
# that were not in the second. This means they were not matched and
# have a multi_reader_id of 0. Such features are ones which have
# been "deleted".
SHAPE_DEF deletedRivers RIVERTYPE char(30)
SAIF River::TRIM matched NO multi_reader_id 0 type %type
SHAPE deletedRivers RIVERTYPE %type
B-35 FME Reference Manual Version 2.0
FACTORY REFERENCE PIPComponentsFactory
B.13 PIPComponentsFactory
B.13.1 Syntax
FACTORY_DEF <ReaderKeyword> PIPComponentsFactory \
[INPUT FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* \
]* \
[OUTPUT (POINT|POLYGON) \
FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function>]* \
]*
B.13.2 Overview
This factory takes a feature with PointInPolygon geometry and splits it into two
features. PointInPolygon geometry consists of a point and either a polygon or a
donut polygon. This factory breaks such a feature into a feature with the point
geometry and another with the polygon or donut polygon geometry. Each output
feature gets all the attributes of the original, plus any others that the INPUT and
OUTPUT clauses add.
Features which match the specified feature type but which do not have a geometry of
PointInPolygon are logged to the FME logfile. They are then passed out of the
factory unchanged.
If either of the OUTPUT clauses is not specified, then that portion of the geometry is
thrown away. For example, if only an OUTPUT POINT clause is specified, the
polygon geometry will be thrown away.
B.13.3 Assumptions
The input feature must have PointInPolygon geometry to be split.
B.13.4 Output Tags
The PIPComponentsFactory supports the following output tags:
PIPComponentsFactory FACTORY REFERENCE
B-36 FME Reference Manual Version 2.0
B.13.5 Example
The following example accepts features of type ForestCoverPIP and outputs two
types of features; InteriorPoint and ForestCoverPolygon. Each of the
output features is assigned all of the attributes of the original feature.
FACTORY_DEF IGDS PIPComponentsFactory \
INPUT FEATURE_TYPE ForestCoverPIP \
OUTPUT POINT FEATURE_TYPE InteriorPoint \
OUTPUT POLYGON FEATURE_TYPE ForestCoverPolygon
The second example shows how this factory can be used with the
@GeneratePoint feature function to replace a polygonal feature with a feature
having all the same attribution but only the geometry of an point internal to the
original polygon:
FACTORY_DEF Shape PIPComponentsFactory \
INPUT FEATURE_TYPE tract @GeneratePoint() \
OUTPUT POINT FEATURE_TYPE tractPoint
Tag Description
POINT The point portion of the input features geometry is output as a point
feature. It has all the attribute values of the input feature.
POLYGON The polygon or donut polygon which defined the input PointInPolygon
feature is output with this clause. The output polygon has all of the
attributes of the input feature.
B-37 FME Reference Manual Version 2.0
FACTORY REFERENCE PolygonFactory
B.14 PolygonFactory
B.14.1 Syntax
FACTORY_DEF <ReaderKeyword> PolygonFactory \
[INPUT FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* \
]* \
[GROUP_BY [<attribute name>]+]* \
(END_NODED|VERTEX_NODED) \
[OUTPUT POLYGON|LINE \
FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function>]* \
]*
B.14.2 Overview
This factory takes linear features and forms topologically correct polygons. Any lines
which can not be formed into polygons are joined together to form maximal length
linestrings. The input linear features may be partitioned by the GROUP_BY clause. If
the GROUP_BY clause is not specified, then all the input are processed together. No
attributes are carried across from the INPUT features to the output features.
However, all OUTPUT features are assigned the GROUP_BY attributes before being
output. If the OUTPUT LINE clause is not specified, then lines which are not part of
a polygon are deleted.
The END_NODED and VERTEX_NODED directives tell the factory about the topology
of the input features. END_NODED indicates that all features begin and end at
topologically significant points, and that none of their vertices connects with any
other features. VERTEX_NODED indicates that every vertex may be topologically
significant, and must be considered when looking to form polygons.
B.14.3 Assumptions
This factory assumes that all input lines are already topologically noded. The factory
assumes that the input arcs have been processed by a GIS product which has ensured
that the data is clean.
PolygonFactory FACTORY REFERENCE
B-38 FME Reference Manual Version 2.0
B.14.4 Output Tags
The PolygonFactory supports the following output tags.
B.14.5 Example
The following example takes IGDS lines from level 9 and forms them into polygons.
The polygons are output as features of type ForestCoverPolygon. Any lines
which cannot be formed into polygons are output as features of type
PolygonFactory_Line.
FACTORY_DEF IGDS PolygonFactory \
INPUT FEATURE_TYPE 9 igds_type igds_line \
OUTPUT LINE FEATURE_TYPE PolygonFactory_Line \
lineNum @Count(LineNum) \
OUTPUT POLYGON FEATURE_TYPE ForestCoverPolygon \
polyNum @Count(PolyNum)
TIP: Notice the use of the @Count() function on the output statements to assign a unique number to each
PolygonFactor_Line and ForestCoverPolygon output feature.
Tag Description
LINE Maximal length line features which are not part of any polygon.
POLYGON Polygon features formed from the input linework.
B-39 FME Reference Manual Version 2.0
FACTORY REFERENCE PolygonDissolveFactory
B.15 PolygonDissolveFactory
B.15.1 Syntax
FACTORY_DEF <ReaderKeyword> PolygonDissolveFactory \
[INPUT FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* \
]* \
[GROUP_BY [<attribute name>]+]* \
[MEAN_FIELDS [<attribute name>]+]* \
[OUTPUT POLYGON|INTERIOR_LINE|NON_POLYGON \
FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function>]* \
]*
1
B.15.2 Overview
This factory accepts polygonal features, and outputs dissolved polygons. Dissolved
polygons are those polygons which are formed when shared edges between polygons
are removed. The factory assumes that the input polygons are properly noded. Any
features which are not polygons are output untouched to the NON_POLYGON feature
output tag.
The input polygonal features may be partitioned by the GROUP_BY clause. If the
GROUP_BY clause is not specified, then all the input are processed together. The
GROUP_BY clause enables a single factory to perform the dissolve of several
different (potentially overlapping) polygonal coverages. No attributes are carried
across from the INPUT features to the output features. However, all OUTPUT features
will have the group by attributes added to them before being output, along with any
SUM and MEAN fields. The factory also enables Sum and Average, operations to be
performed on identified fields. If the OUTPUT INTERIOR_LINE clause is
specified, then any arcs which are not part of the output polygons will be output.
The SUM clause identifies the names of the fields whose values are to be summed
together and then assigned to the output polygons. The summed field values will then
be output with the dissolved polygons. The MEAN clause calculates the MEAN or
average value for the fields identified and assigns the result to the dissolved polygons.
1. The SUM_FIELDS and MEAN_FIELDS are not implemented in FME Version 2.0.
PolygonDissolveFactory FACTORY REFERENCE
B-40 FME Reference Manual Version 2.0
B.15.3 Assumptions
This factory assumes that all input polygons are already topologically noded. The
factory assumes that the input polygons have been processed by a GIS product which
has ensured that the data is clean.
B.15.4 Output Tags
The PolygonDissolveFactory supports the following output tags.
B.15.5 Example
The following example takes all input features from an input shape file and passes all
non-polygon features on via its NON_POLYGON output tag. All the input polygons
are grouped by their long_id, category, and full_id attribute values. All
output polygons have their feature type set to the value of the category. The factory
also outputs any linear features which represent the shared edges between the
polygons which were dissolved. These shared edges are output via the
INTERIOR_LINE .
FACTORY_DEF SHAPE_IN PolygonDissolveFactory \
INPUT FEATURE_TYPE * \
GROUP_BY long_id category full_id \
OUTPUT POLYGON FEATURE_TYPE * @FeatureType(&category) \
OUTPUT INTERIOR_LINE FEATURE_TYPE InteriorLine \
OUTPUT NON_POLYGON FEATURE_TYPE *
Tag Description
POLYGON Dissolved Polygon features with attributes specified by
GROUP_BY, SUM, and MEAN clauses set appropriately.
NON_POLYGON Non-polygonal features which enter the factory, exit the factory
here untouched.
INTERIOR_LINE Linear features which represent the portions of the input polygons
which are not part of the output dissolved polygon.
B-41 FME Reference Manual Version 2.0
FACTORY REFERENCE ReferenceFactory
B.16 ReferenceFactory
B.16.1 Syntax
FACTORY_DEF <ReaderKeyword> ReferenceFactory \
[INPUT REFERENCEE FEATURE_TYPE <featureType> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* \
[INPUT REFERENCER FEATURE_TYPE <featureType> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* \
REFERENCEE_FIELDS [<FIELD_NAME>]+ \
REFERENCER_FIELDS [<FIELD_NAME>]+ \
REFERENCE_INFO [GEOMETRY | ATTRIBUTES] \
[OUTPUT COMPLETE FEATURE_TYPE <feature Type> \
[<attribute name> <attribute value>]*] \
[<feature function> ]* \
[OUTPUT INCOMPLETE FEATURE_TYPE <feature Type> \
[<attribute name> <attribute value>]*] \
[<feature function> ]* \
[OUTPUT REFERENCED FEATURE_TYPE <feature Type> \
[<attribute name> <attribute value>]*] \
[<feature function> ]* \
[OUTPUT UNREFERENCED FEATURE_TYPE <feature Type> \
[<attribute name> <attribute value>]*] \
[<feature function> ]* \
[OUTPUT NO_REFERENCES FEATURE_TYPE <feature Type> \
[<attribute name> <attribute value>]*] \
[<feature function> ]* \
[OUTPUT NO_REFERENCEE_FIELD \
FEATURE_TYPE <feature Type> \
[<attribute name> <attribute value>]*] \
[<feature function> ]* \
[OUTPUT DUPLICATE_REFERENCEE \
FEATURE_TYPE <feature Type> \
[<attribute name> <attribute value>]*] \
[<feature function> ]*
B.16.2 Overview
This factory resolves references between REFERENCER and REFERENCEE features.
It is used to merge the geometry of the REFERENCEE features into REFERENCER
features.
Each ReferenceFactory accepts two kinds of features: REFERENCEEs and
REFERENCERs.
REFERENCEEs are those features which are pointed to by some field of the
REFERENCER features. When the REFERENCE_INFO directive is of type
GEOMETRY then the REFERENCEEs are the features which contain the geometry.
When the REFERENCE_INFO directive is of type ATTRIBUTES then the
ReferenceFactory FACTORY REFERENCE
B-42 FME Reference Manual Version 2.0
REFERENCEEs contain attribution which will be joined to the attribution of the
REFERENCER features.
REFERENCERs are the features which contain reference pointers to the
REFERENCEE features.
The factory performs the following operations.
All REFERENCEE features for each REFERENCER feature are identified.
The geometry (attributes) from the identified REFERENCEE features are then
combined to form the geometry(attributes) of the REFERENCER feature.
REFERENCEE features which are referenced are output by the output tag
REFERENCED.
REFERENCEE features which are not referenced by any REFERENCER feature
are output by the output tag UNREFERENCED.
REFERENCER features which are matched with all the features which they
reference are output by the output tag COMPLETE.
REFERENCER features which refer to one or more REFERENCEE features
which were not found are output by the output tag INCOMPLETE.
REFERENCEE features which dont have any of the attributes identified by the
REFERENCEE_FIELDS clause are output by the tag
NO_REFERENCEE_FIELD.
REFERENCEE features which have the same value for the
REFERENCEE_FIELDS as a previously encountered REFERENCEE are output
via the DUPLICATE_REFERENCEE tag.
REFERENCER features which do not have any value for the
REFERENCER_FIELDS are output by the tag NO_REFERENCES.
At the completion of the processing the factory logs statistics information to the FME
logfile. The number of features output for each output tag value is reported.
The figure below illustrates the processing of the factory. The example illustrates the
processing of three features: 1 REFERENCER and 2 REFERENCEEs. In this
example, all REFERENCEEs are referenced and the REFERENCER references are all
satisfied. After the ReferenceFactory has completed the processing the factory
outputs 1 COMPLETE feature and 2 REFERENCED features.
B-43 FME Reference Manual Version 2.0
FACTORY REFERENCE ReferenceFactory
B.16.3 Assumptions
None.
B.16.4 Input Tags
The ReferenceFactory supports the following input tags.
B.16.5 Clauses
The ReferenceFactory supports several configuration clauses.
REFERENCEE_FIELDS [<field_name>]+: This clause defines the fields
which are to make up the referencee key.
If multiple fields are specified then the key is the concatenation of the fields in the
order that the name is specified. List attribute names may not be specified as part of
the REFERENCEE_FIELDS.
Tag Description
REFERENCEE Features which are pointed to by one or more referencers.
REFERENCER Features which point to one or more referencees.
Geometry
REFERENCER
Reference
Factory
REFERENCEE
REFERENCED
REFERENCEE
REFERENCED
COMPLETE
ReferenceFactory FACTORY REFERENCE
B-44 FME Reference Manual Version 2.0
REFERENCER_FIELDS [<field_name>]+: This clause defines the fields
within the referencer object which when combined refer to a REFERENCEE
object.
If multiple keys are specified then the key values are concatenated in the order
specified on the clause. The ReferenceFactory uses the resulting key to find the
REFERENCEE object.
If a list attribute is specified then each of the list entries are used as a separate key to
reference multiple REFERENCEE objects. If a list attribute is specified then no other
fields can be specified.
B.16.6 Output Tags
The ReferenceFactory supports the following output tags.
B.16.7 Example
The following example defines a ReferenceFactory which accepts three types of
features: LineWork, Lake, and Roads. The factory then resolves the references and
passes the COMPLETE and REFERENCED features out of the factory with their
feature type unchanged.
Any REFERENCER features which are not able to resolve all references are output
with a feature type of INCOMPLETE and all REFERENCEE features which are not
referenced are output with the feature type set to EXTRA. The factory thus performs
all the reference matching as well as identifying referential problems in the input data.
Tag Description
COMPLETE REFERENCER features for which all referenced features were
present.
INCOMPLETE REFERENCER features for which one or more referenced features
were missing.
REFERENCED REFERENCEE features which were referenced by one or more
REFERENCER features.
UNREFERENCED REFERENCEE features which were not referenced by any feature.
NO_REFERENCES REFERENCER features which do not have any value for the
REFERENCER_FIELD attribute.
DUPLICATE_
REFERENCEE
REFERENCEE features which have the same value for the
REFERENCEE_FIELDS attributes.
NO_REFERENCEE
_FIELD
REFERENCEE features which have no value for the
REFERENCEE_FIELDS attributes.
B-45 FME Reference Manual Version 2.0
FACTORY REFERENCE ReferenceFactory
FACTORY_DEF TABLE ReferenceFactory \
INPUT REFERENCEE FEATURE_TYPE LineWork \
INPUT REFERENCER FEATURE_TYPE Lake \
INPUT REFERENCER FEATURE_TYPE Road \
REFERENCEE_FIELDS lineID \
REFERENCER_FIELDS geometry{} \
REFERENCE_INFO GEOMETRY \
OUTPUT COMPLETE FEATURE_TYPE * \
OUTPUT INCOMPLETE FEATURE_TYPE INCOMPLETE * \
OUTPUT REFERENCED FEATURE_TYPE * \
OUTPUT UNREFERENCED FEATURE_TYPE EXTRA
TIP: Notice the use the wildcard feature type (*) on the OUTPUT COMPLETE and OUTPUT REFERENCED
clauses. When the * is used as the feature type on an output line, it will not change the existing feature type.
This allows Lake and Road features to be output by the same OUTPUT clause.
SamplingFactory FACTORY REFERENCE
B-46 FME Reference Manual Version 2.0
B.17 SamplingFactory
B.17.1 Syntax
FACTORY_DEF <ReaderKeyword> SamplingFactory \
[INPUT FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* \
]* \
SAMPLE_RATE <sample rate>
B.17.2 Overview
This factory simply outputs every <sample rate>
th
feature it receives, other
features are simply deleted. If the INPUT clause is not specified then every feature is
input into the factory. This factory is useful for testing mapping files being developed
for large data sources as it can greatly reduce the number of features processed by the
system.
TIP: A sample rate of 1 will pass all features through the factory. This can be used to apply a feature function
to every feature that is translated.
B.17.3 Assumptions
None.
B.17.4 Output Tags
The SamplingFactory does not have any output clause. All features output by the
factory are unchanged from the state they had when they entered the factory.
B.17.5 Example
The following example passes one out of every five features through for further
processing by the FME. The other four features are deleted.
FACTORY_DEF Shape SamplingFactory \
SAMPLE_RATE 5
The second example uses the @Count function and a sampling rate to one to assign
a unique number to each feature as it passes through the FME.
FACTORY_DEF SAIF SamplingFactory \
INPUT FEATURE_TYPE * featNum @Count(features) \
SAMPLE_RATE 1
B-47 FME Reference Manual Version 2.0
FACTORY REFERENCE SDEQueryFactory
B.18 SDEQueryFactory
B.18.1 Syntax
FACTORY_DEF <ReaderKeyword> SDEQueryFactory \
INPUT FEATURE_TYPE <feature type> \
[<attribute Name> <attribute value>]* \
[<feature function>]* \
SDE_SERVER_FIELD <fieldName> \
SDE_DATASET_FIELD <fieldName> \
SDE_USERID_FIELD <fieldName> \
SDE_PASSWORD_FIELD <fieldName> \
TARGET_LAYER_FIELD <fieldName> \
SEARCH_METHOD_FIELD <fieldName> \
[FEATURE_TYPE_FIELD <fieldName>] \
[WHERE_CLAUSE_FIELD <fieldName>] \
[SPATIAL_FILTER_LAYER_FIELD <fieldName> \
SPATIAL_FILTER_ID_FIELD <fieldName> \
SPATIAL_FILTER_METHOD_FIELD <fieldName> \
SPATIAL_FILTER_TRUTH_FIELD <fieldName> \
] \
[CORRIDOR_DISTANCE_FIELD <fieldName>] \
[MAX_NUM_FIELD <fieldName>] \
[OUTPUT QUERY FEATURE_TYPE <feature type> \
[<attribute Name> <attribute value>]* \
[<feature function>]*] \
[OUTPUT RESULT FEATURE_TYPE <feature type> \
[<attribute Name> <attribute value>]* \
[<feature function>]*]
B.18.2 Overview
This factory can be used only in conjunction with ESRIs Spatial Database Engine. It
performs an SDE spatial query for each feature which it retrieves. The factory enables
SDE queries to be performed as part of the FME processing stream. The
SDEQueryFactory
2
is driven by input features which contain the specifics of the
query to be performed. For example, a simple user interface could create such query
features. These query features could then be run through the FME either immediately
or as a batch job when SDE activity from connected users is low. The
SDEQueryFactory is able take advantage of both the where clause and spatial filter
capabilities of the SDE. The use of the spatial filter enables complex spatial queries
to be performed.
TIP: Features which leave this factory are treated by the FME as if they originated from the READER being
used to drive the query.
2. When debugging an SDEQueryFactory specification use the MAX_NUM_FIELD value to avoid
consuming large amounts of system resources with erroneous searches.
SDEQueryFactory FACTORY REFERENCE
B-48 FME Reference Manual Version 2.0
The figure below illustrates the operation of the SDEQueryFactory:
B.18.3 SDEQueryFactory Processing
A feature flows into the SDEQueryFactory either from the reader module or from an
upstream factory. The features which the SDEQueryFactory accepts are called
QueryFeatures as the features specify the SDE Query which is to be performed.
The SDEQueryFactory then performs the query as identified by the query factory.
As features are returned from the SDE they are immediately passed out of the
SDEQueryFactory for immediate processing by the rest of the system. This
maximizes the amount of concurrent processing performed by the SDEQueryFactory
(client) and the SDE Server.
After the last feature has been returned by the SDE, the SDEQueryFactory then
passes the QueryFeature to the rest of the FME system.
B.18.4 Assumptions
The client has ESRIs SDE installed and running and has purchased the FME modules
for the SDE.
SDEQueryFactory Input Feature
SDE
Database
Result Features
QueryFeature
Downstream
Factory or
Writer Module
Upstream
Factory or
Reader Module
Query Result Features
B-49 FME Reference Manual Version 2.0
FACTORY REFERENCE SDEQueryFactory
B.18.5 Clauses
The following clauses are used to configure the SDEQueryFactory for a retrieval
operation:
Clauses Description Optional
SDE_SERVER_FIELD The name of the server machine which is to be
used to perform the query operation
No
SDE_DATASET_FIELD The name of the dataset upon which the query
is performed
No
SDE_USERID_FIELD The userid which is to be used to perform the
query.
No
SDE_PASSWORD_FIELD The password of the user. No
TARGET_LAYER_FIELD This field identifies the field of the search
feature which identifies the layer numbersfrom
which features are retrieved. If more than one
layer are to be specified in the field then the
layer numbers must be separated by colons.
No
FEATURE_TYPE_FIELD This is only specified when the
SDE_SEARCH_METHOD is equal to
SDE_IDENTICAL.
Yes
WHERE_CLAUSE_FIELD The name of the feature field which contains
the where clause used to perform attribute
filtering.
Yes
SPATIAL_FILTER
_LAYER_FIELD
This is specified only if a spatial filter is to be
used during the query operation. This contains
the name of the field which identifies the layer
number containing the spatial filter feature.
Yes
SPATIAL_FILTER
_ID_FIELD
This is specified only if a spatial filter is to be
used during the query operation. This contains
the name of the filed which identifies the
feature id to be used for the spatial filter.
Yes
SPATIAL_FILTER
_METHOD_FIELD
The field specified here identifies the type of
relationship which the search feature is to have
with the returned feature. See the description
of the different relationships under the
discussion of SEARCH_METHOD_FIELD.
See the SPATIAL_FILTER_TRUTH value
below.
Yes
SPATIAL_FILTER
_TRUTH_FIELD
The field specified here identifies if the
relationship specified by SPATIAL
_FILTER_METHOD is to be negated. If the
value specified is TRUE then the relation
specified by SPATIAL_ FILTER_METHOD
must be TRUE for a feature to be returned. If
the value specified is FALSE then the relation
specified by SPATIAL_FILTER _METHOD
must be FALSE.
Yes
SDEQueryFactory FACTORY REFERENCE
B-50 FME Reference Manual Version 2.0
CORRIDOR_DISTANCE
_FIELD
This field is specified if a buffer is to be
constructed around the search feature. The
field specifies the size of the buffer to be used
around this specified feature. The buffered
feature is then used as the search feature.
Yes
SEARCH_METHOD_FIELD This field identifies the type of search method
which is used to perform the query. Values
currently supported are the following:
No
SDE_ENVELOPE - The envelope of the
returned feature overlaps or touches the
envelope of the search feature.
SDE_COMMON_POINT - The search feature
shares at least one common point.
SDE_LINE_CROSS - The search feature
and the returned feature have line segments
which intersect.
SDE_COMMON_LINE - The search feature
and the returned feature share one or more
common line segments.
SDE_CP_OR_LC - The search feature and the
returned feature have line segments which
intersect or have a common point.
SDE_AI_OR_ET - The search feature and
the returned area feature edge touch (ET) or
their areas intersect (AI).
SDE_AREA_INTERSECT - The search
feature and the returned feature's area intersect.
SDE_AI_NO_ET - The returned feature and
search feature have intersecting areas with no
edge touching. One feature is thus contained in
the other.
SDE_CONTAINED_IN - The search feature
is contained in the returned feature. For area
features this is clear. If search feature is a line
then a linear feature is returned if the search
feature path is included in returned feature. If
search feature is a point then the search feature
is one of the returned features vertices.
SDE_CONTAINS - The returned feature is
contained by the search feature. If both
features are linear features then the returned
feature must lie on the search feature's path.
Point features which lie on a search feature
vertex are also returned.
Clauses Description Optional
B-51 FME Reference Manual Version 2.0
FACTORY REFERENCE SDEQueryFactory
B.18.6 Output Tags
The SDEQueryFactory supports the following output tags.
B.18.7 Example
The example below uses a pseudo ARCGEN file to contain the query information.
The contents of the ARCGEN file and the FME mapping file which perform the query
operation are given. Notice the use of MACRO statements on the SDE feature
correlation lines. The use of macros in this way enables the FME to process the
features which are returned from the SDEQueryFactory as if they are ARCGEN
features even though in fact they come from the SDE. This is made possible by the
architecture of the FME which decouples the _DEF lines from the correlation lines.
SDE_CONTAINED_IN_NO_ET - The
returned feature must be an area feature which
doesnt touch or share a vertex with the search
feature. The returned features contain the
search feature.
SDE_CONTAINS_NO_ET - The returned
feature is contained within the search feature.
The returned features cannot touch the edge of
or share a vertex with the search feature.
SDE_POINT_IN_POLY - The returned
feature contains the first point of the search
feature.
SDE_CENTROID_IN_POLY - The returned
features centroid (as by SDE) is contained in
the search feature.
SDE_IDENTICAL - The returned feature
has the same feature type and geometry. This is
used to find duplicate data.
MAX_NUM_FIELD This identifies the maximum number of
features which can be returned by the query.
This is used to ensure that an unexpectedly
large number of result features are not
accidentally returned.
YES
Tag Description
QUERY The query feature which entered the factory.
RESULT Each of the features which satisfied the query.
Clauses Description Optional
SDEQueryFactory FACTORY REFERENCE
B-52 FME Reference Manual Version 2.0
# ==============================================
# SDEQueryFactory example.
# ==============================================
# --------------------------------------------------------------
# Global SDE information.
MACRO SDE_DATASET_NAME sample
MACRO SDE_SERVER tuvok
# The following two MACROS are not specified here as they
# are specified on the command line. This keeps password
# information confidential.
MACRO SDE_USERID
MACRO SDE_PASSWORD test
# --------------------------------------------------------------
# Things the FME needs to know so it knows which direction we are
# going:
# The data which is retrieved from the SDEQueryFactory is written
# to SHAPE.
READER_TYPE ARCGEN
WRITER_TYPE SHAPE
# The arcgen dataset is the current directory. Could be specified
# on the command line.
ARCGEN_DATASET.
# ARCGEN definitions
ARCGEN_DEF quryline ARCGEN_GEOMETRY arcgen_line
# The output shape dataset which contains the result of the query
# operation is also stored within the current directory.
SHAPE_DATASET.
# --------------------------------------------------------------
# This macro is used to define the correlation line of the SDE.
# This enables different input features (other than arcgen)
# to be used to drive the SDEQueryFactory. It also enables the
# original correlation lines which were used during the SDE
# loading operation to be used for the SDEQueryFactory thereby
# greatly reducing the amount of configuration information which is
# required.
MACRO SDE_SOURCE ARCGEN
#
# This included file contains the SDE correlation lines.
# This relies on the MACRO SDE_SOURCE_ARCGEN
# being defined. The contents of the include file is immediately
# following this file.
INCLUDE ascisde.cor
# Now for the factory definition.
#
# Notice the use of the Split command to break apart the
# ARCGEN feature id into component parts. One must be
# careful to ensure that the feature generated matches
# the correlation line specified here. See the input
# Arcgen file.
B-53 FME Reference Manual Version 2.0
FACTORY REFERENCE SDEQueryFactory
#
# Also notice how the SupplyAttribute command is used to
# set the value of many of the other attributes which drive
# the factory.
FACTORY_DEF ARCGEN SDEQueryFactory \
INPUT FEATURE_TYPE quryline \
@Split(&arcgen_id,|,target_layer,search_method,corDist) \
@SupplyAttributes(sde_server, $(SDE_SERVER) ) \
@SupplyAttributes(sde_dataset, $(SDE_DATASET_NAME \
@SupplyAttributes(sde_user_id, $(SDE_USERID) ) \
@SupplyAttributes(sde_password, $(SDE_PASSWORD) ) \
@SupplyAttributes(spflayer, 1007) \
@SupplyAttributes(spfid, 14) \
@SupplyAttributes(spfmethod, SDE_CP_OR_LC) \
@SupplyAttributes(spftruth, FALSE) \
SDE_SERVER_FIELD sde_server \
SDE_DATASET_FIELD sde_dataset \
SDE_USERID_FIELD sde_user_id \
SDE_PASSWORD_FIELD sde_password \
CORRIDOR_DISTANCE_FIELD corDist \
TARGET_LAYER_FIELD target_layer \
SEARCH_METHOD_FIELD search_method \
WHERE_CLAUSE_FIELD where_clause \
SPATIAL_FILTER_LAYER_FIELD spflayer \
SPATIAL_FILTER_ID_FIELD spfid \
SPATIAL_FILTER_METHOD_FIELD spfmethod \
SPATIAL_FILTER_TRUTH_FIELD spftruth \
OUTPUT RESULT FEATURE_TYPE *
Now the contents of the include file. This illustrates how the clever use of macros can
greatly reduce the amount of FME correlation information which must be maintained.
#
# Notice the SDE_SOURCE macro which was defined by the file which
included
# this one. This enables the same correlation pair to be used for
# many different purposes.
MACRO SDE_BASENAME Cadastral
$(SDE_SOURCE) OriginalQuarterSection::$(SDE_BASENAME) \
PPID %1 \
QSECIDENT %2 \
PARENTSECTION %3 \
INSIDEPOINT.X %inX \
INSIDEPOINT.Y %inY \
DATECHNG %yyyymmdd \
BOUNDARY %7
SHAPE oqsect \
PPID %1 \
QSECID %2 \
PRNTOSEC %3 \
INSIDEX %inX \
INSIDEY %inY \
DATECHNG %yyyymmdd \
BOUNDARY{} %7 \
SDEQueryFactory FACTORY REFERENCE
B-54 FME Reference Manual Version 2.0
Finally, the contents of the Arc Generate file which represents an input query feature.
The example contains a single feature. In reality, one could use a file with many
batched query features which could be used to solve many different queries and write
them to an output file.
# The first line of the feature is the line which is split into its
# component pieces using the Split command on the SDEQueryFactory
# definition. This relies on the FMEs liberal interpretation of the
# ARCGEN format specification.
1008|SDE_CP_OR_LC|10
538000,5595000
545000,5600000
END
END
B-55 FME Reference Manual Version 2.0
FACTORY REFERENCE SortFactory
B.19 SortFactory
B.19.1 Syntax
FACTORY_DEF <ReaderKeyword> SortFactory \
[INPUT FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* \
]* \
SORT_BY [<attrName (NUMERIC|ALPHA)>]+ \
[SORT_DIRECTION (ASCENDING|DESCENDING)] \
OUTPUT SORTED FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]*
B.19.2 Overview
This factory sorts features according to the values of the specified attributes, as
specified by the factory definition. For each attribute name, directions are given as to
how the its value should be interpreted when it is compared. If NUMERIC is specified,
then numeric comparisons will be done, otherwise, if ALPHA is specified, then
alphanumeric comparisons will be done.
Once the factory is told to empty itself, it will output all the features it received in the
order specified by SORT_DIRECTION. By default, the SORT_DIRECTION is
ascending.
If an attribute name is specified but is not present on a feature, then the sorting
algorithm considers that feature to have a blank or zero value for that attribute.
An O(nlogn) algorithm is used to do the sorting.
B.19.3 Assumptions
None.
B.19.4 Output Tags
The SortFactory supports the following output tags.
Tag Description
SORTED Applied to all features which leave the factory.
SortFactory FACTORY REFERENCE
B-56 FME Reference Manual Version 2.0
B.19.5 Example
The following example shows how the SortFactory can be used to order features by
their areas:
FACTORY_DEF SHAPE SortFactory \
INPUT FEATURE_TYPE * myarea @Area() \
SORT_BY myarea NUMERIC \
SORT_DIRECTION ASCENDING \
OUTPUT SORTED FEATURE_TYPE * sizeRanking @Count(sizeRanking)
B-57 FME Reference Manual Version 2.0
FACTORY REFERENCE TeeFactory
B.20 TeeFactory
B.20.1 Syntax
FACTORY_DEF <ReaderKeyword> TeeFactory \
[INPUT FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* \
]* \
[OUTPUT FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* \
]+ \
B.20.2 Overview
This factory implements a T junction in the factory pipeline. It replicates each feature
that matches the input specification, and outputs a copy of the feature for each
OUTPUT clause which is specified. The output clauses may change the features type
or otherwise alter the feature as it goes through. If the INPUT clause is not specified
then every feature is input into the factory. This factory is useful when copies of
features need to be generated for further processing by other factories, or for output
to different layers or themes in the output dataset.
B.20.3 Assumptions
None.
B.20.4 Output Tags
Each output clause is applied to all input features, so this factory does not have any
output clauses.
B.20.5 Example
The following example employs the TeeFactory to make three copies of each
Road::TRIM feature that flows through the pipeline. The first copy is output by the
first OUTPUT clause, and flows through the pipeline unchanged since this clause does
nothing to it. The second copy has its feature type changed to Douglased, and has
its geometry generalized using the Douglas algorithm with a tolerance of 20 meters.
The third copy has its feature type changed to deveaued, and has its geometry
generalized using the Deveau algorithm with a tolerance of 10 meters, 3 wedges, and
a 100 degree blunting angle.
TeeFactory FACTORY REFERENCE
B-58 FME Reference Manual Version 2.0
FACTORY_DEF SAIF TeeFactory \
INPUT FEATURE_TYPE Road::TRIM \
OUTPUT FEATURE_TYPE * \
OUTPUT FEATURE_TYPE Douglased \
@Generalize(Douglas,20) \
OUTPUT FEATURE_TYPE deveaued \
@Generalize(Deveau,10,3,100)
B-59 FME Reference Manual Version 2.0
FACTORY REFERENCE TestFactory
B.21 TestFactory
B.21.1 Syntax
FACTORY_DEF <ReaderKeyword> TestFactory \
[INPUT FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* \
]* \
TEST <value> <operator> <value> \
[OUTPUT PASSED|FAILED FEATURE_TYPE <feature Type> \
[<attribute Name> <attribute value>]* \
[<feature function> ]* \
]+ \
B.21.2 Overview
This factory takes a feature and performs the test defined by the TEST clause. If the
result of the test is true then the feature is output via the PASSED tag. If the result is
false then the feature is output via the FAILED tag.
If the PASSED clause is not specified, then features which pass the test will be
destroyed. If the FAILED clause is not specified, then features which fail the test will
be destroyed. One of PASSED or FAILED must be present.
<operator> is one of <, >, =, !=, >=, <=
<value> may be a literal constant, an attribute name preceded by the value-of
operator (&), or an attribute value function. If it is an attribute value function, the
function is executed on the current feature and the result used for the test.
Example TEST clauses include:
TEST @Area() < 100
TEST &numLanes > 2
TEST Joe = Jerry
The TestFactory decides at run time to invoke numeric comparisons or string
comparisons as greater than and less than have different meanings depending on the
type of the operands. If both arguments may be converted to numbers, then numeric
comparisons are used, otherwise string comparisons are.
B.21.3 Assumptions
None.
TestFactory FACTORY REFERENCE
B-60 FME Reference Manual Version 2.0
B.21.4 Output Tags
The TestFactory supports the following output tags.
B.21.5 Example
The following example shows how the TestFactory can be used to perform area
generalization on area features.
The first factory defined below deletes all area features which have an area less than
1000 square ground units:
FACTORY_DEF SHAPE TestFactory \
INPUT FEATURE_TYPE * fme_geometry fme_polygon \
TEST @Area() < 1000 \
OUTPUT FAILED FEATURE_TYPE *
The second factory converts all area features which have an area less than 10000
square ground units to a point and passes the rest on to the third factory.
FACTORY_DEF SHAPE TestFactory \
INPUT FEATURE_TYPE * fme_geometry fme_polygon \
TEST @Area() < 10000 \
OUTPUT PASSED FEATURE_TYPE Point @ConvertToPoint() \
OUTPUT FAILED FEATURE_TYPE *
The final factory converts all remaining area features with a circularity less than 0.25
to a line and point-thins those with a circularity greater than or equal to 0.25.
FACTORY_DEF SHAPE TestFactory \
INPUT FEATURE_TYPE * fme_geometry fme_polygon \
TEST @Circularity() < 0.25 \
OUTPUT PASSED FEATURE_TYPE Line @ConvertToLine(100) \
OUTPUT FAILED FEATURE_TYPE Polygon @Generalize(Douglas, 100)
Tag Description
PASSED Applied to features for which TEST clause is true.
FAILED Applied to features for which the TEST clause is false.
C-1 FME Reference Manual Version 2.0
C
C ACRONYMS
The following acronyms are found in the Feature Manipulation Engine
Reference Manual.
2D two-dimension(al)
3D three-dimension(al)
API Application Programming Interface
ASCII American National Standard Code for Information
Interchange
BC British Columbia (Canada)
CAD Computer Aided Design
CAT Column Aligned Text
CD-ROM Compact DiskRead Only Memory
CSN Class Syntax Notation
CSV Comma Separated Value
DBF dBASE file
DCW Digital Chart of the World
DEF DEFinition
DEM Digital Elevation Model
DLG Digital Line Graph
DLL Dynamic Loading of software Libraries
ACRONYMS Safe Software Inc.
C-2 FME Reference Manual Version 2.0
DNC Digital Nautical Chart
DWG Drawing
DXF Drawing eXchange File
ESRI Environmental Systems Research Institute
FCS Feature Class Schema
FME Feature Manipulation Engine
GIF Graphics Interchange Format
GIS Geographical Information Systems
GOID Geographic Object IDentifier
GMT Greenwich Mean Time
GUI Graphical User Interface
ID Identification, Identifier
IGDS Interactive Graphics Design System
I/O Input/Output
ISFF Intergraph Standard File Format
LAT Latitude
LNG Longitude
lut lookup table
MID/MIF MapInfo Data Interchange Format
MIL-STD Military Standard
MIS Management Information Services
MOEP Ministry Of Environment and Parks
NAD North American Datum
NDCDB National Digital Cartographic Database
OGIS Open Geodata Interoperability Specification
OSN Object Syntax Notation
PIP Point-In-Polygon
PLSS Public Land Survey System
PO This is the Political and Oceans coverage in a DCW library.
RDBMS Relational DataBase Management System
SAIF Spatial Archive and Interchange Format
SDE Spatial Database Engine
C-3 FME Reference Manual Version 2.0
Safe Software Inc. ACRONYMS
TAB Table
TCB Terminal Control Block
TCL Tool Command Language
UOR Units of Resolution
USGS United States Geological Survey
UTC Universal Coordinated Time
UTM Universal Transverse Mercator
VDT Value Descriptor Tables
VPF Vector Product Format
ACRONYMS Safe Software Inc.
C-4 FME Reference Manual Version 2.0