You are on page 1of 520

Reference Manual

Safe Software Inc.


E-mail: support@safe.com
Internet: http://www.safe.com
Safe Software Inc. makes no warranty either expressed or implied, including, but not limited to, any implied warranties of
merchantability or fitness for a particular purpose regarding these materials, and makes such materials available solely on an as-is
basis.
In no event shall Safe Software Inc. be liable to anyone for special, collateral, incidental, or consequential damages in connection with
or arising out of purchase or use of these materials. The sole and exclusive liability of Safe Software Inc., regardless of the form or action,
shall not exceed the purchase price of the materials described herein.
This manual describes the functionality and use of the Feature Manipulation Engine at the time of publication. The software des cribed
herein and the descriptions themselves, are subject to change without notice.
Copyright
This document has been written and produced by Safe Software Inc. All rights are reserved.
Revisions
Every effort has been made to ensure the accuracy of this document. Safe Software Inc. regrets any errors and omissions that may occur
and would appreciate being informed of any errors found. Safe Software Inc. will correct any such errors and omissions in a subsequent
version, as feasible. Please contact us at:
Safe Software Inc.
Fax: (604) 501-9965
E-mail: support@safe.com
Web: http://www.safe.com
Safe Software Inc. assumes no responsibility for any errors in this document or their consequences, and reserves the right to make
improvements and changes to this document without notice.
Trademarks
Product names mentioned in this document may be trademarks of Safe Software Inc. or other hardware, software, or service providers
and are used herein for identification purposes only.
ARCInfo is a registered trademark of Environmental Systems Research Institute.
AutoCAD is a registered trademark of AutoDesk Inc.
FME is a registered trademark of Safe Software Inc.
Intergraph is a registered trademark of Intergraph Inc.
MapInfo is a registered trademark of MapInfo Corporation.
MicroStation is a registered trademark of Bentley Systems Inc.
Phocus Phodat is a registered trademark of Karl-Zeiss Inc.
Spatial Database Engine is a registered trademark of Environmental Systems Research Institute.
Re-Ordering Information
Document Name: FME Reference Manual
Version: 2.0
July 1997
Fourth Printing
FME Reference ManualVersion 2.0 (iii)
Table of Contents
About This Manual
Intended Audience .................................................................................................. xxiii
Using This Manual .................................................................................................. xxiv
About Each Section ................................................................................................ xxiv
Conventions Used in this Guide ............................................................................ xxvii
For More Information ........................................................................................... xxviii
1 INTRODUCTION
1.1 Overview ................................................................................................................... 1-1
1.2 Data Source Merging ................................................................................................ 1-2
1.3 Topology Operations ................................................................................................ 1-3
1.4 Geometric Operations ............................................................................................... 1-3
1.5 Attribute Operations ................................................................................................. 1-4
1.6 Coordinate System Conversion ................................................................................ 1-4
1.7 Summary ................................................................................................................... 1-5
2 FME ARCHITECTURE
2.1 FME Features ............................................................................................................ 2-2
2.2 Reader Modules ........................................................................................................ 2-3
2.3 Functions ................................................................................................................... 2-4
2.4 Feature Factory Pipeline ........................................................................................... 2-5
2.5 Transformation Module ............................................................................................ 2-5
2.6 Writer Modules ......................................................................................................... 2-5
2.7 Mapping File ............................................................................................................. 2-6
FME Reference Manual Version 2.0 (iv)
Safe Software Inc. Table of Contents
3 FME FUNCTIONS
3.1 Function Parameters ................................................................................................. 3-2
3.1.1 Constants ....................................................................................................... 3-3
3.1.2 Transfer Variables ......................................................................................... 3-3
3.1.3 Attribute Values ............................................................................................ 3-3
3.1.4 Attribute Functions ....................................................................................... 3-3
3.1.5 Composites .................................................................................................... 3-4
3.2 Forward Function Example ...................................................................................... 3-4
3.3 Inverse Function Example ........................................................................................ 3-5
3.4 Function Configuration ............................................................................................. 3-6
3.5 User Defined Functions ............................................................................................ 3-6
4 FME FEATURE FACTORIES
4.1 Factory Architecture ................................................................................................. 4-2
4.1.1 Input Interface ............................................................................................... 4-2
4.1.2 Feature Processing Unit ................................................................................ 4-3
4.1.3 Output Interface ............................................................................................ 4-3
4.2 Factory Activation Sequence .................................................................................... 4-3
4.3 Factory Pipeline ........................................................................................................ 4-4
4.4 Factory Definitions ................................................................................................... 4-4
4.4.1 FACTORY_DEF .......................................................................................... 4-5
4.4.2 INPUT ........................................................................................................ 4-5
4.4.3 Factory Specific Directives ........................................................................... 4-6
4.4.4 GROUP_BY ................................................................................................. 4-6
4.4.5 OUTPUT ....................................................................................................... 4-6
4.5 Factory Example 1 .................................................................................................... 4-7
4.6 Factory Example 2 .................................................................................................... 4-8
5 FME TRANSLATION PROCESS
5.1 Transformation Specification ................................................................................... 5-1
5.1.1 Source Line ................................................................................................... 5-3
5.1.2 Destination Line ............................................................................................ 5-3
5.1.3 Example ........................................................................................................ 5-4
5.1.4 Matching Process .......................................................................................... 5-4
5.2 Transfer Variables .................................................................................................... 5-5
5.3 Default Attribute Values ........................................................................................... 5-6
6 FME MAPPING FILE SYNTAX
6.1 Overview ................................................................................................................... 6-1
6.2 Line Continuation ..................................................................................................... 6-1
6.3 Quoted Text .............................................................................................................. 6-2
6.4 Single Line Comments ............................................................................................. 6-2
6.5 Block Comments ...................................................................................................... 6-3
(v) FME Reference Manual Version 2.0
Table of Contents Safe Software Inc.
6.6 MACRO Directive .................................................................................................... 6-3
6.7 Predefined Macros .................................................................................................... 6-4
6.8 DEFAULT_MACRO Directive ................................................................................ 6-5
6.9 INCLUDE Directive ................................................................................................. 6-5
6.10 Environment Variable Expansion ............................................................................. 6-6
6.11 Static Function Evaluation ........................................................................................ 6-6
7 FME CONFIGURATION
7.1 Reader and Writer Selection ..................................................................................... 7-1
7.2 Reader and Writer Keywords ................................................................................... 7-2
7.3 Log File Configuration ............................................................................................. 7-3
7.4 Mapping File Debugging .......................................................................................... 7-4
8 COORDINATE SYSTEM SUPPORT
8.1 Overview ................................................................................................................... 8-1
8.2 Coordinate System Identification ............................................................................. 8-2
8.3 Coordinate System Definition .................................................................................. 8-3
8.3.1 Example Coordinate System Definitions ...................................................... 8-4
8.3.2 Local Coordinate System Definitions ........................................................... 8-4
8.4 Coordinate Units ....................................................................................................... 8-5
8.4.1 Unit Definition .............................................................................................. 8-5
8.4.2 Example Unit Definition ............................................................................... 8-6
8.5 Projection Types ....................................................................................................... 8-6
8.5.1 AE: Albers Equal Area ................................................................................. 8-8
8.5.2 AZMED: Lambert Azimuthal Equidistant Projection .................................. 8-8
8.5.3 AZMEA: Lambert Azimuthal Equal Area Projection ................................ 8-10
8.5.4 BONNE: Bonne Projection ......................................................................... 8-11
8.5.5 BIPOLAR: Bipolar Oblique Conformal Conic .......................................... 8-11
8.5.6 EDCNC: Equidistant Conic Projection ....................................................... 8-12
8.5.7 EDCYL: Equidistant Cylindrical Projection .............................................. 8-12
8.5.8 ECKERT4: Eckert 4 Projection .................................................................. 8-13
8.5.9 ECKERT6: Eckert 6 Projection .................................................................. 8-13
8.5.10 GNOMONIC: Gnomonic Projection .......................................................... 8-14
8.5.11 GOODE: Goode Homolosine Projection .................................................... 8-14
8.5.12 LM: Lambert Conformal Conic Projection ................................................ 8-15
8.5.13 LMTAN: Lambert Tangential Projection ................................................... 8-15
8.5.14 LL: Latitude/Longitude ............................................................................... 8-16
8.5.15 MILLER: Miller Cylindrical Projection ..................................................... 8-17
8.5.16 MODPC: Modified Polyconic Projection ................................................... 8-17
8.5.17 MOLLWEID: Mollweide Projection .......................................................... 8-18
8.5.18 MRCAT: Traditional Mercator Projection ................................................. 8-18
8.5.19 MSTERO: Modified Stereographic Projection ........................................... 8-19
8.5.20 NEACYL: Normal Authalic Cylindrical Projection ................................... 8-19
FME Reference Manual Version 2.0 (vi)
Safe Software Inc. Table of Contents
8.5.21 NZEALAND: New Zealand National Grid System ................................... 8-20
8.5.22 ORTHO: Orthographic Projection .............................................................. 8-20
8.5.23 PLYCN: American Polyconic Projection ................................................... 8-20
8.5.24 ROBINSON: Robinson Projection ............................................................. 8-21
8.5.25 SINUS: Sinusoidal Projection .................................................................... 8-21
8.5.26 STERO: Stereographic Projection .............................................................. 8-22
8.5.27 TEACYL: Transverse Authalic Projection ................................................. 8-23
8.5.28 TM: Transverse Mercator ........................................................................... 8-24
8.5.29 VDGRNTN: Van Der Grinten Projection .................................................. 8-24
8.6 Datums .................................................................................................................. 8-25
8.6.1 Datum Definition ........................................................................................ 8-29
8.6.2 Example Datum Definition ......................................................................... 8-30
8.6.3 Datum Shift Issues for North American Users ........................................... 8-31
8.7 Predefined Ellipsoids .............................................................................................. 8-32
8.7.1 Ellipsoid Definition ..................................................................................... 8-34
8.7.2 Example Ellipsoid Definition ..................................................................... 8-35
9 FME INTERFACES
9.1 Command Line Interface .......................................................................................... 9-1
9.1.1 Overriding Mapping File Settings ................................................................ 9-1
9.1.2 Extending Mapping File Settings ................................................................. 9-2
9.1.3 Defining Macros ........................................................................................... 9-2
9.1.4 Automated Mapping File Generation ........................................................... 9-3
9.2 FME Configurable User Interface ............................................................................ 9-3
9.2.1 User Interface Directives .............................................................................. 9-4
9.2.2 Dialog Box Title ........................................................................................... 9-4
9.2.2.1 Filename Parameters ...................................................................... 9-4
9.2.2.2 Directory Parameters ..................................................................... 9-5
9.2.2.3 Integers Parameters ........................................................................ 9-6
9.2.2.4 Floating Point Parameters .............................................................. 9-6
9.2.2.5 Text Parameters ............................................................................. 9-7
9.2.2.6 Password Parameters ..................................................................... 9-7
10 AUTOCAD DWG/DXF READER/WRITER
10.1 Overview ................................................................................................................. 10-1
10.2 Reader Overview .................................................................................................... 10-3
10.2.1 Reader Keywords ........................................................................................ 10-4
10.2.2 Block Resolution ......................................................................................... 10-4
10.3 Writer Overview ..................................................................................................... 10-4
10.3.1 Writer Keywords ......................................................................................... 10-6
10.3.2 DATASET .................................................................................................. 10-7
10.3.3 VERSION ................................................................................................... 10-7
10.3.4 TEMPLATEFILE ....................................................................................... 10-7
(vii) FME Reference Manual Version 2.0
Table of Contents Safe Software Inc.
10.3.5 LineType Representation ............................................................................ 10-8
10.3.6 Layer Representation .................................................................................. 10-9
10.4 Feature Representation ......................................................................................... 10-10
10.4.1 Extended Entity Data ................................................................................ 10-11
10.4.2 List Format ................................................................................................ 10-11
10.4.3 Structure Format ....................................................................................... 10-13
10.4.4 Interpreted Format .................................................................................... 10-15
10.4.5 Lines .................................................................................................... 10-16
10.4.6 XLines .................................................................................................... 10-16
10.4.7 Points .................................................................................................... 10-16
10.4.8 Ellipses .................................................................................................... 10-17
10.4.9 Shapes .................................................................................................... 10-17
10.4.10Polygons .................................................................................................... 10-19
10.4.11Faces .................................................................................................... 10-19
10.4.12Arcs .................................................................................................... 10-19
10.4.13Traces .................................................................................................... 10-21
10.4.14Solids .................................................................................................... 10-21
10.4.15Rays .................................................................................................... 10-21
10.4.16Text Entities .............................................................................................. 10-21
10.4.17Inserts .................................................................................................... 10-23
10.5 AutoCAD Mapping File Example 1 ..................................................................... 10-24
10.6 AutoCAD Mapping File Example 2 ..................................................................... 10-30
11 B.C. MINISTRY OF ENVIRONMENT AND PARKS (MOEP)
READER/WRITER
11.1 Overview ................................................................................................................. 11-1
11.2 Reader Overview .................................................................................................... 11-2
11.3 Reader Keywords .................................................................................................... 11-2
11.3.1 DATASET .................................................................................................. 11-2
11.3.2 DEF ...................................................................................................... 11-3
11.3.3 IDs ...................................................................................................... 11-4
11.4 Writer Overview ..................................................................................................... 11-4
11.5 Writer Keywords .................................................................................................... 11-4
11.6 Feature Representation ........................................................................................... 11-5
11.6.1 Line Features ............................................................................................... 11-5
11.6.2 Contour Features ......................................................................................... 11-6
11.6.3 Point Features ............................................................................................. 11-6
11.6.4 Arc Features ................................................................................................ 11-7
11.6.5 Text Features ............................................................................................... 11-7
11.7 MOEP Mapping File Example 1 ............................................................................ 11-8
11.8 MOEP Mapping File Example 2 .......................................................................... 11-11
FME Reference Manual Version 2.0 (viii)
Safe Software Inc. Table of Contents
12 DESIGN FILE READER/WRITER
12.1 Overview ................................................................................................................. 12-1
12.2 Reader Overview .................................................................................................... 12-3
12.3 Reader Keywords .................................................................................................... 12-3
12.4 Writer Overview ..................................................................................................... 12-4
12.5 Writer Keywords .................................................................................................... 12-5
12.6 Feature Representation ........................................................................................... 12-6
12.6.1 Attribute Linkages ...................................................................................... 12-7
12.6.2 Cells ...................................................................................................... 12-9
12.6.3 Points .................................................................................................... 12-10
12.6.4 Lines .................................................................................................... 12-10
12.6.5 Shapes .................................................................................................... 12-11
12.6.6 Text Nodes ................................................................................................ 12-11
12.6.7 Curves .................................................................................................... 12-13
12.6.8 Ellipses .................................................................................................... 12-13
12.6.9 Arcs .................................................................................................... 12-14
12.6.10Text Strings ............................................................................................... 12-16
12.6.11Multi Text Strings ..................................................................................... 12-17
12.6.12Solids .................................................................................................... 12-19
12.7 IGDS Mapping File Example ............................................................................... 12-20
13 DIGITAL LINE GRAPH READER
13.1 Overview ................................................................................................................. 13-1
13.2 Reader Overview .................................................................................................... 13-2
13.2.1 Reader Keywords ........................................................................................ 13-3
13.2.1.1 Dataset .............................................................................. 13-3
13.2.2 Feature Representation ............................................................................... 13-3
13.2.3 Points ...................................................................................................... 13-5
13.2.4 Lines ...................................................................................................... 13-6
13.2.5 Areas ...................................................................................................... 13-7
13.3 Features Created by Generated DLG Mapping Files ............................................. 13-7
13.3.1 Feature Representation ............................................................................... 13-7
13.3.2 DLG Attributes ........................................................................................... 13-8
13.3.3 Hypsography ............................................................................................... 13-9
13.3.4 Hydrography ............................................................................................. 13-10
13.3.5 Vegetative Surface Cover ......................................................................... 13-10
13.3.6 Non-Vegetative Features .......................................................................... 13-10
13.3.7 Boundaries ................................................................................................ 13-11
13.3.8 Survey Control and Markers ..................................................................... 13-11
13.3.9 Roads and Trails ....................................................................................... 13-12
13.3.10Railroads ................................................................................................... 13-12
13.3.11Pipelines, Transmission Lines, and Miscellaneous Transportation
Features .................................................................................................... 13-13
(ix) FME Reference Manual Version 2.0
Table of Contents Safe Software Inc.
13.3.12Man-made Features ................................................................................... 13-13
13.3.13U.S. Public Land Survey System .............................................................. 13-13
13.4 Example ................................................................................................................ 13-14
14 ESRI ARCINFO EXPORT FORMAT (E00) READER
14.1 Overview ................................................................................................................. 14-1
14.2 Reader Keywords .................................................................................................... 14-2
14.3 Feature Representation ........................................................................................... 14-2
14.3.1 Geometry Composition ............................................................................... 14-2
14.3.2 Feature Types .............................................................................................. 14-3
14.3.3 Text Representation .................................................................................... 14-6
14.3.4 Tolerances ................................................................................................... 14-8
14.3.5 Projections .................................................................................................. 14-8
14.4 Info Files ................................................................................................................. 14-9
14.5 Generated Mapping Files ........................................................................................ 14-9
14.5.1 Arc Features ................................................................................................ 14-9
14.5.2 Point Features ........................................................................................... 14-10
14.5.3 Polygon Features ....................................................................................... 14-11
14.5.4 Text and Textarrow Features .................................................................... 14-11
14.6 E00 Mapping File Example .................................................................................. 14-13
15 ESRI ARCINFO GENERATE FILE READER/WRITER
15.1 Overview ................................................................................................................. 15-1
15.2 Reader Overview .................................................................................................... 15-1
15.3 Reader Keywords .................................................................................................... 15-2
15.3.1 DATASET .................................................................................................. 15-2
15.3.2 DEF ...................................................................................................... 15-2
15.3.3 IDs ...................................................................................................... 15-3
15.4 Writer Overview ..................................................................................................... 15-3
15.5 Writer Keywords .................................................................................................... 15-3
15.6 Feature Representation ........................................................................................... 15-4
15.6.1 Points ...................................................................................................... 15-4
15.6.2 Lines ...................................................................................................... 15-4
15.6.3 Text ...................................................................................................... 15-5
15.7 Example .................................................................................................................. 15-6
16 ESRI SHAPE FILE READER/WRITER
16.1 Overview ................................................................................................................. 16-1
16.2 Reader Overview .................................................................................................... 16-3
16.3 Reader Keywords .................................................................................................... 16-3
16.3.1 DATASET .................................................................................................. 16-4
16.3.2 DEF ...................................................................................................... 16-4
16.3.3 IDs ...................................................................................................... 16-5
16.4 Writer Overview ..................................................................................................... 16-6
FME Reference Manual Version 2.0 (x)
Safe Software Inc. Table of Contents
16.5 Writer Keywords .................................................................................................... 16-6
16.6 Feature Representation ........................................................................................... 16-6
16.7 Example .................................................................................................................. 16-7
17 ESRI SDE READER/WRITER
17.1 Overview ................................................................................................................. 17-2
17.2 FME SDE Highlights .............................................................................................. 17-3
17.3 Reader Overview .................................................................................................... 17-4
17.4 Reader Keywords .................................................................................................... 17-5
17.4.1 DATASET .................................................................................................. 17-5
17.4.2 SERVER ..................................................................................................... 17-5
17.4.3 USERID ...................................................................................................... 17-6
17.4.4 PASSWORD ............................................................................................... 17-6
17.4.5 Where ...................................................................................................... 17-6
17.4.6 SEARCH_ENVELOPE .............................................................................. 17-7
17.4.7 LOGFILE .................................................................................................... 17-7
17.4.8 IDs ...................................................................................................... 17-7
17.4.9 Complete Reader Example ......................................................................... 17-8
17.5 Writer Overview ..................................................................................................... 17-8
17.6 Writer Keywords .................................................................................................... 17-9
17.6.1 SDE_LogFile .............................................................................................. 17-9
17.6.2 SDE_Transaction ...................................................................................... 17-10
17.7 SDE Layer Representation ................................................................................... 17-10
17.7.1 <layerName> ............................................................................................ 17-11
17.7.2 SDE_Base_Layer ...................................................................................... 17-11
17.7.3 SDE_Layer ................................................................................................ 17-12
17.7.4 SDE_Grid{0} ............................................................................................ 17-12
17.7.5 SDE_Grid{1} ............................................................................................ 17-12
17.7.6 SDE_Grid{2} ............................................................................................ 17-12
17.7.7 SDE_Dimension ....................................................................................... 17-13
17.7.8 SDE_AVERAGE_PTS ............................................................................. 17-13
17.7.9 SDE_INIT_NUM_FEATS ....................................................................... 17-13
17.7.10SDE_CONFIG_KEYWORD .................................................................... 17-13
17.7.11SDE_Geometry ......................................................................................... 17-13
17.7.12SDE_SecurityClass ................................................................................... 17-14
17.7.13Attribute Definitions ................................................................................. 17-15
17.7.14SDE_Index{#} .......................................................................................... 17-16
17.7.15Example of a Layer Definition ................................................................. 17-16
17.8 Feature Representation ......................................................................................... 17-17
17.9 SDE Control File Examples .................................................................................. 17-18
17.9.1 Example 1: SDE <-> MapInfo .................................................................. 17-18
17.9.2 Example 2: SDE<->SDE .......................................................................... 17-21
(xi) FME Reference Manual Version 2.0
Table of Contents Safe Software Inc.
18 GIF IMAGE WRITER
18.1 Overview ................................................................................................................. 18-1
18.2 Writer Overview ..................................................................................................... 18-2
18.3 Writer Keywords .................................................................................................... 18-2
18.3.1 DATASET .................................................................................................. 18-3
18.3.2 DEF ...................................................................................................... 18-4
18.3.3 WIDTH ...................................................................................................... 18-4
18.3.4 HEIGHT ...................................................................................................... 18-4
18.3.5 GROUND_RANGE .................................................................................... 18-5
18.3.6 SQUARE_PIXELS ..................................................................................... 18-5
18.3.7 BACKGROUND_COLOR ......................................................................... 18-5
18.3.8 BACKGROUND_PATTERN .................................................................... 18-5
18.3.9 INTERLACE .............................................................................................. 18-6
18.3.10TRANSPARENT_COLOR ........................................................................ 18-6
18.4 Feature Representation ........................................................................................... 18-6
18.4.1 Polygons ...................................................................................................... 18-6
18.4.2 Lines ...................................................................................................... 18-7
18.4.3 Points ...................................................................................................... 18-8
18.4.4 Text ...................................................................................................... 18-9
18.5 Example ................................................................................................................ 18-10
19 MAPINFO DATA INTERCHANGE FORMAT READER/WRITER
19.1 Overview ................................................................................................................. 19-1
19.2 Reader Overview .................................................................................................... 19-3
19.2.1 Reader Keywords ........................................................................................ 19-3
19.2.2 DATASET .................................................................................................. 19-3
19.2.3 DEF ...................................................................................................... 19-3
19.2.4 IDs ...................................................................................................... 19-5
19.3 Writer Overview ..................................................................................................... 19-5
19.3.1 Writer Keywords ......................................................................................... 19-5
19.4 Feature Representation ........................................................................................... 19-5
19.4.1 Points ...................................................................................................... 19-6
19.4.2 Font Points .................................................................................................. 19-7
19.4.3 Custom Points ............................................................................................. 19-7
19.4.4 Polylines ...................................................................................................... 19-8
19.4.5 Regions ...................................................................................................... 19-9
19.4.6 Text .................................................................................................... 19-10
19.4.7 Ellipse .................................................................................................... 19-11
19.4.8 Arc .................................................................................................... 19-12
19.4.9 Rectangle .................................................................................................. 19-14
19.4.10Rounded Rectangle ................................................................................... 19-14
19.5 Example of an SAIF to MIF Mapping File .......................................................... 19-14
FME Reference Manual Version 2.0 (xii)
Safe Software Inc. Table of Contents
20 MAPINFO NATIVE FORMAT READER/WRITER
20.1 Overview ................................................................................................................. 20-1
20.2 Reader Overview .................................................................................................... 20-3
20.2.1 Reader Keywords ........................................................................................ 20-3
20.2.2 DATASET .................................................................................................. 20-4
20.2.3 DEF ...................................................................................................... 20-4
20.2.4 IDs ...................................................................................................... 20-5
20.3 Writer Overview ..................................................................................................... 20-6
20.3.1 Writer Keywords ......................................................................................... 20-6
20.4 Feature Representation ........................................................................................... 20-6
20.4.1 Points ...................................................................................................... 20-6
20.4.2 Font Points .................................................................................................. 20-7
20.4.3 Custom Points ............................................................................................. 20-8
20.4.4 Polylines ...................................................................................................... 20-9
20.4.5 Regions .................................................................................................... 20-10
20.4.6 Text .................................................................................................... 20-11
20.4.7 Ellipse .................................................................................................... 20-13
20.4.8 Arc .................................................................................................... 20-14
20.4.9 Rectangle .................................................................................................. 20-15
20.4.10Rounded Rectangle ................................................................................... 20-15
20.5 Example of an SAIF to MAPINFO Mapping File ................................................ 20-16
21 MULTI-READER
21.1 Overview ................................................................................................................. 21-1
21.2 Keywords ................................................................................................................ 21-2
21.3 Feature Representation ........................................................................................... 21-2
21.4 Example .................................................................................................................. 21-3
22 PHOCUS PHODAT READER
22.1 Overview ................................................................................................................. 22-1
22.2 Reader Overview .................................................................................................... 22-2
22.2.1 Reader Keywords ........................................................................................ 22-2
22.2.2 DATASET .................................................................................................. 22-2
22.3 Feature Representation ........................................................................................... 22-2
22.4 PHOCUS Attributes ................................................................................................ 22-3
22.4.1 Points ...................................................................................................... 22-4
22.4.2 Lines ...................................................................................................... 22-5
22.4.3 Areas ...................................................................................................... 22-5
22.4.4 Text ...................................................................................................... 22-5
22.5 Example .................................................................................................................. 22-6
(xiii) FME Reference Manual Version 2.0
Table of Contents Safe Software Inc.
23 RELATIONAL TABLE READER/WRITER
23.1 Overview ................................................................................................................. 23-1
23.2 Reader Overview .................................................................................................... 23-2
23.2.1 Reader Keywords ........................................................................................ 23-2
23.2.2 DATASET .................................................................................................. 23-3
23.2.3 DEF ...................................................................................................... 23-3
23.2.3.1 ASCII Field Types ....................................................................... 23-4
23.2.3.2 ASCII Special Fields ................................................................... 23-5
23.2.3.3 CAT Field Types ......................................................................... 23-5
23.2.3.4 CAT Special Fields ...................................................................... 23-6
23.2.3.5 CSV/DBF Field Types ................................................................. 23-6
23.2.3.6 CSV Special Fields ...................................................................... 23-7
23.3 Writer Overview ..................................................................................................... 23-8
23.3.1 Writer Keywords ......................................................................................... 23-8
23.4 Feature Representation ........................................................................................... 23-8
23.5 Example .................................................................................................................. 23-8
24 SPATIAL ARCHIVE AND INTERCHANGE FORMAT (SAIF)
READER/WRITER
24.1 Overview ................................................................................................................. 24-1
24.1.1 SAIF Directory ........................................................................................... 24-2
24.1.2 SAIF Schema .............................................................................................. 24-3
24.1.3 SAIF Object Definitions ............................................................................. 24-3
24.2 Reader Overview .................................................................................................... 24-4
24.2.1 Reader Keywords ........................................................................................ 24-4
24.2.2 DATASET .................................................................................................. 24-4
24.2.3 IDs ...................................................................................................... 24-4
24.3 Writer Overview ..................................................................................................... 24-5
24.3.1 Writer Keywords ......................................................................................... 24-5
24.3.2 DATASET .................................................................................................. 24-6
24.3.3 DEF ...................................................................................................... 24-6
24.3.4 CSN ...................................................................................................... 24-9
24.3.5 XCOORD_TYPE ........................................................................................ 24-9
24.3.6 YCOORD_TYPE ...................................................................................... 24-10
24.3.7 ZCOORD_TYPE ...................................................................................... 24-10
24.4 Feature Representation ......................................................................................... 24-10
24.4.1 Geometric Entity Form ............................................................................. 24-10
24.4.2 Text Entity Form ....................................................................................... 24-11
24.5 Example ................................................................................................................ 24-11
FME Reference Manual Version 2.0 (xiv)
Safe Software Inc. Table of Contents
25 VECTOR PRODUCT FORMAT (VPF) READER
25.1 Reader Overview .................................................................................................... 25-1
25.1.1 Reader Keywords ........................................................................................ 25-1
25.1.2 DATASET .................................................................................................. 25-2
25.1.3 DEF ...................................................................................................... 25-2
25.1.4 IDs ...................................................................................................... 25-4
25.1.5 Feature Representation ............................................................................... 25-5
25.2 Special Attribute Handling ..................................................................................... 25-6
25.2.1 Coordinate Attributes .................................................................................. 25-7
25.3 Value Descriptor Tables ......................................................................................... 25-8
25.3.1 Table Relations ........................................................................................... 25-8
25.3.2 Text Primitive Attributes .......................................................................... 25-10
A FME FUNCTION REFERENCE
A.1 @Abort ................................................................................................................... A-1
A.2 @AddVertices ......................................................................................................... A-3
A.3 @Affine ................................................................................................................... A-5
A.4 @Arc ................................................................................................................... A-7
A.5 @Area ................................................................................................................. A-10
A.6 @Bounds ............................................................................................................... A-11
A.7 @Circularity .......................................................................................................... A-13
A.8 @Close ................................................................................................................. A-14
A.9 @Concatenate ........................................................................................................ A-16
A.10 @ConvertBase ....................................................................................................... A-17
A.11 @ConvertToArc .................................................................................................... A-19
A.12 @ConvertToLine ................................................................................................... A-22
A.13 @ConvertToPoint .................................................................................................. A-24
A.14 @Coordinate .......................................................................................................... A-25
A.15 @CoordSys ............................................................................................................ A-27
A.16 @Count ................................................................................................................. A-28
A.17 @Dimension .......................................................................................................... A-30
A.18 @Evaluate .............................................................................................................. A-31
A.19 @FeatureType ....................................................................................................... A-36
A.20 @Force2D .............................................................................................................. A-38
A.21 @Generalize .......................................................................................................... A-39
A.22 @GeneratePoint ..................................................................................................... A-41
A.23 @GOID ................................................................................................................. A-42
A.24 @KeepAttributes ................................................................................................... A-47
A.25 @Length ................................................................................................................ A-49
A.26 @Log ................................................................................................................. A-50
A.27 @Lookup ............................................................................................................... A-52
A.28 @NumCoords ........................................................................................................ A-55
A.29 @NumElements ..................................................................................................... A-56
FME Reference Manual Version 2.0 (xv)
Safe Software Inc. Table of Contents
A.30 @NumHoles .......................................................................................................... A-58
A.31 @Offset ................................................................................................................. A-59
A.32 @Orient ................................................................................................................. A-60
A.33 @Relate ................................................................................................................. A-62
A.34 @Reproject ............................................................................................................ A-80
A.35 @Rotate2D ............................................................................................................ A-82
A.36 @RoundOffCoords ................................................................................................ A-83
A.37 @SAIFAngle ......................................................................................................... A-85
A.38 @Scale ................................................................................................................. A-87
A.39 @Split ................................................................................................................. A-88
A.40 @SupplyAttributes ................................................................................................ A-92
A.41 @Timestamp .......................................................................................................... A-94
A.42 @XValue ............................................................................................................... A-96
A.43 @YValue ............................................................................................................. A-100
A.44 @ZValue .............................................................................................................. A-101
B FACTORY REFERENCE
B.1 AggregateFactory .....................................................................................................B-1
B.2 ArcFactory ................................................................................................................B-4
B.3 ChoppingFactory ......................................................................................................B-6
B.4 ClippingFactory ........................................................................................................B-9
B.5 CloseFactory ...........................................................................................................B-11
B.6 ConnectionFactory ..................................................................................................B-14
B.7 DeaggregateFactory ................................................................................................B-17
B.8 DonutFactory ..........................................................................................................B-20
B.9 DonutHoleFactory ..................................................................................................B-23
B.10 ElementFactory .......................................................................................................B-25
B.11 ListFactory ..............................................................................................................B-28
B.12 MatchingFactory .....................................................................................................B-31
B.13 PIPComponentsFactory ..........................................................................................B-35
B.14 PolygonFactory .......................................................................................................B-37
B.15 PolygonDissolveFactory .........................................................................................B-39
B.16 ReferenceFactory ....................................................................................................B-41
B.17 SamplingFactory .....................................................................................................B-46
B.18 SDEQueryFactory ...................................................................................................B-47
B.19 SortFactory .............................................................................................................B-55
B.20 TeeFactory ..............................................................................................................B-57
B.21 TestFactory .............................................................................................................B-59
C ACRONYMS
(xvi) FME Reference Manual Version 2.0
Table of Contents Safe Software Inc.
(xvii) FME Reference Manual Version 2.0
About This Manual
In an environment of heterogeneous and incompatible geographic
information systems, the key to timely and cost effective data exchange is
flexible, powerful, and easily configured spatial data translation. This
document describes the Feature Manipulation Engine (FME), a semantic
data translator that processes spatial data independent of source and
destination formats. Using the FME, data is transferred between different
spatial data systems, or manipulated and transformed for later processing by
the source system.
This document describes the data processing and translation capabilities of
the FME.
Intended Audience
This manual is targeted at the technical audience involved in configuring the
FME for customized translation. Data managers, software professionals, and
advanced Geographical Information Systems (GIS) operators wishing to
maximize the value of their data will be interested in the capabilities of the
engine.
There are two types of FME users:
those who prepare FME configurations, called mapping files, tuning them
for the data model of their organization
About This Manual Safe Software Inc.
(xviii) FME Reference Manual Version 2.0
those who use the FME mapping files that come with the system, supplying a few
parameters like a file name or directory to perform translations.
This manual is primarily directed at the first group of users, while the FME Users
Manual applies to the second.
Using This Manual
This manual contains complete reference information on all of the FMEs processing
facilities. The first nine sections provide an introduction to the operation of the FME,
and the syntax of its configuration language. These sections provide a solid
foundation for understanding how to configure the FME, and are of interest to all
FME users. The remaining sections provide detailed information on FMEs support
for a variety of formats and systems. Most users will only refer to those sections
describing the formats they are using, and may safely ignore the rest. Two of the
appendices provide in-depth descriptions of each of the processing facilities of the
FME. They are independent of data format, and will be referenced by anyone creating
custom FME configurations employing these facilities.
Though it contains many examples, this manual is not intended as a replacement for
the FME Tutorial. Alternatively, this manual is of the best use to those users who
have either completed the FME Tutorial or the FME training course.
About Each Section
This document is organized as follows:
Section 1
Introduction
This section describes the data processing and translation capabilities of the
FME.
Section 2
FME Architecture
The FME moves features from external data sources to memory, processes
them, and outputs them according to rules expressed in the mapping file.
Section 3
FME Functions
A unique and powerful capability of the FME is the application of functions
to feature geometry and attributes during the translation process.
Section 4
FME Feature
Factories
Feature factories provide a mechanism for the FME to operate on groups of
features.
(xix) FME Reference Manual Version 2.0
Safe Software Inc. About This Manual
Section 5
FME Translation
Process
The primary task of the FME is to translate features by selectively setting,
transferring, and modifying feature attributes and geometry.
Section 6
FME Mapping File
Syntax
This section describes the syntax and facilities of FME mapping files.
Section 7
FME Configuration
This section explains the FMEs core configuration from the specification
of the reader and writer modules a session uses, to the FME mapping file
debugging facilities.
Section 8
Coordinate System
Support
The FME tracks the coordinate system of each feature, automatically
performing coordinate system conversions when necessary.
Section 9
FME Interfaces
This section describes the command line and configurable user interfaces
(FMEGUI) shipped with the FME. Mapping files may be invoked from a
configurable graphical user interface, which prompts end users for missing
mapping file settings.
Section 10
AutoCAD DWG/
DXF Reader/Writer
This section explains the facilities the FME provides for reading and writing
AutoCAD DWG and DXF files.
Section 11
B.C. Ministry of
Environment and
Parks (MOEP)
Reader/Writer
This section explains the facilities the FME provides for reading and writing
B.C. Ministry of Environment and Parks (MOEP) files.
Section 12
Design File Reader/
Writer
This section explains the facilities the FME provides for reading and writing
Intergraph Design files.
Section 13
Digital Line Graph
Reader
This section explains the facilities the FME provides for importing Level 3
Digital Line Graph (DLG) data and exporting it to any of the FME output
formats.
Section 14
ESRI ArcInfo
Export Format (E00)
Reader
This section explains the capability of the FME to read uncompressed
ArcInfo Export (E00) files.
About This Manual Safe Software Inc.
(xx) FME Reference Manual Version 2.0
Section 15
ESRI ArcInfo
Generate File
Reader/Writer
This section explains the facilities the FME provides for reading and writing
ArcInfo Generate files.
Section 16
ESRI Shape File
Reader/Writer
This section explains the facilities the FME provides for reading and writing
ESRI Shape files.
Section 17
ESRI SDE Reader/
Writer
This section describes the FME facilities for importing and exporting data to
and from ESRIs Spatial Database Engine (SDE).
Section 18
GIF Image Writer
This section explains the facilities the FME provides for creating Graphics
Interchange Format (GIF) image files from input vector data.
Section 19
MapInfo Data
Interchange Format
Reader/Writer
This section explains the facilities the FME provides for reading and writing
MapInfo Data Interchange Format (MIF/MID) files.
Section 20
MapInfo Native
Format Reader/
Writer
This section explains the facilities the FME provides for reading and writing
native MapInfo Data (TAB) files.
Section 21
Multi-Reader
This section explains the Multi-Reader, which allows several different input
datasets to be read and combined during a single translation.
Section 22
Phocus Phodat
Reader
This section explains the facilities the FME provides to read Phocus Phodat
interchange format files.
Section 23
Relational Table
Reader/Writer
This section explains the facilities the FME provides for utilizing relational
databases as the primary source of or destination for information during
translation. It describes the facilities provided for files such as DBase Files
(DBFs), Comma Separated Values (CSVs), free-form ASCII, and Column
Aligned Text (CAT).
(xxi) FME Reference Manual Version 2.0
Safe Software Inc. About This Manual
Conventions Used in this Guide
The following special fonts and conventions are used throughout this manual to assist
you.
Section 24
Spatial Archive and
Interchange Format
(SAIF) Reader/
Writer
This section explains the facilities the FME provides for reading and writing
Spatial Archive and Interchange Format files.
Section 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 which follow the VPF
specification (MIL-STD-2407).
Appendix A
FME Function
Reference
This section contains a description of all the FME functions which are
currently available.
Appendix B
Factory Reference
This section contains a description of all the factories available within the
FME.
Appendix C
Acronyms
All acronyms used in this manual are noted here.
Feature Snapshot This font is used when the in-memory contents of an FME
feature are shown.
Monospaced type This font is used when mapping file contents are shown.
<atom name> Angle brackets enclose names which will be replaced with
a single value in an actual mapping file.
[optional] Optional items are enclosed in square brackets.
(choice1|choice2) Choices are enclosed by parentheses and separated by a
vertical bar.
<item>* An asterisk following any of the above indicates that zero
or more repetitions of the item are allowed.
<item>+ An plus sign following any of the above indicates that one
or more repetitions of the item are allowed.
Italics References to other documents, or to other sections or
paragraphs within this document, are shown in italicized
text.
For example, ...refer to Section 2, FME Architecture.
About This Manual Safe Software Inc.
(xxii) FME Reference Manual Version 2.0
This manual also uses an Icon Key, assigning the following icons with these specific
meanings:
For More Information
For more information about FME or for supporting information, refer to the
following documents:
Feature Manipulation Engine User Documentation Series:
Part I FME User Manual
Part II FME Tutorial
Part III FME Solutions Guide
Map ProjectionsA Working Manual. Written by J.P. Snyder, US Geological
Survey Professional Paper 1395, published in 1987
MapInfo Professional Reference Manual, 2nd Edition, January 1996
Spatial Archive and Interchange Format (SAIF): Formal Specification Release 3.2,
January 1995
SAIF Toolkit API Programmers Reference Manual, Release 1.1, BC Ministry of
Environment Lands and Parks, November, 1994
SAIF/ZIP File Format Description
SDE Reference Manual
SDE Users Manual
Spatial Archive and Interchange Format: Formal Specification Release 3.2
Future Enhancement
Feature Snapshot
Important Point
1-1 FME Reference Manual Version 2.0
1
1 INTRODUCTION
1.1 Overview
The Feature Manipulation Engine (FME) provides a translation hub through
which sophisticated spatial translation operations are performed.
The FME is much more than a simple data translator. In addition to format
conversion, the FME is capable of performing sophisticated processing
during the translation process. It may even be used as a configurable spatial
and attribute processing utility by reading from and writing to the same data
format. In many respects, the FME is a format neutral batch GIS.
Historically, the task of moving data from one format to another has been
difficult. As a result, users with large data stores have been locked into a
single vendors format and have been restricted to using one vendors analysis
and decision support tools. The FME enables users to evaluate and use tools
independent of their data format. In addition, it is commonly reported that
data preparation consumes 80% or more of the time for most GIS projects.
Using its sophisticated topological and attribute processing subsystems, the
FME is able to resolve the geometric and attribute mapping problems between
different systems. As a result, the FME removes the format barriers that have
hindered GIS users for so long, allowing them to spend their time on data
analysis rather than on data preparation.
INTRODUCTION Safe Software Inc.
1-2 FME Reference Manual Version 2.0
Figure 1-1 Feature Manipulation Engine provides a universal spatial data translation
solution.
1.2 Data Source Merging
Through the use of the FMEs Multi-Reader, data from several different sources
possibly of varied formatscan be read, processed, and output to a single dataset.
This can be used to:
Combine several 1:50,000 maps together, generalize them, and create a single
1:250,000 map.
Produce derived products for an area by combining input data from diverse
sources.
AutoCAD
DWG/DXF
ASCII
CSV, CAT
ESRI
SHAPE
ESRI
SDE
DBMS
(ODBC,
ORACLE
DBASE)
MAPINFO
(MIF, TAB)
RASTER
VPF/
DLG
ESRI
ARC/
GENERATE
BC MOEP,
SAIF
IGDS
DESIGN
ESRI
E00
KF 85
PHOCUS
PHODAT
1-3 FME Reference Manual Version 2.0
Safe Software Inc. INTRODUCTION
Bulk load data into seamless spatial database products.
TIP: See Section 21, Multi-Reader for more details.
1.3 Topology Operations
The FME is capable of performing sophisticated topological operations during data
translation. These topology operations can be used in the following ways:
Form polygons, possibly with holes, from input linear geometry.
Merge points with the polygon or donut polygon containing them. The attributes
associated with the point are then associated with the enclosing area feature.
Remove duplicate line segments from an input data set. This is useful when the
input data set is a collection of polygons which share common boundaries and
the desired output is the set of arcs which define the polygon boundaries.
Connect line segments together. This is used to reduce the number of features by
combining their geometry. Line breaks occur only when the attribute values of
the line pieces change or when a topologically significant node is encountered.
Generate interior points for polygons. This is used when the destination format
requires an inside point for the polygonal data.
TIP: See Appendix A, @Generate Point and Appendix B, Polygon Factory, Arc Factory, Donut Factory
descriptions for more details.
1.4 Geometric Operations
In addition to the topological operations, the FME also provides a number of
geometric operations that can be used to achieve the following results:
Generalize features by removing points from lines, converting small polygons
and short lines to points, and converting small polygons to lines. Two different
line thinning algorithms are available, and each of the generalization operations
is fully configurable on a feature by feature basis.
Calculate feature area and length. These calculated values can then be stored in
the destination format or used to control other aspects of the translation process.
TIP: See Appendix A, @ConvertToLine, @ConvertToPoint, @Generalize, @Length and @Area for more
details.
INTRODUCTION Safe Software Inc.
1-4 FME Reference Manual Version 2.0
1.5 Attribute Operations
While the FME is primarily a spatial data translation system, it also provides an
extensive suite of attribute manipulation operations. In fact the FME does not require
that the data it handles have any spatial component, and can be used to translate
between relational or object-relational attribute databases. The attribute operations
enable the FME to:
convert data between a relational model and an object-oriented model (this
capability eases migration to systems with an object-oriented data model)
read or write feature attributes from/to external tables during translation (several
different types of attribute files are supported)
join multiple relational tables together to extract or output data related to a single
feature
1.6 Coordinate System Conversion
All FME features know the coordinate system of their geometry. When a coordinate
system change is requested, the FME completely transforms the feature, possibly
changing its type of geometry as it moves it to the new coordinate system.
The FME automatically extracts coordinate system information from those formats
which store this information. If a source format does not contain spatial referencing
information, then the user may specify it.
In any case, the coordinate system of the output format may also be specified. If the
output coordinate system is different than the input one, then the FME will
automatically convert the feature data. To ensure that the reprojection is accurate, the
FME automatically vectorizes arcs, ellipses, rectangles, and rounded rectangle
objects before doing the coordinate system change. In addition, text rotation angles
and sizes are adjusted during the change. The output system or format stores the
coordinate system of the data if it has the facilities to do this.
TIP: See Section 8, Coordinate System Support for more details.
1-5 FME Reference Manual Version 2.0
Safe Software Inc. INTRODUCTION
1.7 Summary
The FME provides a fully configurable geo-object-relational data processing
environment with many capabilities. The FMEs processing abilities provide the
building blocks for solving difficult processing tasks quickly and easily. The result is
that the FME can solve both simple and complex translation and processing
problems.
In the past, new software was written for each translation situation. Over time, this
introduced a maintenance problem, as it resulted in a large number of incompatible
and inflexible translator programs. The FME solves this problem by allowing the
same translator program to be used to solve a variety of translation problems.
INTRODUCTION Safe Software Inc.
1-6 FME Reference Manual Version 2.0
2-1 FME Reference Manual Version 2.0
2
2 FME ARCHITECTURE
The FME consists of software modules that operate on a collection of
features. The reader modules read features from external sources. The factory
modules in the factory pipeline join features together or split them apart in a
variety of ways. The transformation module converts the feature from one
formats representation into anothers. Writer modules output the features in
a supported format. All processing aspects performed by the FME are
specified through a semantic mapping file.
All modules in the FME output statistics, progress information, warnings, and
errors to a translation log file.
F
e
a
t
u
r
e
s F
e
a
t
u
r
e
s
Transformation
Module
Reader Module Writer Module
Control File
Source Feature
Data
Destination
Feature Data
F
e
a
t
u
r
e
s
Feature Manipulation Engine
Architecture
F
e
a
t
u
r
e
s
External
Attribute
Databases
A
ttr
ib
u
te
D
a
ta
Feature Factory Pipeline
Features
A
t
t
r
ib
u
t
e
D
a
t
a
FME ARCHITECTURE Safe Software Inc.
2-2 FME Reference Manual Version 2.0
2.1 FME Features
To transport features from one format to another, the FME considers features to be
collections of attribute names and values associated with two or three dimensional
geometry (arbitrary dimensions will be supported in a future release). The FME
places no restrictions on the values, or types of attributes. Attribute names consist of
one or more ASCII characters. FME features may contain any of these types of
geometry.
In addition to attributes and geometry, each FME feature has a feature type. Reader
and writer modules interpret the feature type in ways specific to their own formats.
For example, the Interactive Graphics Design System (IGDS) reader and writer use
the feature type to store the IGDS level of the feature, while the Spatial Archive and
Interchange Format (SAIF) reader and writer use it to store the SAIF class of the
object. Feature types are also used in FME mapping files as the foundation for
defining the transformation specifications. Transformation specifications are
described in Section 5.1.
Geometry
Type
Example Description
Point A single x, y, and possibly z set of values representing
a single point on the earths surface.
Line A line of two or more x, y, and optionally z values.
Spaghetti lines (which cross themselves) are allowed,
but the FME always removes any adjacent duplicated
points it finds in lines as they are read.
Polygon A closed ring of 2 or 3 dimensional vertices which
represent an area. The first and last points are identical.
The polygon may follow either the right hand or left
hand rule.
Donut Polygon A set of closed rings, or polygons. The first ring defines
the outer boundary of the area. The remaining rings
must be completely inside the outer boundary and
define the holes in the area. No orientation rule is
enforced.
Aggregate A collection of distinct geometric entities, treated as a
single unit. May or may not be homogenous.
.
.
.
.
.
. .
.
. .
.
. .
.
. .
.
.
.
.
.
. .
.
. .
.
.
.
.
2-3 FME Reference Manual Version 2.0
Safe Software Inc. FME ARCHITECTURE
Feature attributes are usually a primitive type (integers, floats, characters). However,
collections of attributes may also be stored in a single FME feature using an attribute
list. Attribute lists behave like primitive attributes, except that they contain an index
enclosed in braces to identify an element of the list. Attribute list elements may
contain primitives or other attribute lists. Attribute lists may be used by feature
factories, feature functions, and the reader and writer modules.
Throughout this manual, memory snapshots of FME features are shown to illustrate
FME processing concepts. The following snapshot shows a portion of a multi-line
text feature produced by the IGDS reader. This feature contains an attribute list
named igds_text_elements which holds both of the text elements contained in
the IGDS feature.
2.2 Reader Modules
Reader modules are responsible for retrieving data from a data source. The data
source may be either a static file or another software system. For example, the IGDS
reader module extracts features from Intergraph Design Files, while the Spatial
Database Engine (SDE) reader module connects to an SDE server to retrieve its
features.
The Multi-Reader (see Section 21) allows many reader modules to be used in a single
FME session thereby enabling data from several different data stores to be processed.
The FME has reader modules for the following formats:
ASCII
AutoDesk DXF/DWG
BC Ministry of Environment Binary (MOEP)
Column Aligned Text (CAT)
Comma Separated Value (CSV)
dBASE III (DBF)
Feature Type: 35
Attribute Name 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)
FME ARCHITECTURE Safe Software Inc.
2-4 FME Reference Manual Version 2.0
Digital Line Graph (DLG) standard and optional
ESRI ArcInfo Export (E00)
ESRI ArcInfo Generate
ESRI Shape File
ESRI Spatial Database Engine (SDE)
Intergraph IGDS Design Files
MapInfo MIF
MapInfo TAB
Spatial Archive and Interchange Format (SAIF)
Swedish KF85
Vector Product Format (VPF)
The CAT, CSV, DBF, and ASCII reading modules can also be used to retrieve feature
attributes from sources external to the primary spatial data storage. See the @Relate
Function in Appendix A.
The parameters used to control each of these modules are discussed in the specific
data format sections starting with Section 10 of this manual.
2.3 Functions
FME functions may be called at any time to set attribute values or change a features
geometry. For example, the @Generalize function can be called on a feature to
thin its coordinates, and the @Log() function may be called to output the entire
feature to the translation session log file for later inspection. The current library of
predefined functions is described in Appendix A of this manual.
TIP: Future releases of the FME will enable users to write their own feature functions and have them
automatically called by the transformation module.
The @Relate() function is particularly interesting because it allows attribute data
to be extracted from or added to auxiliary attribute databases. Presently, the FME
supports only file-based attribute databases in the dBASE, comma separated value
(CSV), column aligned text (CAT), or ASCII formats. In the near future, support for
live attribute database links to Oracle and ODBC-compliant databases will be
completed.
Section 3 provides an overview of FME functions, and Appendix A describes each of
the available functions.
TIP: Functions operate on only one feature at a time.
2-5 FME Reference Manual Version 2.0
Safe Software Inc. FME ARCHITECTURE
2.4 Feature Factory Pipeline
Just as real factories take in raw materials, process them, and turn out products, the
FME factory modules (called feature factories) accept as input raw features,
perform processing on them as a group, and output processed features. Feature
factories are able to combine input features together into one output feature, or split
them apart into numerous output features. For example, the polygon formation
feature factory combines line segments which have identical attribution, and forms
them into closed polygons.
Section 4 provides an overview of FME factories, and Appendix B describes the
operations of each of the available factories.
2.5 Transformation Module
The transformation module is responsible for transforming features from a source
format to a destination format. The first step in the transformation process is the
matching of a feature with the transformation specification which specifies how the
feature is to be transformed. Matching is done based on feature type and attribute
values. When a match is found, the feature is transformed into its destination form by
adding, dropping, and modifying its attributes. For example, when translating
features from an Intergraph Design File to ESRIs SDE, linear features from level 12
with color 8 and style 0 could be correlated to features on the SDE layer containing
roads, with attribute NUMLANES set to 2 and attribute PAVED set to false. The
operation of the transformation module is discussed in detail in Section 5 of this
manual.
TIP: Features that do not match any transformation specification are dropped from the translation, allowing the
FME to act as a data filter.
2.6 Writer Modules
The writer modules are responsible for exporting features from the FME to some
destination which may be either a static file or another software system. For example,
the IGDS writer module exports features to Intergraph Design Files, while the SDE
writer module connects to an SDE server to export its features.
The FME has writer modules for the following formats:
ASCII
AutoDesk DXF/DWG
BC Ministry of Environment and Parks (MOEP) Binary
Column Aligned Text (CAT)
Comma Separated Value (CSV)
FME ARCHITECTURE Safe Software Inc.
2-6 FME Reference Manual Version 2.0
dBASE III (DBF)
ESRI ArcInfo Generate
ESRI Shape File
ESRI Spatial Database Engine (SDE)
GIF Imagery
Intergraph IGDS Design Files
MapInfo MIF
Spatial Archive and Interchange Format (SAIF)
TIP: The CAT, CSV, DBF, and ASCII writing modules can also be used to output feature attributes to sources
external to the primary spatial data storage. See the @Relate function (Appendix A).
The parameters used to control each of these modules are discussed in the specific
data format sections starting with Section 10.
2.7 Mapping File
An FME translation is controlled by a series of rules specifying the rules and
transformations of a data translation. The mapping file drives the operation of all
FME modules during a data translation.
The typical format of the FME mapping file is illustrated in Figure 2-1.
Though the order of the major sections of a mapping file is not significant, typically
the configuration of readers and writers is placed at the top. Next the factory
definitions, if any, are presented. Finally, the definitions of the features in the input
and output systems are given with the rules for transforming them from one system
to the other.
See Section 6, FME Mapping File Syntax for a complete discussion of their syntax.
2-7 FME Reference Manual Version 2.0
Safe Software Inc. FME ARCHITECTURE
Figure 2-1 FME Mapping File Structure
FME Control File Structure
Reader And Writer
Configuration
Feature Factory Pipeline Configuration :
Feature Factory 1
Feature Factory 2
Feature Factory N
Transformation Module Configuration:
Feature Definition Statements
Feature Correlation Rules
FME ARCHITECTURE Safe Software Inc.
2-8 FME Reference Manual Version 2.0
3-1 FME Reference Manual Version 2.0
3
3 FME FUNCTIONS
Supplementing the transformation capabilities of the FME, functions provide
a flexible means to apply specific algorithmic operations to features as they
are being transformed.
TIP: Transformation functions differ from feature factories in that transformation functions work on
exactly one feature at a time, whereas feature factories may work on many features at once.
FME functions are named with an at sign (@) as their first character.
Arguments to the functions are enclosed in parentheses. The format of a
function is as follows:
@funcName([<parameter>[,<parameter>]])
There are two kinds of transformation functions. Attribute functions are used
to compute the value for an attribute, whereas feature functions operate on the
complete feature. The following table contrasts the two kinds of
transformation functions.
TIP: Attribute functions may also be used to provide values to FME mapping file directives. See
Section 6.11, Static Function Evaluation, for details.
Table 3-1 Transformation Function Types
Attribute Function Feature Function
Compute and return a value. Do not return a value.
Unable to directly modify features. Can modify both feature attributes and
geometry.
No side effects to the feature. Leave lasting side effects on the feature.
FME FUNCTIONS Safe Software Inc.
3-2 FME Reference Manual Version 2.0
Because the same mapping file can be used to translate in either direction between
two systems or formats, each function implements its inverse operation, if it makes
sense to do so. Functions that cannot be reversed implement a null operation as their
inverse, or perform the same operation when run in reverse as in the forward
direction.
Transformation functions on the destination line of a transformation specification
are run in the forward direction.
Transformation functions on the source line of a transformation specification are run
in the inverse direction.
Figure 3-1 Transformation Process
3.1 Function Parameters
Five kinds of parameters may be passed to transformation functions.
Do not affect the feature, the environment,
or external data stores.
Can modify feature attributes and
geometry, can read or write to external data
stores.
Must be placed to the right of a feature
attribute name on a transformation
specification line.
Placed after all attribute name/value pairs
on a transformation specification line.
Attribute Function Feature Function
Source
Feature
Transformation
Module
Destination
Feature
T
r
a
n
s
f
o
r
m
a
t
i
o
n
F
u
n
c
t
i
o
n

(
I
n
v
e
r
s
e
)
T
r
a
n
s
f
o
r
m
a
t
i
o
n
F
u
n
c
t
i
o
n
Transfer
Variable
3-3 FME Reference Manual Version 2.0
Safe Software Inc. FME FUNCTIONS
3.1.1 Constants
Constants are passed to the function untouched. If a constant contains a space, the
constant must be enclosed in quotation marks. All parameters are considered to be
constants unless they are transfer variables, attribute values, or function calls.
In this example, all parameters are constant, and so each time the function is invoked
on a feature it will be passed the same parameters:
@Generalize(Deveau,20,4,100)
3.1.2 Transfer Variables
Transfer variables are used to carry values across from a source transformation
specification line to a destination transformation specification line. All transfer
variables have a % as their first character. When a transfer variable is encountered in
a function parameter list, its value is passed to the function. If the function is running
in the inverse direction, it will set the first transfer variable in its parameter list to the
result of its computation. See Forward Function Example and Inverse Function
Example discussions in Section 3.3 for further information.
3.1.3 Attribute Values
There are times when the value of an existing attribute should be used as a function
argument. In such cases, the value-of operator (an ampersand&) is used to tell the
FME to substitute the value of the attribute as the argument to the function. If the
function is run in the inverse direction and there are no transfer variables in its
argument list, it will set the first attribute to its result.
The example below counts all of the different values encountered for the
numberOfLanes attribute. The totals are logged in the log file. This can be used to
produce a histogram of a particular attributes range of values.
@Count(&numberOfLanes)
3.1.4 Attribute Functions
Any attribute function may be used as the value for a parameter, and this nesting may
be arbitrarily deep. At run time, the FME invokes the deepest nested function, uses
its result as the argument for the next function, and so on. Only functions which will
return a value should be nested. All nested functions must be enclosed in quotation
marks.
The example below produces a histogram of the feature types encountered:
@Count(@FeatureType())
FME FUNCTIONS Safe Software Inc.
3-4 FME Reference Manual Version 2.0
3.1.5 Composites
Function parameters may be composed of the previous four types by enclosing them
in a single set of quotation marks. All substitutions are made before the resulting
string is passed to the function.
The example below returns three times the current @Count value, and can be used
as a counter which goes up by three each time:
@Evaluate(@Count() * 3)
In this example, the string contains a function call. Each time this @Log function is
invoked, the @Count() is replaced in the log message by the value it returns:
@Log(Feature # @Count())
3.2 Forward Function Example
Consider this transformation specification governing a translation of DEM points
between Shape and SAIF:
# -------------------------------------------------
Handle DEM Points
Shape dempoint type %pt elevation %z
SAIF DemPoint pointType %pt @ZValue(%z)
This example illustrates the use of the @ZValue feature function. Because the Shape
file format does not carry a third dimension, the elevation of each point is stored as
an attribute (elevation) in the Shape attribute table. When translating from Shape
to SAIF, a Shape feature is read into the FME as:
The transformation module sets up the %pt and %z transfer variables to hold
spotElevation and 1059.3 respectively. It then sets the destination features
type to DemPoint, sets its pointType attribute to the value of the %pt transfer
variable, which is spotElevation, and sets the destination features coordinates.
Once this is done, the destination feature looks like:
Feature Type: dempoint
Attribute Name Value
type spotElevation
elevation 1059.3
Coordinates: (477553.1, 5360181.4)
3-5 FME Reference Manual Version 2.0
Safe Software Inc. FME FUNCTIONS
Now the @ZValue function is invoked in the forward direction, since the SAIF line
is the destination. This function takes its argumentthe value of the %z transfer
variable (1059.3)and performs its normal function, which is setting the z
coordinate of the feature to the given value. The resulting FME feature, which is
passed to the SAIF writer, looks like:
3.3 Inverse Function Example
Consider the situation when the same transformation specification is used to translate
DEM points from SAIF into Shape. In this case, SAIF is the source line, and when
the feature is read from SAIF, it looks like:
The transformation module sets up the %pt transfer variable to hold the
spotElevation. It then executes the inverse of the @ZValue function, which
sets the %z transfer variable to the result of the function. The inverse of @ZValue
returns the value of the z coordinate of the feature, which is 1059.3 in this case.
The transformation module then sets the destination features type to dempoint,
and sets the type attribute to the value of the %pt transfer variable, which is
spotElevation. It also sets the elevation attribute to the value of the %z
Feature Type: DemPoint
Attribute Name Value
pointType spotElevation
Coordinates: (477553.1, 5360181.4)
Feature Type: DemPoint
Attribute Name Value
pointType spotElevation
Coordinates: (477553.1, 5360181.4, 1059.3)
Feature Type: DemPoint
Attribute Name Value
pointType spotElevation
Coordinates: (477553.1, 5360181.4, 1059.3)
FME FUNCTIONS Safe Software Inc.
3-6 FME Reference Manual Version 2.0
transfer variable, which is 1059.3, and sets the features coordinates. Once this is
done, the feature is passed on to the Shape writer containing:
The Shape writer outputs the feature, ignoring the z coordinate value as it can only
output x and y to a Shape file.
3.4 Function Configuration
Some sophisticated functions require configuration before they can be invoked. To
accommodate this, these functions accept configuration lines in the mapping file.
Such configuration lines always begin with the name of the function, without the @
sign. If a function accepts configuration, its documentation states the format of the
configuration lines.
3.5 User Defined Functions
Presently, new functions cannot be defined in the mapping file, so the user is
restricted to using the predefined functions. In future releases, mapping file definition
of Tool Command Language (TCL) functions may be permitted. As well, for
systems such as Solaris and Microsoft Windows 95/NT that allow dynamic loading
of software libraries (DLLs), an API is planned to enable sites to write their own
processing functions using whatever language they wish, and have the FME invoke
them during transformation.
See Appendix A, FME Function Reference for a listing and discussion of all currently
available FME functions.
Feature Type: dempoint
Attribute Name Value
type spotElevation
elevation 1059.3
Coordinates: (477553.1, 5360181.4, 1059.3)
4-1 FME Reference Manual Version 2.0
4
4 FME FEATURE FACTORIES
Feature factories enable the FME to perform operations on collections of
features. Factories are the second major feature processing facility available
in the FME and supplement the function facility introduced in the previous
section. There are several differences between feature functions and feature
factories:
Feature factories have no inverse. To ensure that a single correlation
table can be used in both directions, feature factory definitions are
associated with a <ReaderKeyword>. If the active
<ReaderKeyword> does not match, then the feature factory definition
is not activated.
All feature and attribute value functions on feature factory definition
lines run in the forward direction.
Feature factories are able to operate on more than one feature at a time.
In addition, they may output more than one feature. Feature functions are
only able to make changes to the single feature they are operating on,
although they may delete it.
Factories enable the FME to perform sophisticated processing tasks. Because
factories may be combined with feature and attribute value functions, and
chained together into a factory pipeline, problems which traditionally
required custom software can be solved by a single FME mapping file.
FME FEATURE FACTORIES Safe Software Inc.
4-2 FME Reference Manual Version 2.0
4.1 Factory Architecture
All feature factories have the same architecture. They each define an input interface,
which is used to control the features entering the factory, invoking feature and
attribute functions on them as they enter. The core of every factory is its feature
processing unit, which operates on the features that have entered the factory. The
processing unit may merge features together, split them apart, delete them, generate
new features based on the input features, and/or alter their geometry and attributes in
order to accomplish its task. The output interface controls how features leaving the
factory appear to the rest of the system. It allows the feature type and attribute values
to be reset, and further feature and attribute functions to be invoked on the feature as
it leaves the factory.
4.1.1 Input Interface
The input interface is used to identify features to be processed by a factory. Each
feature factory has an input interface. The input interface is controlled by one or more
INPUT clauses on a factory definition statement. The feature INPUT clause has a
similar syntax to the source line of a transformation specification.
As with the source line of a transformation specification, the INPUT clauses are used
as a pattern to match against features to identify those which are permitted to enter
the factory. Features that are not accepted by a factory move on to the next factory
downstream in the factory pipeline.
Unlike the source line of a transformation specification, all attribute and feature
functions on a factory INPUT clause are run in the forward direction.
If no input clause is specified for a factory, then all features will enter it.
Feature
Processing
Unit
Input
Interface
Output
Interface
Feature Factory
Input
Features
Output
Features
4-3 FME Reference Manual Version 2.0
Safe Software Inc. FME FEATURE FACTORIES
4.1.2 Feature Processing Unit
The feature processing unit receives features from the factory input interface and
processes the feature. There are two types of factory processing units: grouping
factories and non-grouping factories.
Grouping factories collect features, then process the feature collection once the
input source has been exhausted. Factories which fall into this category include
the PolygonFactory and the ArcFactory.
Non-grouping factories operate on the features as they arrive. These factories
may split a feature into many smaller features, collect statistics on features, or
delete passed-in features. Examples of non-grouping factories include the
SamplingFactory and the PIPComponentsFactory.
4.1.3 Output Interface
The output interface is used to output features from the factory. The output interface
is controlled by one or more OUTPUT clauses on a factory definition statement. The
factory OUTPUT clause has a similar syntax and follows rules similar to a
transformation specification destination line.
As with the destination line of a transformation specification, the purpose of the
OUTPUT clauses are to set the feature type and attribute values of features leaving the
feature factory. Feature functions on factory OUTPUT clauses are executed in the
forward direction.
4.2 Factory Activation Sequence
When the FME is launched, it initializes all of the factories first. The factory
activation sequence occurs in several steps as the mapping file is scanned from top to
bottom:
When a feature factory definition is encountered, the FME determines if it
matches the current <ReaderKeyword>.
If the feature factory definition is for the <ReaderKeyword>, the feature
factory is activated. Otherwise, the factory definition is ignored.
When defining mapping files it is important to remember that features flow from
the first factory down through the last one. It is impossible for a feature to exit
one factory and enter a factory defined earlier in the mapping file.
FME FEATURE FACTORIES Safe Software Inc.
4-4 FME Reference Manual Version 2.0
4.3 Factory Pipeline
Feature factories add a flexible processing model to the FME. The real power of the
feature factories is realized when they are chained together to form a factory pipeline.
A factory pipeline is formed when a feature leaves one factory and is immediately
sent by the FME to another factory. This chaining of factories is referred to as factory
pipelining. An FME factory pipeline is a directed acyclic graph.
Figure 4-1 Factory Pipeline
4.4 Factory Definitions
Feature factory definitions control all aspects of the feature factories. Each factory
definition has the following form:
FACTORY_DEF <ReaderKeyword> <factory name> \
[INPUT [<tag>] FEATURE_TYPE <feature type> \
<attribute name> <attribute value>]* \
[<feature function>]* \
]* \
[<factory specific directives>]* \
[GROUP_BY [<attribute name>]+]* \
[OUTPUT <tag> FEATURE_TYPE <feature type> \
[<attribute name> <attribute value>]* \
[<feature function>]* \
]*
All parts of each factory definition are discussed in subsections 4.4.1 through 4.4.5.
Feature
Factory
Feature
Factory
Feature
Factory
4-5 FME Reference Manual Version 2.0
Safe Software Inc. FME FEATURE FACTORIES
4.4.1 FACTORY_DEF
The FACTORY_DEF clause is always the first clause of a factory specification. It
consists of two parameters: <ReaderKeyword> and <factory name>.
The example FACTORY_DEF clause below specifies that the ArcFactory is to be
activated when the <ReaderKeyword> is IGDS.
FACTORY_DEF IGDS ArcFactory...
4.4.2 INPUT
Factory INPUT clauses acts as a guard, allowing only features which satisfy one of
the input clauses to enter the factory. Features that do not satisfy any of a feature
factorys INPUT clauses skip that factory and are routed to the next factory
downstream in the factory pipeline.
TIP: If a factory has no INPUT clause, it accepts every feature. This is an easy way to create a factory which
processes every feature. Using the @Count() function on the input line of the feature will count the
features input to the factory.
Parameter Content
<ReaderKeyword> The reader module with which this factory is associated.
<factory name> The name of the factory used by this factory definition.
Parameter Content
<tag> The tag is used to categorize input features for the factory.
Some features, such as the ReferenceFactory, require that
features be divided into classifications as they are accepted by
the factory. See the description of the individual factories in
Appendix B for the tags which they support. Most factories do
not support tags in their INPUT clauses as there is no
distinction between types of features which enter the factory.
<feature type> The feature type of input features that match the input clause.
<attribute name> The attribute name being referenced in the input specification.
<attribute value> If the attribute value is a constant, it is used for matching.
Once the feature has successfully been matched, any attribute
values which were attribute functions are evaluated and the
result is assigned to the attribute before the feature gets passed
into the feature processing unit.
<feature function> If the feature is successfully matched, any feature functions
specified are executed in the forward direction before the
feature is passed into the factory.
FME FEATURE FACTORIES Safe Software Inc.
4-6 FME Reference Manual Version 2.0
The following example specifies that all features with a feature type of
ForestCoverPolygon will be accepted by the factory. In addition, the output of
the Area() command is assigned to the features area1 attribute before the feature
is passed into the feature factory.
INPUT FEATURE_TYPE ForestCoverPolygon area1 @Area()
4.4.3 Factory Specific Directives
Many of the factories require that directives which are specific to them be specified.
The form of these directives varies from factory to factory and is described in the
factory reference system for each factory.
For example, the ArcFactory requires a directive of either END_NODED or
VERTEX_NODED be specified, while the SamplingFactory requires a
SAMPLE_RATE directive be specified.
4.4.4 GROUP_BY
This clause identifies how features passed into the factory are partitioned. The clause
specifies the attribute names used to partition the input feature set. One partition is
created for each unique combination of the values of the named attributes. Each of
these partitions is processed independently of every other partition. Features output
from such a factory are supplied values for each <attribute name> specified in
the GROUP_BY clause.
TIP: Clever use of the GROUP_BY clause often reduces the number of feature factories that need to be
specified. However, not every factory supports a GROUP_BY clause.
4.4.5 OUTPUT
OUTPUT clauses are used to assign attribute values to features as they emerge from a
factory. OUTPUT clauses may also apply feature and attribute value functions to the
features as they leave the factory.
Parameter Content
<attribute name> The name of the attribute used to define the group of features.
4-7 FME Reference Manual Version 2.0
Safe Software Inc. FME FEATURE FACTORIES
The following example sets all features output from a factory and associated with
LINE <tag> to have a FEATURE_TYPE of JoinedRoad::TRIM and an attribute
value of 1 for the attribute numberOfLanes.
OUTPUT LINE FEATURE_TYPE JoinedRoad::TRIM numberOfLanes 1
4.5 Factory Example 1
The example below uses the GROUP_BY statement with the ArcFactory to apply its
functionality to independent groups of features. This is equivalent to having a
separate ArcFactory specification for every combination of the specified attributes.
This results in all Road::TRIM features having the same numberOfLanes and
abutting one another to be connected together. It will not connect Road::TRIM
features which have a different number of lanes.
FACTORY_DEF SAIF ArcFactory \
INPUT FEATURE_TYPE Road::TRIM \
GROUP_BY numberOfLanes \
END_NODED \
OUTPUT LINE FEATURE_TYPE JoinedRoad::TRIM
TIP: Note the use of the factory specific directive END_NODED on the ArcFactory definition.
If we assume that the numberOfLanes that a feature can have is only 1, 2, or 3,
then the above statement is equivalent to the following three factory definitions.
Notice the extra work required when the GROUP_BY clause is not specified.
Parameter Content
<tag> The tag identifies the type of feature associated with the
output clause. Factories often output more than one type of
feature and the tags are used to associate the different types of
features with attributes. See the description of the individual
factories for the tags which they support.
<feature type> The feature type assigned to features leaving the factory via
the output clause.
<attribute name> The name of the attribute into which a value is to be assigned.
<attribute value> The attribute value assigned to the attribute identified by the
associated attribute name. The attribute value may be a
constant or the value returned from an attribute function.
Attribute functions are applied immediately to the features as
they exit the feature factory.
<feature function> The feature function is executed after the attribute functions
are executed.
FME FEATURE FACTORIES Safe Software Inc.
4-8 FME Reference Manual Version 2.0
FACTORY_DEF SAIF ArcFactory \
INPUT FEATURE_TYPE Road::TRIM numberOfLanes 1 \
END_NODED \
OUTPUT LINE FEATURE_TYPE JoinedRoad::TRIM numberOfLanes 1
FACTORY_DEF SAIF ArcFactory \
INPUT FEATURE_TYPE Road::TRIM numberOfLanes 2 \
END_NODED \
OUTPUT LINE FEATURE_TYPE JoinedRoad::TRIM numberOfLanes 2
FACTORY_DEF SAIF ArcFactory \
INPUT FEATURE_TYPE Road::TRIM numberOfLanes 3 \
END_NODED \
OUTPUT LINE FEATURE_TYPE JoinedRoad::TRIM numberOfLanes 3
4.6 Factory Example 2
The following mapping file fragment describes a feature pipeline that combines a
Polygon factory, a Donut factory, and a PIPComponents factory.
FACTORY_DEF IGDS PolygonFactory \
INPUT FEATURE_TYPE 9 igds_type igds_line igds_color 56 \
igds_style 1 igds_class 2 \
INPUT FEATURE_TYPE 9 igds_type igds_line igds_color 61 \
igds_style 1 igds_class 0 \
OUTPUT LINE FEATURE_TYPE PolygonFactory_Line \
lineNum @Count(LineNum) \
OUTPUT POLYGON FEATURE_TYPE ForestCoverPolygon polyNum \
@Count(PolyNum)
FACTORY_DEF IGDS DonutFactory \
INPUT FEATURE_TYPE ForestCoverPolygon area1 @Area() \
INPUT FEATURE_TYPE 10 igds_type igds_text_node \
igds_graphic_group0 @Count(Nodes) \
INPUT FEATURE_TYPE 10 igds_type igds_multi_text \
igds_graphic_group 0 @Count(Multis \
OUTPUT POLYGON FEATURE_TYPE ForestCoverPolygon \
OUTPUT DONUT FEATURE_TYPE ForestCoverPolygonDonut area2 \
@Area() donutNum @Count(DonutNum) \
OUTPUT POINT FEATURE_TYPE ForestCoverPolygonPoint \
OUTPUT PIP FEATURE_TYPE ForestCoverPIP
FACTORY_DEF IGDS PIPComponentsFactory \
INPUT FEATURE_TYPE ForestCoverPIP \
OUTPUT POINT FEATURE_TYPE tiedpnt \
OUTPUT POLYGON FEATURE_TYPE tiedpoly
The first factory in the example is the PolygonFactory. This factory is activated when
the <Readerkeyword> is IGDS. The factory accepts features from level 9 of the
IGDS file and outputs two types of features; PolygonFactory_Line features
and ForestCoverPolygon features. The PolygonFactory_Line features
leave the factory pipeline and are processed by the remainder of the FME.
4-9 FME Reference Manual Version 2.0
Safe Software Inc. FME FEATURE FACTORIES
TIP: Notice the use of the @Count() function to count the number of features that exit the factory. This is used
to assign unique numbers to each feature leaving the factories.
The next factory in the pipeline is the DonutFactory. This factory takes the polygons
from the first factory along with text nodes and multi-text elements from the IGDS
file. The factory performs the DonutFactory operation and outputs four different
types of features from the factory. One of these types of features
ForestCoverPIPis sent on to the last factory. The other features flow on to be
processed by the remainder of the FME.
TIP: Features output from factories that are not desired by any downstream factories get moved on to the
transformation process.
The final factory in the pipeline is the PIPComponentsFactory. This factory takes
ForestCoverPIP features from the earlier factory and outputs two types of
features: tiedpnt and tiedpoly. These two types of features are then processed
by the rest of the system.
FME FEATURE FACTORIES Safe Software Inc.
4-10 FME Reference Manual Version 2.0
5-1 FME Reference Manual Version 2.0
5
5 FME TRANSLATION PROCESS
As features flow through the FME, they are transformed from their original
state to some destination state according to the rules read from the mapping
file. These rules, called transformation specifications, are used to:
identify a feature for transformation
change the features attribute names, values, and feature type
Figure 5-1 FME Translation Process
This section describes this process, and how it is driven by the mapping file.
5.1 Transformation Specification
The transformation specification determines the mapping between source
features and destination features. Each transformation specification consists
of a pair of lines: one line associated with the source format, and one line
associated with the destination format. The source line is used as a filter to
Source
Feature
Transformation
Module
Destination
Feature
FME TRANSLATION PROCESS Safe Software Inc.
5-2 FME Reference Manual Version 2.0
determine which source features match the transformation specification. If a feature
matches a source specification line, then the destination line instructs the FME how
the feature is to be written to the destination format. Each feature is matched to a
single specification line. If a feature could potentially match several different
transformation specifications, then the first one defined in the mapping file is used.
The mapping file fragment below is used to direct translations between IGDS Design
File and ESRIs SDE. It illustrates the use of the mapping file in directing the
transformation between formats.
# -------------------------------------------------
# Handle Roads
IGDS 12 igds_type igds_line igds_color 10 igds_style 3
SDE ROAD NUMLANES 2 PAVED false
TIP: Note that these two lines control transformation in both directions from IGDS to the SDE, as well as from
the SDE to IGDS.
This pair of lines instructs the FME to convert a linear IGDS source feature with a
color value of 10 and a style of 3 residing on level 12 of the design file into an SDE
feature on the ROAD layer, with the number of lanes set to 2 and the paved flag set
to false. If the specifications were to change whereby all two-lane, unpaved roads
were found to reside on level 13 of the Design File, the operator need only alter this
portion of the mapping file to handle the schema change:
# -------------------------------------------------
# Handle Roads
IGDS 13 igds_type igds_line igds_color 10 igds_style 3
SDE ROAD NUMLANES 2 PAVED false
The portion of a mapping file which specifies how features are transformed consists
of a series of transformation specifications. These lines specify how features are
transformed from some source to some destination. Each transformation specification
consists of a pair of two lines, a source line, and a destination line.
TIP: Transformation specifications are bidirectional. The same transformation specification is used to control
transformation from format A to format B, as well as back to format A from format B.
In general, transformation specifications follow this pattern:
<ReaderKeyword> <Source Feature Type> \
[<attribute name> <attribute value>]* \
[<feature function>]*
<WriterKeyword> <Destination Feature Type> \
[<attribute name> <attribute value>]* \
[<feature function>]*
The feature type is the type of feature to match if on the source line, or the new feature
type if on the destination line. The wildcard feature type, the asterisk (*) character,
matches any feature type when found on a source line. On a destination line, it does
not alter the existing feature type of the feature. In addition, when the wildcard feature
type is used on a destination line, it also carries across all attributes of the source
5-3 FME Reference Manual Version 2.0
Safe Software Inc. FME TRANSLATION PROCESS
feature. This is useful when the FME is used to translate from one format back to
itself.
The attribute value may be one of the following:
Constant: An explicit value assigned to the associated attribute name. When on
the source line, constant values are the only attribute values used to match
features. On the destination line, the constant values are used to set feature
attribute values.
Transfer Variable: A variable used to transfer an attribute value from the source
line to the destination line. All transfer variables start with a percent (%)
character.
Attribute Function: A function whose return value is used to set attribute values.
TIP: Use the @SupplyAttributes function to supply constant values to attributes when you do not want the
attribute values to be used for specification matching. See Appendix A for details.
Feature functions are functions that perform operations on a feature as a whole. They
may be used to change a features geometry, or operate on groups of attributes at a
single time. See Appendix A for a full description of FME feature and attribute
functions.
5.1.1 Source Line
The source line of a transformation specification is used as a pattern to be matched
against features. Source lines begin with the current <ReaderKeyword>, which
by default is the same as the name of the reader module being used. For a feature to
match the source line, it must have the same feature type as the source line. In
addition, the features attribute values must have the same values as any attribute
constants listed on the source line. Source lines also identify attribute values to be
transferred across to the destination line. Finally, the inverse operation of all feature
functions and attribute functions on the source line are executed from right to left.
5.1.2 Destination Line
The destination line portion of a transformation specification is the pattern used to
create an output feature once a match has been made. It is applied when a feature
matches a source line and all the transformation variables have been loaded. The
feature type of the output feature is set to the feature type listed on the destination line,
and any constant attribute values are set. Attribute values may also be set to the value
of transfer variables loaded on the source line. Finally, all feature or attribute
FME TRANSLATION PROCESS Safe Software Inc.
5-4 FME Reference Manual Version 2.0
functions are executed in the forward direction, proceeding from left to right across
the line.
5.1.3 Example
The following transformation specification translates road features between IGDS
and SAIF:
# -------------------------------------------------
# Handle Roads
IGDS 12 igds_type igds_line igds_color 10 igds_style 3
SAIF Road::TRIM position.geometry.Class arc \
numberOfLanes 2 paved false
The first word of each line specifies the source or destination system involved in the
transformation. The same pair of lines is used to go in either direction between
systems. In this example, the two lines are used to translate from IGDS to the SAIF
or from the SAIF to IGDS. The direction of the transformation determines which
keyword is used to identify candidate source features and which keyword is used to
identify destination features.
5.1.4 Matching Process
For each feature read from the source system, the FME logically scans the mapping
file from top to bottom looking for the first matching source specification. Then it
transforms the feature according to the corresponding destination specification.
Expanding on the above example, consider a mapping file containing these lines:
# -------------------------------------------------
# Handle Two Lane Roads
IGDS 12 igds_type igds_line igds_color 10 igds_style 3
SAIF Road::TRIM position.geometry.Class arc \
numberOfLanes 2 paved false
# -------------------------------------------------
# Handle Four Lane Roads
IGDS 12 igds_type igds_line igds_color 4 igds_style 3
SAIF Road::TRIM position.geometry.Class arc \
numberOfLanes 4 paved false
# -------------------------------------------------
# Handle Single Lane Roads
IGDS 12 igds_type igds_line igds_color 4
SAIF Road::TRIM position.geometry.Class arc \
numberOfLanes 1 paved false
TIP: Recall that the second word on a transformation specification line is the feature type, which for IGDS is
the features level and for SAIF is the features class.
Suppose a transformation from IGDS to SAIF is being performed, and a linear feature
from IGDS level 12 with color 10 and style 3 has been read. The FME scans down
the mapping file, examining all IGDS specifications and looking for a match. Since
the second specification matches, the feature is transformed into a SAIF
5-5 FME Reference Manual Version 2.0
Safe Software Inc. FME TRANSLATION PROCESS
Road::TRIM, with the numberOfLanes and paved attributes to 4 and false
respectively. Then the feature is sent to the SAIF writer.
TIP: The order of the transformation specifications is very important. Specifications should be listed from the
most specific to the most general.
Suppose the next IGDS feature read is a linear feature from IGDS level 12 with color
10 and style 2. The first two IGDS specifications are tested and found not to match.
However, the third IGDS specification does not refer to the style attribute, and so it
is matched. The feature is transformed into a single lane SAIF Road::TRIM. Note
that if the third IGDS specification were moved to the top of the file, it would match
any linear IGDS feature from level 12 with color 4. The result would be that no two
or four lane roads would be output. Instead, all roads encountered would be output as
single lane. For this reason, feature specifications should be listed from the most
specific to the most general.
If a feature does not match any source specification, it will not be translated. Statistics
on the number and types of features dropped, as well as those transformed, are
gathered by the FME and output to the FME log file.
5.2 Transfer Variables
In the previous examples, no attribute values were transferred between the source
feature and the destination feature. The attribute values of the destination feature were
based entirely on the matching source feature. This situation occurs often when one
of the two systems involved in the transformation is based on feature codes. For
example, certain combinations of level, line style, and color may be used to represent
certain types of features in an IGDS file.
Figure 5-2 Translation Process including Transfer Variable
Source
Feature
Transformation
Module
Destination
Feature
Transfer
Variable
FME TRANSLATION PROCESS Safe Software Inc.
5-6 FME Reference Manual Version 2.0
More commonly, however, attribute values must be transferred from an attribute of
the source feature to an attribute of the destination feature.
To accomplish this, a transfer variable is created to move the value from one system
to another. Transfer variables are identified with a first character of % and have the
following syntax:
%<variable name>[:<default value>]
TIP: The FME ensures that any transfer variables defined on a source line are referenced on a destination line,
and conversely that any transfer variables referenced on a destination line are defined on a source line.
When a transfer variable is encountered on a source line, it is assigned the value of
the features attribute it is paired with. If the feature had no value for the attribute,
then the transfer variable is set to its default value, if one was specified.
When a transfer variable is encountered on a destination line, the attribute to which it
is associated, is assigned the variables value. If the variables value was the same
as the default value, providing one was specified, then the attribute is not set.
Transfer variables may also be used as arguments to feature or attribute value
functions.
The net effect of the transfer variable is to move an attribute value from the source
feature to the destination feature. For example:
# -------------------------------------------------
# Handle Bridges
IGDS 14 igds_type igds_line igds_graphic_group %var1
SDE BRIDGE width %var1
TIP: Using descriptive transfer variable names eases maintaining and understanding the mapping file.
In this example, all linear features on level 14 represent bridges, and the width of the
bridges is encoded in the IGDS graphic group field. The transfer variable var1 is
used to transfer this width value between the IGDS encoding and the SDE width
attribute. Note that transfer variables may have any name, so long as they are unique
within a single transformation specification and start with a percent character (%).
5.3 Default Attribute Values
In some formats, the absence of a value implies a predefined value. In other words,
there is a default value for an attribute which will not be explicitly stored in the
format. To accommodate transformations supporting such formats, the transfer
variable syntax provides a means of specifying a default value. The default value is
listed immediately after the transfer variable name, and is separated from the variable
name by a colon (:). For example:
5-7 FME Reference Manual Version 2.0
Safe Software Inc. FME TRANSLATION PROCESS
# -------------------------------------------------
# Handle Bridges
SAIF Bridge::TRIM bridgeType %bt:footBridge
SDE BRIDGE bridgeType %bt
In this example, bridge features stored in the SAIF format will not have a
bridgeType attribute when the value of the bridgeType is footBridge. The
absence of the attribute implies this value. When a transformation from SAIF to the
SDE is performed, the %bt transfer variable is assigned the value of footBridge
if no bridgeType attribute was present in the feature. If a bridgeType attribute
were present, then its value would be used. In either case, the SDE bridgeType
attribute would have its value set.
If a translation from the SDE into SAIF is performed using the same transformation
specification, the value stored in the SDE bridgeType attribute would initially be
assigned to the %bt variable to be transferred to SAIF. However, when the feature
was transformed into a SAIF feature, a test would be done to ensure that the %bt
variable was not equal to the default value of footBridge before it was transferred.
If it was equal to footBridge, it would not be transferred.
FME TRANSLATION PROCESS Safe Software Inc.
5-8 FME Reference Manual Version 2.0
6-1 FME Reference Manual Version 2.0
6
6 FME MAPPING FILE SYNTAX
The translation of features from a source system to a destination system is
completely controlled by rules specified in the semantic mapping file. This
ASCII text file consists of a series of translation specifications.
In this section, the syntax and facilities of FME mapping files
1
are described.
Subsequent sections explain the actual matching and transformation process.
Familiarity with the syntax of the mapping files will assist you in
understanding the examples encountered later in this manual.
6.1 Overview
The mapping file consists of free-form ASCII text organized into a series of
lines. To expedite maintenance, a mapping file may contain both line and
block comments which can be nested, text expansion macros, and include
other text files. Each non-comment line in the correlation file starts with a
keyword recognized by some component of the translation engine.
6.2 Line Continuation
Long mapping file lines may logically continue to the next line by using a
backslash (\) as its last character. For example, the following two lines:
1. Mapping files were called control files in earlier versions of the FME, but have been changed
to be consistent with Open Geodata Interoperability Specification (OGIS) terminology.
FME MAPPING FILE SYNTAX Safe Software Inc.
6-2 FME Reference Manual Version 2.0
IGDS 45 igds_color 8 \
igds_style 3
are equivalent to this line:
IGDS 45 igds_color 8 igds_style 3
There is no limit on the number of consecutive lines that may be joined together using
continuation characters.
TIP: Breaking long lines into several smaller parts makes your mapping files easier to read and maintain. The
continued parts of lines are usually indented to aid readability.
6.3 Quoted Text
Parameters or string literals containing spaces or tabs must be enclosed in quotation
marks. The quotation marks are stripped off by the FME when the mapping file is
processed, and the string they contain is treated as a single token. The example below
assigns the text Hello There to the text.textString attribute of a SAIF
object.
SAIF Text::TRIM text.textString Hello there
If a parameter or string literal is to contain a quotation mark, it must be escaped by
placing a backslash before it, as shown in the below example:
SAIF Text::TRIM text.textString Some \ label
6.4 Single Line Comments
Mapping files are mini-programs interpreted by the FME. In keeping with good
programming practice, the mapping file should be documented. The FME ignores any
line that starts with a hash (#) character. Blank lines are also ignored. For example,
the line below will be ignored during processing:
# This line is a comment
Note that the hash character must be the first character in the line to be considered a
comment, so it is not possible to place a comment on the same line as a control line.
For example, the line below would not be recognized as containing a comment and
would be reported by the IGDS module as invalid:
IGDS 45 igds_color 8 # This is a road
TIP: A mapping file is easier to read if groups of logically related lines are separated by whitespace and a solid
comment line.
6-3 FME Reference Manual Version 2.0
Safe Software Inc. FME MAPPING FILE SYNTAX
6.5 Block Comments
Sometimes a larger discussion of the mapping file contents is desired. To accomplish
this without the inconvenience of starting each line of the comment with a special
character, a block comment may be used. Block comments start with slash-asterisk
(/*) at the beginning of the line, and end with an asterisk-slash (*/) at the end of the
line.
The following examples illustrate the use of block comments in a mapping file:
/* This is a one line block comment */
/*
This is a multi-line comment.
Any text in here will be ignored.
/* This is a nested comment */
*/
TIP: Because block comments may be nested, they are often useful for disabling large sections of a mapping
file during testing.
6.6 MACRO Directive
To avoid duplicating portions of correlation lines repeatedly throughout a mapping
file and to allow creating symbolic constants to avoid hardcoding numbers, the
mapping file provides a simple textual substitution mechanism. Macros are defined
by lines starting with the keyword MACRO which must be in uppercase letters. The
word following the MACRO keyword is the name of the macro, which will be replaced
by the contents of the rest of the line when it is expanded on other lines. A macro
expansion is requested by enclosing the macro name with $( and ). The lines below:
MACRO blue 8
IGDS 32 igds_color $(blue) igds_style 3
will be expanded to:
IGDS 32 igds_color 8 igds_style 3
TIP: Using macros as symbolic constants for color numbers and line styles eases the maintenance of mapping
files.
Macro definitions may themselves refer to other macros, which will be expanded
recursively at the time the outermost macro is expanded. Macros may be redefined at
any time in the file. A macro definition remains in effect from the point of definition
until the end of the file, or until it is redefined. Macro definitions may, of course, be
spread over several lines using the continuation character (\) to join consecutive
physical lines. A macro may not, directly or indirectly, refer to itself.
FME MAPPING FILE SYNTAX Safe Software Inc.
6-4 FME Reference Manual Version 2.0
The FME flags any reference to an undefined macro, and stops the translation if one
is encountered.
The next example illustrates a more complex use of macros to define a large,
commonly used correlation block. Note that the first macro itself references another
macro to set the color of the text. Once the two macros are defined, they are then used
in the specification of the translation from SAIF to IGDS.
MACRO IGDSTextSpec \
igds_color $(blue) \
igds_type igds_text \
igds_style 0 igds_class 0 igds_weight 1 \
igds_text_size %size \
igds_text %string \
igds_font %font \
igds_rotation %orientation
MACRO SAIFTextSpec \
textOrSymbol.characterHeight %size \
textOrSymbol.text %string \
textOrSymbol.fontName %font \
textOrSymbol.orientation @SAIFAngle(%orientation)
#-----------------------------------------------------
# Feature KB14250000 -- Text (Hydrographic)
IGDS 44 igds_color 2 $(IGDSTextSpec)
SAIF OtherText::TRIM \
textType hydrographic $(SAIFTextSpec)
6.7 Predefined Macros
Often a mapping file contains references to external data files to be used during
translation. To simplify the portability of such a mapping file from system to system,
the FME automatically defines the FME_CF_DIR macro to contain the directory of
the mapping file. By placing external data files in the same directory as the mapping
file using them and then using this macro as their directory name, hardcoded
directories are avoided.
TIP: Placing referenced data files in the same directory as the mapping file and using the FME_CF_DIR macro
for their directory, makes your configurations inherently portable across installations.
The mapping file fragment below shows how the FME_CF_DIR macro is used to
specify the location of the SAIF class definition files. The two Class Syntax Notation
(CSN) files are located in the same directory as the mapping file. If the mapping file
and CSN files are transferred to another computer, the mapping file will not require
editing in order to work, as it contains no hardcoded references.
SAIF_CSN $(FME_CF_DIR)/saif32.csn
SAIF_CSN $(FME_CF_DIR)/trim32.csn
6-5 FME Reference Manual Version 2.0
Safe Software Inc. FME MAPPING FILE SYNTAX
In addition, the macro FME_HOME is also defined automatically. This macro expands
to the directory containing the FME executable, and may be used to locate frequently
referenced system data files.
6.8 DEFAULT_MACRO Directive
Default macros are used to supply a value to a macro name only if the macro was
undefined. If the macro was already defined, the DEFAULT_MACRO line is
equivalent to that of the MACRO directive.
DEFAULT_MACRO CELL_LIB DEFAULT.LIB
6.9 INCLUDE Directive
To allow for modularity and reuse of portions of mapping files, a facility exists to
allow mapping files to include other mapping files. The net effect is that the entire
contents of the included file are processed as though they were pasted into the
mapping file containing them.
TIP: Breaking mapping files into smaller pieces allows reuse of mapping file portions, which eases
maintenance.
The INCLUDE keyword is followed by the name of the file to include. If the filename
given is not an absolute path, then the filename is assumed to be relative to the
location of the containing file. For example, the control fragment below:
INCLUDE colors.fmi
causes the contents of the colors.fmi file to be read before the rest of the file is
processed. The colors.fmi file must be in the same directory as the mapping file
that included it. Of course, absolute pathnames may also be specified in an INCLUDE
statement.
TIP: Mapping files are normally named with an .fme extension. Included files are normally named with
an .fmi extension.
INCLUDE files are often used to define macros that are used by many mapping files.
In this way, a mapping file change may be made in just one place and affect all
mapping files that include the changed file.
TIP: The filename to be included may be composed of macros. For example,
INCLUDE $(_COLOR_SETTINGS)
There is no limit on the nesting of INCLUDE files, but circular includes are not
allowed.
FME MAPPING FILE SYNTAX Safe Software Inc.
6-6 FME Reference Manual Version 2.0
6.10 Environment Variable Expansion
Sometimes it is useful to pick up the value of an environment variable within a
mapping file. This allows session settings to be part of a users environment, rather
than requiring them to be specified each time a mapping file is run. An environment
variable expansion is requested by enclosing the environment variable name with ${
and }.
TIP: Each operating system defines its own mechanism for setting environment variables. On UNIX, they are
most often set in .login or .cshrc scripts, that run when a user logs on. On Windows NT/95, they may
be set in an AUTOEXEC.BAT file or using the Control Panel.
Assuming that the environment variable FME_CONTROL_DIR has been set to
/usr/control_files, the line below:
INCLUDE ${FME_CONTROL_DIR}/mappings.fme
will be expanded to:
INCLUDE /usr/control_files/mappings.fme
Environment variable values may themselves refer to other environment variables,
which will be expanded recursively when the outermost environment variable is
substituted. An environment variable may not, directly or indirectly, refer to itself.
The FME flags any reference to an undefined environment variable, and stops the
translation if one is encountered.
6.11 Static Function Evaluation
In certain situations, it is convenient to execute an FME attribute function as the
mapping file is parsed. The value returned from the function is then used as if it was
part of the original mapping file. In this way, certain settings are determined
dynamically rather than by prompting the user.
An FME function may be invoked at mapping file parse time by enclosing it with
$[ and ]. The function may take any type of arguments, including macros, which
are expanded prior to its evaluation.
Only functions returning a value are legal in this context.
For example, if the mapping file contains the output shape file line:
SHAPE road creationTime $[@TimeStamp(^Y^m^d^H^M^S)]
6-7 FME Reference Manual Version 2.0
Safe Software Inc. FME MAPPING FILE SYNTAX
all road objects created will have the same value for their timestamp attribute. The
timestamp will be the parse time of the mapping file. However, if the mapping file
contained the line:
SHAPE road creationTime @TimeStamp(^Y^m^d^H^M^S)
all road objects created will have different time stamps, reflecting the time this
object was created.
Other FME functions that are often useful in this context are @Lookup and
@Evaluate. Refer to Appendix A for details.
FME MAPPING FILE SYNTAX Safe Software Inc.
6-8 FME Reference Manual Version 2.0
7-1 FME Reference Manual Version 2.0
7
7 FME CONFIGURATION
Previous sections1 through 6have described the syntax and capabilities
of the FME processing facilities. Sections 10 through 25 describe the
operation of the individual reader and writer modules available to the FME.
In this section, the configuration of the FME itself is explained.
7.1 Reader and Writer Selection
The two most important FME keywords specify the reader and writer
modules to be used during an FME session. The syntax of these keywords are:
READER_TYPE <readerType>
WRITER_TYPE <writerType>
Any valid reader or writer module may be named following these keywords.
When the FME session is started, the mapping file is scanned for these two
keywords and the appropriate reader and writer are created.
The mapping file fragment below creates a SAIF reader and a Shape writer:
READER_TYPE SAIF
WRITER_TYPE SHAPE
The FME command line shown below overrides the settings for
READER_TYPE and WRITER_TYPE in the mapping file and causes an
IGDS reader and a SAIF writer to be created:
fme roadgen.fme READER_TYPE IGDS WRITER_TYPE SAIF
FME CONFIGURATION Safe Software Inc.
7-2 FME Reference Manual Version 2.0
7.2 Reader and Writer Keywords
When a reader and writer are created, they scan the mapping file for additional
parameters to configure their operation.
All reader and writer parameters are labelled with a two part keyword. The prefix of
the keyword is the current keyword associated with the reader or writer. The suffix
identifies the configuration option. The general form of these parameters is:
<ReaderKeyword>_<ReaderOption> <parameter value>
<WriterKeyword>_<WriterOption> <parameter value>
By default, the <ReaderKeyword> is the same as the READER_TYPE setting, and
the <WriterKeyword> is the same as the WRITER_TYPE setting. For example, if
the READER_TYPE and WRITER_TYPE are configured as:
READER_TYPE SAIF
WRITER_TYPE SHAPE
then by default the <ReaderKeyword> is SAIF and the <WriterKeyword> is
SHAPE. When the SAIF reader is created, it searches the mapping file for parameters
prefixed with SAIF_, and the Shape writer searches for parameters prefixed with
SHAPE_.
Transformation specifications determine the mapping between source features and
destination features. The <ReaderKeyword> starts every source line of a
transformation specification, and the <WriterKeyword> starts every destination
line. In the example above, the transformation module scans the file for pairs of lines
starting with SAIF and SHAPE, with the SAIF lines being the source portion of the
transformation specification, and the SHAPE lines being the destination portion.
The default values for the <ReaderKeyword> and <WriterKeyword> may be
overridden by specifying values for READER_KEYWORD and WRITER_KEYWORD
in the mapping file or on the command line. The syntax of these directives is:
READER_KEYWORD <newReaderKeyword>
WRITER_KEYWORD <newWriterKeyword>
These directives are used most often when the READER_TYPE and WRITER_TYPE
are the same. For example, if the FME is to read an IGDS file, alter the geometry of
some of the features, then output a new IGDS file, a mechanism is needed to identify
the source and destination portions of the transformation specifications, as well as the
source and destination datasets. The following mapping file fragment shows how to
configure the FME to do such a translation:
READER_TYPE IGDS
WRITER_TYPE IGDS
WRITER_KEYWORD I_OUT
7-3 FME Reference Manual Version 2.0
Safe Software Inc. FME CONFIGURATION
# Name the input IGDS file. Note that since no
# <ReaderKeyword> was specified, the default of IGDS
# is used
IGDS_DATASET original.dgn
# Provide the name for the output IGDS file
I_OUT_DATASET newone.dgn
# Identify the seed file for the output IGDS file
I_OUT_SEED_FILE seed.dgn
# Now write a transformation specification. The
# source line will be labeled with the
# <ReaderKeyword> (IGDS), and the destination line
# will be labeled with the <WriterKeyword> (I_OUT)
IGDS 40 igds_color 3 igds_style %s
I_OUT 40 igds_color 4 igds_style %s\
@Generalize(Douglas,10)
When a <ReaderKeyword> or <WriterKeyword> is specified, the reader or
writer module first scans the file for its configuration options using this keyword as a
prefix. If any of its required options are not found, then the configuration file is
rescanned to search for the option prefixed by the default prefix, which is the same as
the reader or writer type. In the example above, if the line:
I_OUT_SEED_FILE seed.dgn
was given as:
IGDS_SEED_FILE seed.dgn
the end result would be the same. The IGDS writer module first scans the mapping
file for I_OUT_SEED_FILE, because I_OUT is the <WriterKeyword>.
However, it will not find this keyword. It then rescans the file using IGDS as the
<WriterKeyword>, and finds a value for IGDS_SEED_FILE.
7.3 Log File Configuration
The FME logs its configuration, progress, performance, statistics, warnings, and error
messages to a log file as it executes. The filename of the log file is set in the mapping
file or on the command line by supplying a value for the LOG_FILENAME keyword.
The example below sets the log files name:
LOG_FILENAME /tmp/fme.log
FME CONFIGURATION Safe Software Inc.
7-4 FME Reference Manual Version 2.0
If the named log file already exists, then the FME appends to it by default. If no
LOG_FILENAME keyword is found in the mapping file, no session logging is
performed.
TIP: After a translation, the log file should be scanned for warning messages and the statistics examined to
ensure that the translation was successful. When an error occurs during translation, the log file contains
detailed messages describing what happened and possibly a list of the features that caused the problem.
The flag LOG_APPEND directs the FME to either append to the log file if it existed
previously, or to delete it. Valid choices for this keyword are YES or NO. The default
is YES.
To assist in building customized interfaces to the FME, log information may be
routed to the standard output stream. This stream may be redirected to a graphical
user interface or a network connection. To configure the FME to log to standard
output, the LOG_STANDARDOUT keyword must be given a value of YES:
LOG_STANDARDOUT YES
To prevent the accidental creation of extremely large log files, the number of FME
features that may be logged during an FME session can be controlled. The FME logs
features found to be invalid during translation and the mapping file may request
features be logged with the @Log function. If a bad input data file is encountered, or
a mapping file inadvertently specifies logging the entire dataset, a log file several
megabytes in size may result. The value of the LOG_MAX_FEATURES keyword sets
a limit on the number of features that can be logged during a translation, which by
default is 20. This prevents excessively large log files from being inadvertently
generated. To remove the limit on the maximum number of loggable features, set
LOG_MAX_FEATURES to -1. The line below sets the maximum loggable features to
50:
LOG_MAX_FEATURES 50
7.4 Mapping File Debugging
The FME provides several facilities that may be enabled to assist in debugging
mapping files. These debugging facilities are useful for finding either errors in a
custom mapping file being developed, or errors in input data. Each debugging option
causes diagnostic information to be output to the log file.
The debug options are enabled by listing the desired debug facilities on one or more
FME_DEBUG lines in a mapping file. The syntax of these lines is:
FME_DEBUG <option1> [<optionN>]*
The valid debugging options and their actions are listed in the following table.
7-5 FME Reference Manual Version 2.0
Safe Software Inc. FME CONFIGURATION
Table 7-1 Valid Debugging Options and Related Actions
Option Action
UNCORRELATED One feature of each feature type that was not matched by any source line
of a transformation specification is logged to the log file. This assists in
determining exactly which features were not correlated, so
transformation specifications may be written for them.
UNGROUPED One feature of each feature type that was correlated and transformed but
had no output destination, is logged. For example, if a Shape feature of
the type road was created but there was no SHAPE_DEF for the road
type, the feature would be logged.
MAPPING_FILE Every line of the mapping file is logged to the log file after all blanks and
comments have been removed, continuation characters have been taken
into account, and macros have been expanded. A histogram of the
keywords encountered in the mapping file is also listed and used to view
the mapping file as the FME actually sees it. The keyword histogram can
also be used to discover missing continuation characters if it reports extra,
incorrect keywords.
TRANSFER_SPECS Each transfer specification source and destination line is logged to the log
file as it is processed. This is useful when tracking down an unmatched
transfer specification pair or to ensure that the transfer specifications are
expanded appropriately.
TRANSFER_PROCESS This is a very expansive debugging option that examines the
transformation process. It reports any attributes of source features that
were ignored or referenced but not defined during the transformation
process. As it is done on each feature and may produce a great deal of
output in the log file, it should only be done while testing mapping files
on small input datasets.
FACTORY Each factory definition line is logged as the factory is activated. This can
be used to ensure that the factories intended to operate are correctly
created and configured.
DonutFactory This activates warning output from the DonutFactory. Points and
polygons contained by more than one polygon are logged, as are polygons
containing more than one point. This is used to track down problems with
extra points or overlapping polygons in the original source dataset.
PolygonDissolve
Factory
This activates additional statistical output from the
PolygonDissolveFactory. When a GROUP_BY clause is used with this
factory, setting this debug option causes the number of features input and
output from each group to be logged.
FME CONFIGURATION Safe Software Inc.
7-6 FME Reference Manual Version 2.0
8-1 FME Reference Manual Version 2.0
8
8 COORDINATE SYSTEM
SUPPORT
All FME features know about their coordinate system and, therefore, where
they are located on the earth. An FME coordinate system contains a complete
mathematical model of the conversion between a specific location on the
earth and a set of coordinates. Coordinate system definitions are specified by
a set of parameters defining this mathematical model, including the earth
model (ellipsoid or datum), the units used to measure the coordinates, the
projection type, and any parameters specific to the projection type.
Coordinate systems may be extracted from input feature data sources, may
come predefined with the FME, or may be defined by FME users. The FME
allows output coordinate systems that are different than the input ones to be
specified, and performs the required coordinate conversions when necessary.
8.1 Overview
The FME is shipped with over 600 coordinate systems based on a variety of
different projections, ellipsoids, and datums. The file reproject.txt in
the FME installation directory contains the names and descriptions of all
predefined coordinate systems. However, some users may wish to use
coordinate systems that do not come with the FME. This sections contains a
complete reference for defining custom coordinate systems.
When a source of input feature data knows its coordinate system, the FME
creates a coordinate system matching the input data specification, and tags
each feature read with this system name. However, a majority of formats do
COORDINATE SYSTEM SUPPORT Safe Software Inc.
8-2 FME Reference Manual Version 2.0
not explicitly store the coordinate system. In such cases, mapping file directives are
used to supply coordinate system information.
The mapping file may also contain a specification as to which coordinate system the
output data is to be in. If the output coordinate system is specified and it is different
than the input coordinate system, then the FME automatically converts the feature
data between coordinate systems. For example, converting features from one
coordinate system based on North American Datum (NAD) 27 to another from
NAD83 causes the FME to perform the required datum conversion. To ensure that the
reprojection is accurate, the FME automatically vectorizes arcs, ellipses, rectangles,
and rounded rectangle objects before doing the coordinate system change. The output
system or format stores the coordinate system of the data if it has facilities for doing
so; for example, the MapInfo formats.
8.2 Coordinate System Identification
These mapping file directives are used to identify the source and destination
coordinate system:
<READER_KEYWORD>_COORDINATE_SYSTEM <coordinateSystemName>
<WRITER_KEYWORD>_COORDINATE_SYSTEM <coordinateSystemName>
If a format or system knows its coordinate system, this overrides whatever is specified
in the mapping file (if something was) and a warning is logged. If no reader
coordinate system is specified in the mapping file and the format or system does not
store coordinate system information, then the coordinate system of the features read
is not set.
If a destination coordinate system is set and the feature has been tagged with a
coordinate system, then a coordinate system conversion is performed to put the
feature into the destination system. This happens after features leave the factory
pipeline, but before they enter the transformation process.
If the destination coordinate system was not set, then the features are written out in
their original coordinate system.
If a destination coordinate system is set, but the source coordinate system was not
specified in the mapping file, nor was it ascertained from the source system, then no
conversion is performed. The features are simply tagged with the output system name
before being written to the output dataset.
8-3 FME Reference Manual Version 2.0
Safe Software Inc. COORDINATE SYSTEM SUPPORT
8.3 Coordinate System Definition
The FME enables new coordinate system definitions to be specified in a mapping file,
as described below. For most users, the supplied coordinate system definitions are
sufficient. However, specific sites may require custom coordinate systems. The
COORDINATE_SYSTEM_DEF directive provides a facility for defining new
coordinate systems.
COORDINATE_SYSTEM_DEF <coordSysName>
PROJ <projType> \
UNIT <unitName> \
(DT_NAME <datumName> | EL_NAME <ellipName>) \
[<parameter> <value>]+ \
DESC_NM <descriptive_name> \
SOURCE <source>
Table 8-1 Local Coordinate System Definitions
Name Range Description Optional
<coordSysName> any string The name of the coordinate
system being defined may be
used to identify the coordinate
system of a reader or writer, or
as an argument to
@Reproject or
_COORDINATE_SYSTEM.
No
<unit name> See Section 8.4 The name of the units used to
measure coordinates in the
coordinate system.
No
<projType> See Section 8.5 The type of map projection used
for this definition. This name
must come from the table below,
and it determines which other
parameters may be specified.
The parameters used by each
projection type are described
below.
No
<parameter> Depends on the
projection
systemsee
Section 8.5
Each projection system makes
use of a set of parameters. These
are listed for each supported
project in subsequent tables.
No
<datumName> See Section 8.6 The datum to be used for the
projection. Either a datum or an
ellipsoid must be specified for
each coordinate system.
Yes
<ellipName> See Section 8.7 The ellipsoid to be used for the
projection. Either a datum or an
ellipsoid must be specified for
each coordinate system.
Yes
<descriptive
name>
any string A descriptive name of the
definition.
Yes
<source> any string Source person or agency who
supplied the definition.
Yes
COORDINATE SYSTEM SUPPORT Safe Software Inc.
8-4 FME Reference Manual Version 2.0
8.3.1 Example Coordinate System Definitions
This mapping file fragment defines a NAD83 based UTM Zone 12 coordinate
system.
COORDINATE_SYSTEM_DEF UTM12N83 \
DT_NAME NAD83 \
PROJ TM \
UNIT METER \
PARM1 -111.0 \
SCL_RED 0.9996 \
ORG_LAT 0.0 \
X_OFF 500000.0 \
Y_OFF 0.0 \
MAP_SCL 1.0
This mapping file fragment defines an Albers Equal Area coordinate system called
BCALB-83.
COORDINATE_SYSTEM_DEF BCALB-83 \
PROJ AE \
DT_NAME NAD83 \
UNIT METER \
PARM1 50.0 \
PARM2 58.5 \
ORG_LNG -126.0 \
ORG_LAT 45.0 \
X_OFF 1000000.0 \
Y_OFF 0.0 \
MAP_SCL 1.0
TIP: These coordinate systems are among the many predefined systems delivered with the FME.
8.3.2 Local Coordinate System Definitions
To allow sites to add their own coordinate systems, a file of local coordinate system
definitions is automatically loaded and made available to each FME session. This file
is found in the Reproject subdirectory under the FME installation directory and is
called LocalCoordSysDefs.fme. It contains a series of
COORDINATE_SYSTEM_DEF, DATUM_DEF, ELLIPSOID_DEF, and UNIT_DEF
lines that define additional, site-specific coordinate systems. Users may edit these
files to add their own definitions. In the FME Solutions Guide: Chapter 9, Using
Custom Coordinate Systems this process is described in detail.
8-5 FME Reference Manual Version 2.0
Safe Software Inc. COORDINATE SYSTEM SUPPORT
8.4 Coordinate Units
The predefined units available to measure coordinates are given in the following
table:
Table 8-2 Coordinate Units Supported by FME
For the Latitude/Longitude pseudo-projection, units of angle are used to measure the
coordinates. The list of such units predefined in the FME is given in Section 8.5.14,
Table 8-5.
8.4.1 Unit Definition
Custom coordinate units are defined when coordinates are measured in units, not in
the predefined set of units. For example, Canadian users wanting to perform
coordinate conversions directly between NAD27 Grid Coordinates and NAD83
ground coordinate, can perform this operation by defining the length of the grid units.
Unit definitions may occur in an FME mapping file, as well as in the
LocalCoordSysDefs.fme. The syntax of a unit definition is:
FME Unit Name Full Name Unit length in metres
CENTIMETER centimetre 0.01
CHAIN chain 20.11684023368047
FOOT US survey foot 0.30480060960121920243
IFOOT international foot 0.3048
IINCH international inch 0.0254
IMILE international mile 1609.344
INCH inch 0.0254000508001016002
IYARD international yard 0.9144
KILOMETER kilometre 1000
LINK link 0.2011684023368047
METER metre 1.0
MILE mile 1609.34721869443738887477
MILLIMETER millimetre 0.001
NAUTM nautical mile 1852.0
ROD rod 5.02921005842012
YARD yard 0.91440182880365760731
COORDINATE SYSTEM SUPPORT Safe Software Inc.
8-6 FME Reference Manual Version 2.0
UNIT_DEF <unit name> \
UNIT_TYPE <unit type> \
UNIT_ABBREVIATION <unit abbreviation> \
UNIT_FACTOR <unit size>
Table 8-3 Unit Definition Parameters
8.4.2 Example Unit Definition
This mapping file fragment defines a unit used to perform coordinate conversions
from NAD27 Grid to NAD83 Ground:
UNIT_DEF GRIDUNIT \
UNIT_TYPE LENGTH \
UNIT_ABBREVIATION GRD \
UNIT_FACTOR 0.999738
8.5 Projection Types
Each coordinate system definition must specify a projection type and provide values
for all of the parameters associated with the projection.
Table 8-4 lists the projection types allowed in coordinate system definitions. A
description of each parameter used by each projection type follows the table.
Name Range Description Optional
<unitname> any string The name of the unit being
defined.
No
<unittype> ANGLE |
LENGTH
Specifies whether the unit
measures angles or lengths.
No
<unit
abbreviation>
any string This abbreviation represents the
unit and may be used in
coordinate system definitions
instead of the <unitname>.
No
<unitsize> Floating point
number
The size of a unit in metres if it
measures length. If the unit
measures angle, then this is the
size in degrees.
No
8-7 FME Reference Manual Version 2.0
Safe Software Inc. COORDINATE SYSTEM SUPPORT
Table 8-4 Allowed Projection Types
Projection Type Full Projection Name
AE Albers Equal Area
AZMEA Lambert Azimuthal Equal Area
ASMED Lambert Azimuth Equidistant
BIPOLAR Bipolar Oblique Conformal Conic
BONNE Bonne
CASSINI Cassini
ECKERT4 Eckert 4
ECKERT6 Eckert 6
EDCNC Equidistant Conic
EDCYL Equidistant Cylindrical
GNOMONIC Gnomonic
GOODE Good Homolosine
HOM1UV Hotline Oblique Mercator one point unrectified
HOM1XY Hotline Oblique Mercator one point rectified
HOM2UV Hotline Oblique Mercator two points unrectified
HOM2XY Hotline Oblique Mercator two points rectified
LL Latitude/Longitude
LM Lambert Conformal Conic
LMTAN Lambert Tangential
MILLER Miller Cylindrical
MODPC Modified Polyconic
MOLLWEID Mollweide Projection
MRCAT Traditional Mercator
MSTERO Modified Stereographic
NEACYL Normal Aspect Equal Area Cylindrical
NZEALAND New Zealand National Grid
ORTHO Orthographic
PLYCN American Polyconic
ROBINSON Robinson
COORDINATE SYSTEM SUPPORT Safe Software Inc.
8-8 FME Reference Manual Version 2.0
8.5.1 AE: Albers Equal Area
8.5.2 AZMED: Lambert Azimuthal Equidistant Projection
There are two modespoint and azimuth. The modes differ in the manner in which
the relationship of the Y axis to true north is defined. In the point mode, the direction
of the Y axis is defined by a point, given in latitude and longitude on the positive Y
axis. In the azimuth mode, the azimuth of the Y axis is given in degrees east of north.
SINUS Sinusoidal
STERO Stereographic
TEACYL Transverse Aspect Equal Area Cylindrical
TM Transverse Mercator
VDGRNTN Van Der Grinten
Parameter Name Description
PARM1 Latitude, in degrees, of the first standard parallel, usually the
nothernmost.
PARM2 Latitude, in degrees, of the second standard parallel, usually
the southernmost. This may be the same as PARM1 to obtain
a conic with a single point of tangency.
ORG_LAT Latitude, in degrees, of the origin of the projection.
ORG_LNG Longitude, in degrees, of the origin of the projection.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from meters to coordinate system
units, and the mapping scale which is to be applied.
X_OFF The false easting to be applied to all X coordinates, selected
to cause all X coordinates within the coordinate system to be
positive values of reasonable size.
Y_OFF The false northing to be applied to all Y coordinates.
Projection Type Full Projection Name
8-9 FME Reference Manual Version 2.0
Safe Software Inc. COORDINATE SYSTEM SUPPORT
In the point mode, the following parameters must be set.
In the azimuth mode, the following parameters must be set.
The following parameters are common to both modes:
Parameter Name Description
PARM1 Longitude, in degrees, of a point on the positive Y axis of the
coordinate system. This point is used to compute the azimuth
of the Y axis of the coordinate system, therefore the actual
location of the point is immaterial as long as it is on the
positive portion of the Y axis of the coordinate system.
PARM2 Latitude, in degrees, of a point on the positive Y axis of the
coordinate system. This point is used to compute the azimuth
of the Y axis of the coordinate system, therefore the actual
location of the point is immaterial as long as it is on the
positive portion of the Y axis of the coordinate system.
PARM3 This parameter is taken as an integer which indicates the
quadrant of the coordinate system which has positive X and Y
values. For example, normal coordinate systems where X
increases to the right while Y increases up require a value of
one. A system where the X axis increases to the left would
require a value of two. The quadrants are numbered as shown
here:
Parameter Name Description
PARM1 The azimuth, in degrees east of north, of the positive Y axis
of the coordinate system.
PARM2 This parameter is taken as an integer that indicates the
quadrant of the coordinate system which has positive X and Y
values. For example, normal coordinate systems where X
increases to the right while Y increases up require a value of
one. A system where the X axis increases to the left would
require a value of two.
Parameter Name Description
ORG_LNG The longitude, in degrees, of the origin of the projection.
ORG_LAT The latitude, in degrees, of the origin of the projection.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from meters to coordinate system units
and the mapping scale to be applied.
2 1
3 4
COORDINATE SYSTEM SUPPORT Safe Software Inc.
8-10 FME Reference Manual Version 2.0
8.5.3 AZMEA: Lambert Azimuthal Equal Area Projection
There are two modespoint and azimuth. The modes differ in the manner in which
the relationship of the Y axis to true north is defined. In the point mode, the direction
of the Y axis is defined by a point, given in latitude and longitude, on the positive Y
axis.
In the point mode, the following parameters must be set.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinates
system to be positive values of reasonable size. This is the X
coordinate of the coordinate system origin.
Y_OFF The false northing to be applied to all Y coordinates. This is
the Y coordinate of the coordinate system origin.
Parameter Name Description
PARM1 Longitude, in degrees, of a point on the positive Y axis of the
coordinate system. This point is used to compute the azimuth
of the Y axis of the coordinate system, therefore the actual
location of the point is immaterial as long as it is on the
positive portion of the Y axis of the coordinate system.
PARM2 Latitude, in degrees, of a point on the positive Y axis of the
coordinate system. This point is used to compute the azimuth
of the Y axis of the coordinate system, therefore the actual
location of the point is immaterial as long as it is on the
positive portion of the Y axis of the coordinate system.
PARM3 This parameter is taken as an integer indicating the quadrant
of the coordinate system that has positive X and Y values. For
example, normal coordinate systems where X increases to the
right while Y increases up, require a value of one. A system
where the X axis increases to the left, requires a value of two.
ORG_LNG The longitude, in degrees, of the origin of the projection.
ORG_LAT The latitude, in degrees, of the origin of the projection.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from meters to coordinate system units
and the mapping scale which is to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinates
system to be positive values of a reasonable size. This is the
X coordinate of the coordinate system origin.
Y_OFF The false northing to be applied to all Y coordinates. This is
the Y coordinate of the coordinate system origin.
Parameter Name Description
8-11 FME Reference Manual Version 2.0
Safe Software Inc. COORDINATE SYSTEM SUPPORT
8.5.4 BONNE: Bonne Projection
8.5.5 BIPOLAR: Bipolar Oblique Conformal Conic
This projection is usually used only for the specific coordinate system for which it
was invented. However, to remain consistent with the rest of the projections, the
following parameters can be specified. These parameters specify the location of the
two poles upon which the projection is based. The first is always specified by latitude
and longitude. The latitude of the second pole must always be specified. However the
longitude of the second pole can either be specified directly (PARM3) or as an angular
distance from the first pole (PARM5). If PARM5 is greater than zero, the second
method is used. The parameter values usually used are shown in bold.
Parameter Name Description
ORG_LNG The longitude, in degrees, of the central meridian of the
projection.
ORG_LAT The latitude, in degrees, of the standard parallel of the
projection.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from meters to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size.
Y_OFF The false northing to be applied to all Y coordinates.
Parameter Name Description
PARM1 Longitude, in degrees, of the first pole (usually the southwest).
[-110.0]
PARM2 Longitude, in degrees, of the first pole. [-20.0]
PARM3 Longitude, in degrees, of the second pole (usually the
northeast). [+45.0]
PARM4 Latitude, in degrees, of the second pole. [-19.99333333]
PARM5 If greater than zero, this value is considered to be the angular
distance, in degrees, from the first pole to the second pole and
the longitude of the second pole is computed as such. If this
value is zero, the value provided in PARM3 is considered the
longitude of the second pole. [=104.0]
PARM6 Angular distance, in degrees, from either pole to the first of two
standard parallels. [+31.0]
COORDINATE SYSTEM SUPPORT Safe Software Inc.
8-12 FME Reference Manual Version 2.0
8.5.6 EDCNC: Equidistant Conic Projection
8.5.7 EDCYL: Equidistant Cylindrical Projection
PARM7 Angular distance, in degrees, from either pole to the second of
two standard parallels. [+73.0]
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from meters to coordinate system units
and the mapping scale to be applied. [1.0]
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size. [0.0]
Y_OFF The false northing to be applied to all Y coordinates. [0.0]
Parameter Name Description
PARM1 Latitude, in degrees, of the first standard parallel, usually the
northernmost (it makes no difference).
PARM2 Latitude, in degrees, of the second standard parallel, usually
the southernmost. This parameter is sometimes set to the same
value as PARM1 to obtain a conic with a single point of
tangency, i.e., a single standard parallel.
ORG_LNG The longitude, in degrees, of the origin of the projection.
ORG_LAT The latitude, in degrees, of the origin of the projection.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size.
Y_OFF The false northing to be applied to all Y coordinates.
Parameter Name Description
PARM1 Latitude, in degrees, of the reference parallel.
ORG_LNG The longitude, in degrees, of the origin of the projection.
ORG_LAT The latitude, in degrees, of the origin of the projection.
Parameter Name Description
8-13 FME Reference Manual Version 2.0
Safe Software Inc. COORDINATE SYSTEM SUPPORT
8.5.8 ECKERT4: Eckert 4 Projection
8.5.9 ECKERT6: Eckert 6 Projection
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size. This is the X
coordinate of the coordinate system origin.
Y_OFF The false northing to be applied to all Y coordinates. This is
the Y coordinate of the coordinate system origin.
Parameter Name Description
ORG_LNG The longitude, in degrees, of the origin of the projection
(central meridian).
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size. This is the X
coordinate of the coordinate system origin.
Y_OFF The false northing to be applied to all Y coordinates. This is
the Y coordinate of the coordinate system origin.
Parameter Name Description
ORG_LNG The longitude, in degrees, of the origin of the projection
(central meridian).
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size. This is the X
coordinate of the coordinate system origin.
Y_OFF The false northing to be applied to all Y coordinates. This is
the Y coordinate of the coordinate system origin.
Parameter Name Description
COORDINATE SYSTEM SUPPORT Safe Software Inc.
8-14 FME Reference Manual Version 2.0
8.5.10 GNOMONIC: Gnomonic Projection
8.5.11 GOODE: Goode Homolosine Projection
Parameter Name Description
PARM1 Latitude, in degrees, of the reference parallel.
ORG_LNG The longitude, in degrees, of the origin of the projection.
ORG_LAT The latitude, in degrees, of the origin of the projection.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size. This is the X
coordinate of the coordinate system origin.
Y_OFF The false northing to be applied to all Y coordinates. This is
the Y coordinate of the coordinate system origin.
Parameter Name Description
PARM1-24 The interrupted form of the Goode Homolosine Projection is
fully supported. PARM1 through PARM24 can be used to
specify the extents of the different zones.
ORG_LNG The longitude, in degrees, of the origin of the projection.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size. This is the X
coordinate of the coordinate system origin.
Y_OFF The false northing to be applied to all Y coordinates. This is
the Y coordinate of the coordinate system origin.
8-15 FME Reference Manual Version 2.0
Safe Software Inc. COORDINATE SYSTEM SUPPORT
8.5.12 LM: Lambert Conformal Conic Projection
8.5.13 LMTAN: Lambert Tangential Projection
Parameter Name Description
PARM1 Latitude, in degrees, of the first standard parallel, usually the
southernmost.
PARM2 Latitude, in degrees, of the second standard parallel, usually
the northernmost. This parameter is sometimes set to the same
value as PARM1 to obtain a conic with a single point of
tangency, i.e., a single standard parallel.
ORG_LNG The longitude, in degrees, of the origin of the projection.
ORG_LAT The latitude, in degrees, of the origin of the projection.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size.
Y_OFF The false northing to be applied to all Y coordinates.
Parameter Name Description
ORG_LNG The longitude, in degrees, of the origin of the projection
relative to Greenwich.
ORG_LAT The latitude, in degrees, of the origin of the projection relative
to the equator.
SCL_RED The scale reduction factor which is to be applied to the
projection.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size. This value is
the X coordinate of the coordinate system origin.
Y_OFF The false northing to be applied to all Y coordinates. This
value is the Y coordinate of the coordinate system origin.
COORDINATE SYSTEM SUPPORT Safe Software Inc.
8-16 FME Reference Manual Version 2.0
8.5.14 LL: Latitude/Longitude
Strictly speaking, Latitude/Longitude is not a projection. All coordinates in this
projection are measured in units of latitude and longitude, relative to some ellipsoid
or datum.
For this projection, the UNIT parameter must be set to any of the angular
measurement units listed in Table 8-5.
Table 8-5 Angular Measurement Units
In addition, either an EL_NAME or DT_NAME is required.
FME Unit Name Angular Measurement in Degrees
DEGREE 1.0
GRAD 0.9
GRADE 0.9
MAPINFO 0.000001
MIL 0.05625
MINUTE 0.01666666666666666666
RADIAN 57.2957795130823208772
SECOND 0.00027777777777777777
DECISEC 0.00002777777777777777
CENTISEC 0.00000277777777777777
MILLISEC 0.00000027777777777777
Parameter Name Description
PARM1 The minimum longitude that will be used. Longitudes smaller
than this will be expressed as positive longitudes by adding
360 to them. This is used to control where the discontinuity in
longitude measurements will occur.
This value must be less than or equal to 0 and greater than or
equal to -360.
If not specified, the default is -180.
PARM2 The maximum longitude that will be used. Longitudes larger
than this will be expressed as negative longitudes by
subtracting 360 from them.
This value must be greater than or equal to 0 and greater than
or equal to 360.
Though not required, normally the range between PARM1 and
PARM2 is 360.
If not specified, the default is 180.
8-17 FME Reference Manual Version 2.0
Safe Software Inc. COORDINATE SYSTEM SUPPORT
8.5.15 MILLER: Miller Cylindrical Projection
8.5.16 MODPC: Modified Polyconic Projection
Parameter Name Description
PARM1 Latitude, in degrees, of the central meridian of the coordinate
system (or map).
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size.
Y_OFF The false northing to be applied to all Y coordinates.
Parameter Name Description
PARM1 Longitude, in degrees, of the central meridian.
PARM2 Longitude, in degrees, of the eastern meridian. The western
meridian is assumed to be west of the central meridian by the
same amount that the eastern meridian is east of the central
meridian.
PARM3 Latitude, in degrees, of the northern standard parallel.
PARM4 Latitude, in degrees, of the southern standard parallel.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size.
Y_OFF The false northing to be applied to all Y coordinates.
COORDINATE SYSTEM SUPPORT Safe Software Inc.
8-18 FME Reference Manual Version 2.0
8.5.17 MOLLWEID: Mollweide Projection
8.5.18 MRCAT: Traditional Mercator Projection
Parameter Name Description
ORG_LNG The longitude, in degrees, of the origin of the projection
(central meridian).
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size. This is the X
coordinate of the coordinate system origin.
Y_OFF The false northing to be applied to all Y coordinates. This is
the Y coordinate of the coordinate system origin.
PARM1-24 The interrupted form of the Mollweide Projection is fully
supported. PARM1 through PARM24 can be used to specify
the extents of the different zones.
Parameter Name Description
PARM1 Longitude, in degrees, of the central meridian of the
coordinate system (or map).
PARM2 Latitude, in degrees, of the standard parallel, usually zero,
indicating the equator. Using a non-zero value has an affect
similar to that of the scale reduction factor of other cylindrical
projections.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size.
Y_OFF The false northing to be applied to all Y coordinates.
8-19 FME Reference Manual Version 2.0
Safe Software Inc. COORDINATE SYSTEM SUPPORT
8.5.19 MSTERO: Modified Stereographic Projection
8.5.20 NEACYL: Normal Authalic Cylindrical Projection
Parameter Name Description
PARM1-24 Use these elements to specify the power series coefficients.
Odd and even number pairs, e.g., PARM1 and PARM2, are used
to specify the real and imaginary components of the
coefficients respectively. All other PARMs which represent
unused coefficients must be set to zero. The FME will
determine the order of the series by looking for zero
coefficients. Therefore, orders as high as 12 are supported.
Orders higher than 12 are not supported.
ORG_LNG The longitude, in degrees, of the origin of the projection.
ORG_LAT The latitude, in degrees, of the origin of the projection.
SCL_RED This element must be set to 1.0.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size.
Y_OFF The false northing to be applied to all Y coordinates.
Parameter Name Description
ORG_LNG Longitude, in degrees, of the central meridian of the
coordinate system (or map).
PARM1 Latitude, in degrees, of the standard parallel, usually zero
indicating the equator. Using a non-zero value has an affect
similar to that of the MAP_SCL reduction factor of other
cylindrical projections.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size.
Y_OFF The false northing to be applied to all Y coordinates.
COORDINATE SYSTEM SUPPORT Safe Software Inc.
8-20 FME Reference Manual Version 2.0
8.5.21 NZEALAND: New Zealand National Grid System
8.5.22 ORTHO: Orthographic Projection
8.5.23 PLYCN: American Polyconic Projection
Parameter Name Description
ORG_LNG The longitude, in degrees, of the origin of the projection.
ORG_LAT The latitude, in degrees, of the origin of the projection.
SCL_RED This element must be set to 1.0.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size.
Y_OFF The false northing to be applied to all Y coordinates.
Parameter Name Description
ORG_LNG The longitude, in degrees, of the origin of the projection.
ORG_LAT The latitude, in degrees, of the origin of the projection.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size. This is the X
coordinate of the coordinate system origin.
Y_OFF The false northing to be applied to all Y coordinates. This is
the Y coordinate of the coordinate system origin.
Parameter Name Description
PARM1 Longitude, in degrees, of the central meridian.
ORG_LAT Latitude, in degrees, of the origin of the projection.
8-21 FME Reference Manual Version 2.0
Safe Software Inc. COORDINATE SYSTEM SUPPORT
8.5.24 ROBINSON: Robinson Projection
8.5.25 SINUS: Sinusoidal Projection
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size.
Y_OFF The false northing to be applied to all Y coordinates.
Parameter Name Description
ORG_LNG Longitude, in degrees, of the origin of the projection.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size. This is the X
coordinate of the coordinate system origin.
Y_OFF The false northing to be applied to all Y coordinates.This is
the Y coordinate of the coordinate system origin.
Parameter Name Description
ORG_LNG The longitude of the central meridian of the projection, in
degrees, where positive indicates east longitude. It is this line
of longitude which is straight and true to scale. The longitude
is also considered the X origin of the projection. The Y origin
is always the equator.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system
units, the scale reduction factor, and the mapping scale to be
applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size. This is the X
coordinate of the coordinate system origin.
Parameter Name Description
COORDINATE SYSTEM SUPPORT Safe Software Inc.
8-22 FME Reference Manual Version 2.0
8.5.26 STERO: Stereographic Projection
There are two modespoint and azimuth. The modes differ in the manner in which
the relationship of the Y axis to true north is defined. In the point mode, the direction
of the Y axis is defined by a point, given in latitude and longitude, on the positive Y
axis.
In the point mode, the following parameters must be set:
Y_OFF The false northing to be applied to all Y coordinates. This is
the Y coordinate of the coordinate system origin.
PARM1-24 These 24 doubles can be used in groups of three to specify the
zones of an interrupted Sinusoidal Projection. Leave all
values set to zero for a standard single zone projection based
on the origin longitude specified in the ORG_LNG element.
Parameter Name Description
PARM1 Longitude, in degrees, of a point on the positive Y axis of the
coordinate system. This point is used to compute the azimuth
of the Y axis of the coordinate system, therefore the actual
location of the point is immaterial as long as it is on the
positive portion of the Y axis of the coordinate system.
PARM2 Latitude, in degrees, of a point on the positive Y axis of the
coordinate system. This point is used to compute the azimuth
of the Y axis of the coordinate system, therefore the actual
location of the point is immaterial as long as it is on the
positive portion of the Y axis of the coordinate system.
PARM3 This parameter is taken as an integer indicating the quadrant
of the coordinate system having positive X and Y values. For
example, normal coordinate systems where X increases to the
right while Y increases up require a value of one. A system
where the X axis increases to the left would require a value of
two.
ORG_LNG The longitude, in degrees, of the origin of the projection.
ORG_LAT The latitude, in degrees, of the origin of the projection.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system
units, the scale reduction factor, and the mapping scale to be
applied.
SCL_RED The scale reduction factor independent of all other scaling, is
obtained from this element and is necessary for correct
computation of the grid scale factor in some cases.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size. This value is
the X coordinate of the coordinate system origin.
Parameter Name Description
8-23 FME Reference Manual Version 2.0
Safe Software Inc. COORDINATE SYSTEM SUPPORT
In the azimuth mode, the azimuth of the Y axis is given in degrees east of north, and
the following parameters must be set:
8.5.27 TEACYL: Transverse Authalic Projection
Y_OFF The false northing to be applied to all Y coordinates. This
value is the Y coordinate of the coordinate system origin.
Parameter Name Description
PARM1 The azimuth, in degrees east of north, of the positive Y axis
of the coordinate system.
PARM2 This parameter is taken as an integer indicating the quadrant
of the coordinate system having positive X and Y values. For
example, normal coordinate systems where X increases to the
right while Y increases up require a value of one. A system
where the X axis increases to the left would require a value of
two.
ORG_LNG The longitude, in degrees, of the origin of the projection.
ORG_LAT The latitude, in degrees, of the origin of the projection.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from meters to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinates
system to be positive values of reasonable size. This is the X
coordinate of the coordinate system origin.
Y_OFF The false northing to be applied to all Y coordinates. This is
the Y coordinate of the coordinate system origin.
Parameter Name Description
ORG_LNG The longitude, in degrees, of the origin of the projection.
ORG_LAT The latitude, in degrees, of the origin of the projection.
SCL_RED The scale reduction factor to be applied. This is also referred
to as the scale of the central meridian.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
Parameter Name Description
COORDINATE SYSTEM SUPPORT Safe Software Inc.
8-24 FME Reference Manual Version 2.0
8.5.28 TM: Transverse Mercator
.
8.5.29 VDGRNTN: Van Der Grinten Projection
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size.
Y_OFF The false northing to be applied to all Y coordinates.
Parameter Name Description
PARM1 Longitude, in degrees, of the central meridian.
ORG_LAT Latitude, in degrees, of the origin of the projection.
SCL_RED The scale reduction to be applied. This is also referred to as
the scale of the central meridian.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from meters to coordinate system
units, and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, selected
to cause all X coordinates within the coordinate system to be
positive values of reasonable size.
Y_OFF The false northing to be applied to all Y coordinates.
Parameter Name Description
ORG_LNG Longitude, in degrees, of the origin of the projection.
MAP_SCL The scale of the coordinate system. This one factor must
include the conversion from metres to coordinate system units
and the mapping scale to be applied.
X_OFF The false easting to be applied to all X coordinates, usually
selected to cause all X coordinates within the coordinate
system to be positive values of reasonable size. This is the X
coordinate of the coordinate system origin.
Y_OFF The false northing to be applied to all Y coordinates.This is
the Y coordinate of the coordinate system origin.
Parameter Name Description
8-25 FME Reference Manual Version 2.0
Safe Software Inc. COORDINATE SYSTEM SUPPORT
8.6 Datums
Table 8-6 lists the predefined datums which can be used in coordinate system
definitions. Note that each coordinate system definition must specify either a datum
or an ellipsoid.
Table 8-6 Predefined Datums
Datum Name Description
ADINDAN Adindan, Mean (Ethiopia & Sudan)
AFGOOYE Afgooye (Somalia)
AINELABD AIN el ADB 1970, Bahrain Island
ANNA65 ANNA 1 Astro 1965, Cocos Islands
ADOS714 Astro DOS 71/4, St. Helena Island
ARC1950 ARC 1950, Mean Value
ARC1960 ARC 1960, Mean Value
ASCENSN Ascension Island 1958, Ascension Island
ASTATN52 Astronomic Station 1952, Marcus Island
ASTRLA66 Australian Geodetic 1966, Australia & Tasmania Island
ASTRLA84 Australian Geodetic 1984, Australia & Tasmania Island
AZORES Faial, Graciosam Pico, Sao Jorge & Terceira Islands
BELGIUM Belgium
BELLEVUE Bellevue (IGN), Efate & Erromango Islands
BERMUDA Bermuda 1957, Bermuda Islands
BOGOTA Bogota Observatory (Columbia)
CAMPO Campo Inchauspe (Argentina)
CANARY Pico de las Nieves, Canary Islands
CANTON Canton Astro, 1966; Phoenix Islands
CAPE Cape, South Africa
CANAVRL Cape Canaveral, Florida & Bahama Islands
CARTHAGE Carthage, Tunisia
CH-1903 Swiss National Geodetic System (August 1990)
CHATHAM Chatham 1971, Chatham Island, New Zealand
CHAU Chau Astro, Paraguay
COORDINATE SYSTEM SUPPORT Safe Software Inc.
8-26 FME Reference Manual Version 2.0
CHILE Hito XVIII 1963, Chile, near 53 south
CORREGO Corrego Alegre, Brazil
DHDN Deutsches Hauptdreicknetz, Germany
DJAKRTA Djakarta (Batavia), Sumatra Island, Indonesia
DLX Lisboa, Portugal
DOS1968 DOS 1968, Gizo Island (New Georgia Islands)
D73 Melrica 1973, Portugal
EASTER Easter Island 1967
ED87 European 1987
EUROP50 European 1950, Mean Values
ERP50-CY European 1950, Cypress
ERP50-EG European 1950, Egypt
ERP50-GB European 1950, Great Britain Only
ERP50-IR European 1950, Iran
ERP50-UK European 1950, Great Britain & Ireland
ERP50-W European 1950, Western Europe
EUROP79 European 1979, Mean Values
GHANA-WO Ghana War Office, guesstimate using neighboring MINNA
GNDAJIKA Gandajika Base, Republic of Maldives
GD1949 Geodetic Datum of 1949, New Zealand
GUAM63 Guam 1963, Guam Island
GUX1 GUX 1 Astro, Guadalcanal Island
HJORSEY Hjorsey 1955, Iceland
HONGKONG Hong Kong 1963
HPGN High Precision GPS Network (a.k.a. HARN, NAD83/91, etc.)
INDIAN Bangladesh, India, Nepal
INDIANTV Thailand & Vietnam
IRELND65 Ireland 1965
ISTS69 ISTS 073 Astro 1969, Diego Garcia
IWOJIMA Astro Beacon E, Iwo Jima Island
Datum Name Description
8-27 FME Reference Manual Version 2.0
Safe Software Inc. COORDINATE SYSTEM SUPPORT
JHNSTN Johnston Island, 1961
KANDWALA Kandawalam, Sri Lanka
KERGUELN Kerguelen Island
KERTAU48 Kertau 1948, West Malaysia & Singapore
L-C5 L.C.5 Astro, Cayman Bra Island
LIBERIA Liberia 1964, Liberia
LUZON Philippines, excluding Mindanao Island
LUZON-MI Philippines, Mindanao Island
MADEIRA Southeast Base, Porto Santo & Madeira Islands
MAHE1971 Mahe 1971, Mahe Island
MARCO Marco Astro, Savage Islands
MASSAWA Eritrea (Ethiopia)
MERCHICH Merchich, Morocco
MIDWAY Midway Astro 1961, Midway Island
MINNA Minna, Nigeria
NAD27 North American Datum of 1927, Mean Values
NAD27-AK North American Datum of 1927, Alaska
NAD27-BA North American Datum of 1927, Bahamas
NAD27-CN North American Datum of 1927, Canada
NAD27-CZ North American Datum of 1927, Canal Zone
NAD27-CB North American Datum of 1927, Caribbean
NAD27-CA North American Datum of 1927, Central America
NAD27-CU North American Datum of 1927, Cuba
NAD27-GR North American Datum of 1927, Greenland (Hayes)
NAD27HII NAD27 with International Ellipsoids for HI UTM grid
NAD27-MX North American Datum of 1927, Mexico
NAD27-SA North American Datum of 1927, San Salvador
NAD83 North American Datum of 1983
NETHERLANDS Netherlands
NHRWN-O Nahrwan, Masirah Island (Oman)
Datum Name Description
COORDINATE SYSTEM SUPPORT Safe Software Inc.
8-28 FME Reference Manual Version 2.0
NHRWN-S Nahrwan, Saudi Arabia
NHRWN-U Nahrwan, United Arab Emirates
NAPARIMA Naparima, BWI; Trinidad & Tobago
NTF Nouvelle Triangulation Franaise, France
NTF-PM Nouvelle Triangulation Franaise, France
(Prime Meridian value of 2.33722917)
NWGL-10 NWGL 10
OBSRV66 Observatorio 1966, Corvo & Flores Islands (Azores)
OLD_EGYP Old Egyptian, Egypt
OLDHI Old Hawaiian, Mean Values
OMAN Oman
OSGB Ordinance Survey of Great Britain, 1936; Mean Value
PITCAIRN Pitcairn Astro 1967, Pitcairn Island
POTSDAM Potsdam, Germany
PRVI Puerto Rico and Virgin Islands
PSAD56 Provisional South American Datum of 1956, Mean
PSC63 Provisional Southern Chile of 1963 (~53 degrees South)
PULKOVO Pulkovo 1942, Germany
QATAR Qatar National
QORNOQ Qornoq, South Greenland
RAUENBERG Rauenberg, Germany
REUNION Reunion, Mascarene Island
ROME1940 Rome 1940, Sardinia Island
RT90 Rikets Triangulering 1990, Sweden
SA1969 South American Datum of 1969, Mean
SANTO Espirito Santo Island
SAOBRAZ Sao Miguel & Santa Maria Islands (Azores)
SAPPER Sapper Hill 1943, East Falkland Island
SCHWARZK Schwarzeck, Nambia
SINGAPR Southeast Asia, Singapore
SOROL Astro B4 Sorol Atoll, Tern Island
Datum Name Description
8-29 FME Reference Manual Version 2.0
Safe Software Inc. COORDINATE SYSTEM SUPPORT
8.6.1 Datum Definition
Certain sites may require a datum which is not predefined in the FME. In such a case,
a custom datum may be created. Datum definitions may occur in an FME mapping
file, as well as in the LocalCoordSysDefs.fme. The syntax of a datum
definition is:
DATUM_DEF <datumName> \
DESC_NM <descriptive name> \
SOURCE <source> \
ELLIPSOID <ellipsoid name> \
USE <use type> \
DELTA_X <x value> \
DELTA_Y <y value> \
DELTA_Z <z value> \
BWSCALE <bwscale> \
ROT_X <rotX> \
ROT_Y <rotY> \
ROT_Z <rotZ>
Table 8-7 Datum Definition Parameters
TAIWAN Hu-Tzu-Shan, Taiwan
TIMBALAI Timbalai 1948, Brunei and East Malaysia
TMBLI-A Timbalai 1948, Brunei and East Malaysia
TOKYO Japan, Korea, Okinawa; Mean Value
TRISTAN Tristan Astro 1968, Tristan da Cunha
VITI Viti Levu 1916, Viti Levu Island (Fiji)
WAKE Wake-Eniwetok 1960, Marshall Islands
WGS72 World Geodetic System of 1972
WGS72-BW World Geodetic System of 1972, Bursa/Wolfe Transformation
WGS84 World Geodetic System of 1984
YACARE Yacare, Uruguay
ZANDERIJ Surinam
Name Range Description Optional
<datumName> any string The name of the datum being
defined.
No
<descriptive
name>
any string A descriptive name for the
datum.
Yes
Datum Name Description
COORDINATE SYSTEM SUPPORT Safe Software Inc.
8-30 FME Reference Manual Version 2.0
8.6.2 Example Datum Definition
This mapping file fragment defines a datum with the BURSA use-type:
DATUM_DEF DHDN \
DESC_NM Deutsches Hauptdreicknetz (DHDN) \
SOURCE German Government \
ELLIPSOID BESSEL \
USE BURSA \
DELTA_X 582.00000000000 \
DELTA_Y 105.00000000000 \
DELTA_Z 414.00000000000 \
BWSCALE 8.3000000000000 \
ROT_X -1.0400000000000 \
<source> any string The individual or agency
providing the datum parameters.
Yes
<ellipsoid
name>
valid ellipsoid The ellipsoid upon which the
datum is based.
No
<use type> MOLO-
DENSKY
BURSA
MULREG
NAD27
NAD83
WGS84
WGS72
HPGN
LCLGRF
The type of approximation used
when the datum is involved in a
datum conversion.
No
<x value> floating point
value
The X component of the vector
from the geocenter of the datum
being defined to the geocenter of
the WGS-84 datum.
No
<y value> floating point
value
The Y component of the vector
from the geocenter of the datum
being defined to the geocenter of
the WGS-84 datum.
No
<x value> floating point
value
The X component of the vector
from the geocenter of the datum
being defined to the geocenter of
the WGS-84 datum.
No
<bwscale> floating point
value
The scale factor employed by
the BURSA use-type.
Used by BURSA only
<rotX> floating point
value
The X rotation factor employed
by the BURSA use-type.
Used by BURSA only
<rotY> floating point
value
The Y rotation factor employed
by the BURSA use-type.
Used by BURSA only
<rotZ> floating point
value
The Z rotation factor employed
by the BURSA use-type.
Used by BURSA only
Name Range Description Optional
8-31 FME Reference Manual Version 2.0
Safe Software Inc. COORDINATE SYSTEM SUPPORT
ROT_Y -0.35000000000000 \
ROT_Z 3.0800000000000
8.6.3 Datum Shift Issues for North American Users
The FME automatically performs a datum shift if the source and destination
coordinate systems use different datums. Within North America, this is most often a
shift between NAD27 and NAD83. To accomplish these shifts, the FME employs a
number of files residing in the Reproject subdirectory of the FME. For U.S. users,
the FME uses the freely distributable NADCON data files supplied by USGS.
Canadian users may use either version 1 or version 2 of the Canadian National
Transformation.
To use version 2 of the Canadian National Transformation, you need to obtain a
copy of the data file. Contact:
Information Services,
Geodetic Survey Division, Geomatics Canada,
615 Booth Street,
Ottawa, Ontario, K1A 0E9
(613) 995-4410,
information@geod.nrcan.gc.ca
http://www.geod.nrcan.gc.ca.
Once you have the file, copy it into the Reproject subdirectory of the FME,
and give it the name ntv2.gsb.
Note: On UNIX systems, it must be named NTV2.GSB and uppercase is
required.
WARNING: Geomatics Canada no longer supports version 1, and many
Canadian provinces do not consider it to produce valid results. If
you are in Canada and doing NAD Shifts, you should obtain the
ntv2.gsb from Geomatics Canada.
To use version 1 of the national transformation, obtain the grid file and copy it
into the Reproject subdirectory, and give it the name grid11.dac.
Note: On UNIX systems, it must be named GRID11.DAC and uppercase is
required.
If both versions of the Canadian National Transformation are present, the FME will
use version 2. If neither are present, the FME will issue a warning and use an
approximation of the transformation.
COORDINATE SYSTEM SUPPORT Safe Software Inc.
8-32 FME Reference Manual Version 2.0
8.7 Predefined Ellipsoids
Table 8-8 lists the predefined ellipsoids that can be used in coordinate system and
datum definitions. Note that each coordinate system definition must specify either a
datum or ellipsoid.
Table 8-8 Predefined Ellipsoids
Ellipsoid Name Description
APL4-5 A.P.L./4.5
AIRY30 Airy - 1830
AIRY49 Airy - 1848
AIRY-MOD Airy - Modified
AUSSIE52 Australian - AIG - 1952
AUSSIE Australian - 1965
BESSEL Bessel - 1841
BESL-MOD Bessel Modified
BESL-NMB Bessel - Nambia
BESL-TRI Bessel Triangulation - Sweden
BPCNC Sphere having volume equal to International ellipsoid
CLRK22 Clark3 1922 - IGN
CLRK58 Clarke - 1858
CLRK66 Clarke - 1866
CLRK80 Clarke - 1880
CLRK85 Clarke - 1885
CLRK-ARC Clark ARC
CLRK-IGN Institut Geographique National (France), Clarke 1880
CLRK-PAl Clarke Palestine
CLRK-RGS Clarke 1880 - RGS
CLRKS Clarke - 1866, Spherical
DANEMARK Danemark
DELA1810 Delambre, 1810
DELA-MOD Delambre Modified - Hydro
EVEREST Everest Indian - 1830
8-33 FME Reference Manual Version 2.0
Safe Software Inc. COORDINATE SYSTEM SUPPORT
EVRST-IM Everest Imperial - 1830
EVRST_MD Everest - Modified
EVRST-TM Everest - Timbalai (same as Everest Imperial)
FSHR1960 Fischer - 1960 (Mercury)
FSHR60MOD Modified Fischer - 1960 (South Asia)
FSHR1968 Fischer - 1968
Ghana-WO Ghana Labelled War Office, given in feet, assumed IFOOT
GRS1967 Geodetic Reference System, 1967
GRS1980 Geodetic Reference System of 1980
HEIS-29 Heiskanen, 1929
HLMRT06 Helmert - 1906 (a.k.a. 1907)
HOUGH Hough
HAYFORD Hayford - 1924 (a.k.a. 1909), same as International 1924
HOLLAND Holland
INTNL International 1924
IUGG-67 IUGG Reference Ellipsoid, 1967
JEFF-48 Jeffreys, 1948
KRASOV Krassovsky - 1940/1948
MICHIGAN Michigan - based on Clarke 1866 + 800 feet
NWL-9D NWL-9D
PLESSIS Plessis, 1817
SA1969 South American 1969
SPHERE Sphere of radius 6370997
SPHERE-1 Sphere of radius 6371000.0
STRU1860 Struve, 1860
SVANBERG Svanberg
UNITE Unit ellipsoid, testing only. Eccentricity same as Clarke 66
UNITS Unit sphere, testing only
UNIT3 3.0 Unit sphere, testing only
T-BPCNC Sphere for testing Bipolar Oblique Conformal Conic
Ellipsoid Name Description
COORDINATE SYSTEM SUPPORT Safe Software Inc.
8-34 FME Reference Manual Version 2.0
8.7.1 Ellipsoid Definition
Certain sites may require an ellipsoid that is not predefined in the FME. In such a
case, a custom ellipsoid may be created. Ellipsoid definitions may occur in an FME
mapping file, as well as in the LocalCoordSysDefs.fme. The syntax of an
ellipsoid definition is:
ELLIPSOID_DEF <ellipsoidName> \
DESC_NM <descriptive name> \
SOURCE <source> \
E_RAD <equator radius> \
P_RAD <polar radius>
Table 8-9 Ellipsoid Definition Parameters
WALB Walbeck
WAR_OFC War Office, McCaw
WGS60 World Geodetic System of 1960
WGS66 World Geodetic System of 1966 / NWL 8D
WGS67 World Geodetic System of 1967, Lucerne
WGS72 World Geodetic System of 1972
WGS84 World Geodetic System of 1984
Name Range Description Optional
<ellipsoid-
Name>
any string The name of the ellipsoid being
defined.
No
<descriptive
name>
any string A descriptive name for the
ellipsoid.
Yes
<source> any string The individual or agency
providing the ellipsoid
parameters.
Yes
<equator
radius>
floating point
value
The radius of the ellipsoid in
metres at the equator.
No
<polar
radius>
floating point
value
The radius of the ellipsoid in
metres in the polar direction.
No
Ellipsoid Name Description
8-35 FME Reference Manual Version 2.0
Safe Software Inc. COORDINATE SYSTEM SUPPORT
8.7.2 Example Ellipsoid Definition
This mapping file fragment defines a sample ellipsoid:
ELLIPSOID_DEF myEllipse \
DESC_NM Safe Sample Ellipse \
SOURCE Safe Software Inc. \
E_RAD 6377340.128 \
P_RAD 63356034.448
COORDINATE SYSTEM SUPPORT Safe Software Inc.
8-36 FME Reference Manual Version 2.0
9-1 FME Reference Manual Version 2.0
9
9 FME INTERFACES
9.1 Command Line Interface
While the FMEs graphical user interface is well suited for most uses, the
FME also has a flexible command line interface enabling it to be used as a
component of a batch processing environment.
Although a graphical user interface may be wrapped around the FME to
simplify its operational use, at its core the FME is a command line utility. This
makes it simple to run the FME in a batch processing mode.
The syntax of the FME command line is:
fme <mappingFile> [[+|-]<keyword> <value>]* \
[--<macroName> <value>]*
When the FME is invoked, a mapping file must be specified. All parameters
pertaining to the translation session are extracted from the mapping file. The
optional additional arguments on the command line are used to override or
supplement the contents of the mapping file.
9.1.1 Overriding Mapping File Settings
Any keyword settings in the mapping file may be overridden on the command
line simply by listing the keyword which is optionally preceded by a dash,
followed by its new value. Any values for the keyword that are already in the
mapping file will be overridden by the new value. There is no limit on the
FME INTERFACES Safe Software Inc.
9-2 FME Reference Manual Version 2.0
number of keywords that may be overridden on the command line, although some
operating systems do place a limit on command line length.
The following example sets the READER_TYPE keyword value to SAIF and the
WRITER_TYPE keyword value to SHAPE. Their initial settings in the mapping file
are ignored.
fme roadgen.fme -READER_TYPE SAIF -WRITER_TYPE SHAPE
Note that since the dashes are optional when keyword values are being overridden,
this is equivalent to the command line below:
fme roadgen.fme READER_TYPE SAIF WRITER_TYPE SHAPE
9.1.2 Extending Mapping File Settings
Any keyword settings in the mapping file may be extended on the command line by
preceding the keyword with a plus (+) sign, and listing the additional values for the
keyword. The result is the same as if the keyword and values were placed at the end
of the mapping file. This is only useful for keywords accumulating their values and
may be specified more than once in the mapping file. It is most commonly used to add
to the _IDs being read by the reader module during an FME session.
The following example adds the Lanes ID to whatever other IDs were requested for
translation in the roadgen.fme mapping file. If this mapping file originally
included a line in it stating SAIF_IDs Roads Railroads and the command line
below was used, the SAIF Reader would process the features in the Roads,
Railroads, and Lanes collections.
fme roadgen.fme +SAIF_IDs Lanes
However, if the plus sign was not used and the command line below was given
instead, then the SAIF_IDs on the command line would override those in the
mapping file, and only the Lanes collection would be processed.
fme roadgen.fme -SAIF_IDs Lanes
9.1.3 Defining Macros
Macros may also be defined on the command line. Frequently, macros are
intentionally referenced but not defined in a mapping file. When the mapping file is
used, it is assumed that the macros will be given values on the command line.
Macros are defined by preceding the macro name with two dashes on the command
line. The value for the macro follows the macro name parameter.
9-3 FME Reference Manual Version 2.0
Safe Software Inc. FME INTERFACES
Macros specified on the command line provide only an initial value for the macro. If
the macro is defined anywhere in the mapping file, the mapping files definition
overrides that given on the command line.
In the following example, the roadgen.fme file contains the line:
SAIF_DATASET $(saifFile)
However, the saifFile macro is not defined anywhere in this mapping file. A
value for the macro must be provided on the command line:
fme roadgen.fme --saifFile /usr/data/92j013.zip
9.1.4 Automated Mapping File Generation
The FME can also be requested to generate a mapping file through its command line
interface. To generate a mapping file, the FME is invoked in the following manner:
fme Generate <readerType> <writerType> \
<sourceDataset> <outputMappingFileName>
TIP: It is usually easier to customize a mapping file generated by the FME than to build a mapping file from
scratch.
The generated mapping file may then be edited and customized for the particular
translation. For example,
fme Generate SHAPE MIF /usr/shapedata/92b034 /tmp/s2m.fme
would generate a mapping file in /tmp/s2m.fme which could be used to translate
all the shape files in the /usr/shapedata/92b034 directory to MapInfo MID/
MIF.
9.2 FME Configurable User Interface
The previous sections have described the syntax of the FME mapping files, and the
configuration of the FME itself. This subsection describes the configurable user
interface that ships with the FME.
There are two types of FME users. One type prepares FME mapping files, tuning
them for the data model of the organization. The other uses pre-made FME mapping
files, supplying a few parameters, such as a filename or directory, to perform a
translation. This second type of user is able to harness the full power of the FME
without understanding its detailed workings.
To accommodate this second type of user, a mapping file may specify that the user be
prompted for some missing parameters when the mapping file is run. The original
FME INTERFACES Safe Software Inc.
9-4 FME Reference Manual Version 2.0
author of the mapping file simply leaves some macros undefined, and places some
instructions in the mapping file indicating the prompts to use when the end user is
queried for the macro values. The mapping file is then distributed to users along with
the FME as a data translation application.
The FME user interface does not understand the full mapping file syntax. In
particular, it does not understand line continuation, macros, comments, include
directives, or quotation marks.
9.2.1 User Interface Directives
The previous subsection discussed the user interface presented to end-users after a
mapping file has been completed. This subsection describes the few statements used
to configure the FME user interface. All user interface mapping file lines start with
the Graphical User Interface (GUI) keyword.
9.2.2 Dialog Box Title
The title of the dialog box
1
is specified with a line that looks like:
GUI TITLE Title Goes Here
Note that no quotation marks are necessary. For example:
GUI TITLE TRIM SAIF To ESRI Shape Road Generalization
causes the dialog box to have the title TRIM SAIF To ESRI Shape Road
Generalization.
9.2.2.1 Filename Parameters
Filenames are requested with a line that looks like:
GUI FILENAME <macroName> <filter> <heading>
This causes the FME user interface to interact with the user to get a filename and to
define the macro named by <macroName>. All occurrences of the macro in the
mapping file are replaced by the users input.
The filter is a standard MS-Windows filter, which follows the syntax:
<description>|<filter>[|<description>|<filter>]*
1. The dialog box title should describe the processing the mapping file will perform.
9-5 FME Reference Manual Version 2.0
Safe Software Inc. FME INTERFACES
For example:
GUI FILENAME saifFile SAIF_Files(*.saf)|*.saf Original SAIF File:
requests a dialog box entry with the caption Original SAIF File that accepts
filenames. After the user dismisses the dialog box, the macro saifFile is set to the
filename that was input.
The above two GUI statements result in the following dialog box being displayed.
9.2.2.2 Directory Parameters
Directory names are requested with a line that looks like:
GUI DIRNAME <macroName> <heading>
For example:
GUI DIRNAME shapeName Destination Shape Directory:
requests a dialog box entry with the caption Destination Shape Directory that
accepts directory names. After the user dismisses the dialog box, the macro
shapeName is set to the directory that was input.
The complete dialog box now appears as:
FME INTERFACES Safe Software Inc.
9-6 FME Reference Manual Version 2.0
9.2.2.3 Integers Parameters
Integers are requested with a line that looks like:
GUI INTEGER <macroName> <heading>
For example:
GUI INTEGER tolerance Deveau Tolerance:
requests a dialog box entry with the caption Deveau Tolerance that accepts only
integers. After the user dismisses the dialog box, the macro tolerance is set to the
integer that was input.
There is no ability to restrict the range of the integer.
The final dialog box which results from the above entries is shown below.
9.2.2.4 Floating Point Parameters
Floating point numbers are requested with a line that looks like:
GUI FLOAT <macroName> <heading>
For example:
GUI FLOAT tolerance Deveau Tolerance:
requests a dialog box entry with the caption Deveau Tolerance that accepts only
floating points. After the user dismisses the dialog box, the macro tolerance is set
to the floating point value that was input.
There is no ability to restrict the range of the floating point number.
9-7 FME Reference Manual Version 2.0
Safe Software Inc. FME INTERFACES
9.2.2.5 Text Parameters
Text parameters are requested with a line that looks like:
GUI TEXT <macroName> <heading>
For example:
GUI TEXT mapid Mapsheet Identifier
requests a dialog box entry with the caption Mapsheet Identifier that accepts only
text parameters. After the user dismisses the dialog box, the macro mapid is set to
the text that was input.
9.2.2.6 Password Parameters
Passwords, or other text that is not to be displayed when entered, are requested with
a line that looks like:
GUI PASSWORD <macroName> <heading>
For example:
GUI PASSWORD passw Password:
requests a dialog box entry with the caption Password that accepts text characters.
As each character is entered, the PASSWORD field displays an * to keep the contents
of the field from displaying. After the user dismisses the dialog box, the macro
passw is set to their input.
Using these simple GUI mapping file commands enables graphical user interfaces to
be easily constructed. This greatly simplifies the task of using the FME for
operational data translation.
FME INTERFACES Safe Software Inc.
9-8 FME Reference Manual Version 2.0
10-1 FME Reference Manual Version 2.0
10
10 AUTOCAD DWG/DXF READER/
WRITER
The AutoCAD reader and writer modules provide the Feature Manipulation
Engine (FME) with the capability to read and write files used by AutoCAD
and compatible systems. AutoCAD drawing files consist of drawing settings
and configuration, as well as a series of entities, or graphic elements,
organized into layers. The FME provides broad support for many AutoCAD
entity types and options. In addition, when AutoCAD data is output, header
information may be copied from a supplied template, or prototype, file.
This section assumes familiarity with AutoCAD compatible systems and the
entities (features) which are manipulated within these systems.
TIP: Throughout this section, the AutoCAD file will be referred to as a drawing file rather than a DXF
or DWG file.
10.1 Overview
There are two formats used by AutoCAD: DXF (drawing exchange format)
files are large, and ASCII representations of the binary DWG (drawing) files.
Logically, both files are identical, and therefore the FME treats both file types
in the same manner exactly.
AutoCAD files consist of four sections, as follows:
1. HEADER: This contains settings of variables associated with the
drawing.
AUTOCAD DWG/DXF READER/WRITER Safe Software Inc.
10-2 FME Reference Manual Version 2.0
2. TABLES: This contains a variety of tables including the following.
Layers: Each layer entry contains layer definition information such as layer
color, layer name, and layer line type.
Linetypes: Each linetype entry contains the linetype definition information
such as name, and alignment. The AutoCAD writer enables line type
definitions to be copied from an existing AutoCAD file and then referenced
by name during the data translation.
Shape Files: Each shape file entry identifies a shape file referenced by the
drawing. Shape files are used by AutoCAD as a different method for
defining symbols or fonts.
TIP: AutoCAD shape files are not the same thing as ESRI Shape files. AutoCAD shape files
store symbol and font definitions.
Applications: Each Application entry contains the name of an application
referenced within the AutoCAD file.
3. BLOCKS: These are used to define symbols and other drawing file objects
which are used repeatedly throughout a drawing. The AutoCAD writer enables
block definitions to be copied from an existing AutoCAD file and then
referenced by name during a data translation operation.
4. ENTITIES: This is the main section of a drawing file and contains the actual
feature entities. Each entity contains standard information, such as its color,
layer, thickness, linestyle, and geometry, as well as a number of attributes
specific to its entity type. For example, a text entity has fields for font, size, and
the text string in addition to the standard display attributes.
TIP: The FME supports both 2D and 3D AutoCAD entities. However, many applications only support 2D
DWG and DXF files. The @Force2D function can be used to ensure that only 2D data is written to an
output DWG or DXF file.
Each entity may also have associated attribution which is stored within an extended
entity data section. Extended entity data is fully supported by the FME.
All coordinates within a drawing file are stored as 64 bit floating point values in world
coordinates. As such there is no need to scale or otherwise alter coordinates as they
are being read from or written to a drawing file.
The AutoCAD reader and writer use symbolic names for the different entity types
stored within a drawing file. This simplifies feature type specification. The following
table gives a brief description of each of the different AutoCAD entity types currently
supported by the reader and writer. The entities are described in detail in the
subsequent sections.
10-3 FME Reference Manual Version 2.0
Safe Software Inc. AUTOCAD DWG/DXF READER/WRITER
Table 10-1 AutoCAD Entity Types and Descriptions
10.2 Reader Overview
The AutoCAD reader first reads the header and table information from the drawing
file being processed, and caches information on blocks, shape files, layers, line types,
and applications. These cached values are referenced by entities throughout the file
and are needed when processing the entities.
The reader then extracts entities, one at a time, from the entity section of the drawing
file and passes them on to the rest of the FME for processing. Complex entities such
as polylines and inserts are extracted as single FME features. If the entity has
attribution stored as extended entity data then this is also read and placed in the
feature.
When the AutoCAD reader encounters an entity types it does not know how to
process, it simply sets the entity type of the feature and returns it. This feature will
then be logged by the FME correlation subsystem. The reader then moves on to the
next entity.
FME autocad_entity Description
autocad_line Linear features stored within drawing file as a line or
unclosed polyline.
autocad_point Point features.
autocad_xline Linear features of type xline.
autocad_ellipse Features with an elliptical or circular representation.
autocad_shape Features whose representation is stored in an AutoCAD
shape file.
autocad_polygon Features whose geometry is represented by a closed
polyline.
autocad_face Features represented by a 3D face object. The face
object may have 3 or 4 coordinates.
autocad_arc Features whose geometry represents a portion of a
circular arc.
autocad_trace Features with a 4 coordinate trace geometry.
autocad_solid Features with a 3 or 4 coordinate solid geometry.
autocad_ray Features with a linear geometry which represents a ray.
autocad_text Text features.
autocad_insert Point features which carry insert entity data.
AUTOCAD DWG/DXF READER/WRITER Safe Software Inc.
10-4 FME Reference Manual Version 2.0
10.2.1 Reader Keywords
The AutoCAD reader processes several keywords in the mapping file, as shown in
the following table. These are all prefixed by the current <ReaderKeyword>_.
TIP: The AutoCAD reader automatically determines whether the file is DWG or DXF and processes it
accordingly. The same mapping file can thus be used to read either DXF or DWG.
10.2.2 Block Resolution
When the reader resolves blocks, it outputs the following:
a feature which represents the insert entity,
a feature for each of the autocad entities which are part of the block definition.
Each feature is given an attribute autocad_block_number which is set to the
same value for each block so that the features may be processed or combined in
subsequent processing. Arbitrarily deep block nesting is permitted, however the
autocad_block_number attribute is only updated for each block at the
outermost level.
10.3 Writer Overview
The AutoCAD writer provides the following capabilities when writing AutoCAD
files.
User Defined Line Types: New line types can be defined on FME mapping file
lines. These line types can then be referenced by features being written to the
AutoCAD file.
User Defined Layers: Users must define the layers into which features are
stored. The layers can also define the attributes which are to be stored within the
feature.
Keyword Suffix Value Required/
Optional
DATASET The dataset into which feature data is to be written. Required
RESOLVE_BLOCKS Specifies whether the reader should resolve the
block entities when processing inserts or if it
should just treat inserts as a point feature. See the
description below for details.
Value: yes | no. The default value is no.
Optional
10-5 FME Reference Manual Version 2.0
Safe Software Inc. AUTOCAD DWG/DXF READER/WRITER
Copy Block Definitions: Often users have existing AutoCAD drawing files
which contain block definitions which they want the translated data to carry.
Specifying the TEMPLATEFILE keyword in the mapping file results in block
definitions being copied from the existing file to the output DWG/DXF file.
These blocks can then be referred to by insert entities.
Copy Line Types: Predefined line types within existing DWG/DXF files are
copied making them available for use by features being written to the destination
file. Specifying the TEMPLATEFILE keyword in the mapping file results in the
pre-defined line types being copied from the template file to the output drawing
file. Feature entities can then refer to these line type definitions.
Copy Layer Definitions: Layer definitions within an existing DWG/DXF file
identified by TEMPLATEFILE enables layer definitions to be copied to the
destination dataset and then referenced.
Copy Shape Header Definitions: Shape header definitions are also copied from
the file specified by the TEMPLATEFILE directive.
Automatic Block Creation: When a feature is passed to the writer which cannot
be written as a single autocad entity (such as a donut polygon) the writer
automatically defines an autocad block and insert entities necessary to represent
the feature.
Flexible Attribute Support: Attribute information is by default written to
extended entity data for each feature written to the dataset. This can be
overridden however, through the use of the autocad_attributes
attribute being set as shown below.
Multi-version Support: Currently the AutoCAD DWG/DXF writer enables
files to be written which are either Release 11, Release 12, or Release 13
compatible.
autocad_attributes value Description
extended_entity_data This is the default value and results in the
attribution being written to the extended entity
for the feature.
insert_attributes This results in the writer creating an insert entity
for each feature and storing all attributes with
the insert entity. The insert entity refers to a
block which contains the geometry of the output
feature.
external_attributes No attributes are written to the AutoCAD file.
This is useful if the attributes are being stored in
an external database or if attribute information
is not wanted.
AUTOCAD DWG/DXF READER/WRITER Safe Software Inc.
10-6 FME Reference Manual Version 2.0
When creating AutoCAD files the AutoCAD writer first defines the line types and
layers which are defined within the FME mapping file. The writer then reads in a
template file, if specified, and copies the line types, layer definitions, shape file
header information, and block information from the template file to the output
dataset.
The AutoCAD writer then outputs each feature it is given to the output file in the
appropriate entity type.
When writing an AutoCAD file, the format of file output is determined as follows:
If the filename contains .dwg or .DWG then the output dataset is written in
the DWG format.
Otherwise if the filename contains .dxf or .DXF then the output dataset is
written in DXF format.
Otherwise if the specified writer type is DWG then the output dataset is written
in the DWG format.
Otherwise if the specified writer type is DXF then the output dataset is written in
the DXF format.
Otherwise if an error exists in the mapping file and the translation is halted.
The AutoCAD writer uses the above rules in order to enable the same FME
mapping file to be used to create both DXF and DWG output files. Users are able
to specify which they want simply by changing the suffix of the output file which
is being produced.
10.3.1 Writer Keywords
The AutoCAD writer processes several keywords in the mapping file, as shown in the
following table. These are all prefixed by the current <WriterKeyword>_.
Keyword Suffix Value Required/
Optional
DATASET The dataset into which feature data is to be
written.
Required
10-7 FME Reference Manual Version 2.0
Safe Software Inc. AUTOCAD DWG/DXF READER/WRITER
10.3.2 DATASET
This keyword operates as explained above for the AutoCAD reader.
10.3.3 VERSION
This statement specifies the version of AutoCAD file which is to be output. The
statement is of the following form
<WriterKeyword>_VERSION <autocad version>
The example statement below instructs the AutoCAD writer to produce a release 12
AutoCAD file:
DWG_VERSION Release12
10.3.4 TEMPLATEFILE
This statement specifies the name of the existing AutoCAD DXF or DWG file which
contains linetype, layer, shape header, and block definitions which are to be copied
to the destination AutoCAD file. This is an optional parameter. If the parameter is not
defined then the output file uses the line type defined in the mapping file along with
the predefined type of CONTINUOUS which is always present in an AutoCAD
drawing.
TIP: LINETYPE definitions found in the mapping file override any line type definitions found in the
template file. This can be used to change linetype definitions during translations both the reader and writer
are AutoCAD files.
VERSION The version of AutoCAD file which is to be
produced. Values currently supported are:
Release11: Release 11 AutoCAD file is
produced.
Release12: Release 12 AutoCAD file is
produced
Release13: Release 13 AutoCAD file is
produced
Required
TEMPLATEFILE The name of an existing AutoCAD DXF or DWG
file which contains the block definitions and line
type definitions to be used when creating the
output dataset.
Optional
LINETYPE New linetypes can be created in the mapping file. Optional
Keyword Suffix Value Required/
Optional
AUTOCAD DWG/DXF READER/WRITER Safe Software Inc.
10-8 FME Reference Manual Version 2.0
The example below specifies that the file called c:\tmp\test.dwg contains the
block, layer, shape header definitions, and line type definitions for the output dataset.
DWG_TEMPLATEFILE c:/tmp/test.dwg
TIP: Many AutoCAD users refer to template files as prototype files.
10.3.5 LineType Representation
The AutoCAD writer enables line types to be defined within the FME mapping file.
This enables the user to control how output lines are to look in the destination dataset.
The LineType definition is of the following form:
<WriterKeyword>_LINETYPE <linetype name> \
autocad_textpict <picture> \
[autocad_patternLength <pattern Length> \
<segment values>+ \
]
where:
<linetype name> is the name used throughout the mapping file to refer to the
linetype being defined by this statement.
<picture> is the text or name displayed in AutoCAD when linetypes are
displayed.
<pattern Length> the length of a single instance of the line.
<segment values>: the length of each of the segments within the line type
segment. The segment values obey the following rules:
negative value pen up length (used to create spaces of varying lengths)
positive value pen down length (used to make dashes of varying lengths)
zero used to create a dot.
The following example creates a line type called dash-dot which looks appears as
__ . __ . __ . and so on when displayed on the screen.
DWG_LINETYPE dash-dot \
autocad_textpict DASHDOT \
autocad_patternLength 1.0 \
0.5 -0.25 0 -0.25
10-9 FME Reference Manual Version 2.0
Safe Software Inc. AUTOCAD DWG/DXF READER/WRITER
10.3.6 Layer Representation
The AutoCAD writer requires that every feature written to the AutoCAD file be
stored within a predefined AutoCAD layer. In AutoCAD the layers are used to store
collections of logically related attributes. Within the FME the AutoCAD layer and the
type of the feature are treated synonymously as their is a one to one correspondence
between FME Feature type and AutoCAD layer.
1
The layer statement is of the
following form:
<WriterKeyword>_DEF <layer name> \
autocad_color <default color> \
autocad_linetype <default line type> \
[<attribute name> <attribute type>]
where:
<layer name>: The name of the layer being defined. This is the name which
is used throughout the remainder of the FME mapping files.
<default color>: The color number which is used for all features stored
within the layer unless explicitly overridden on the correlation lines below. Valid
values are between 0 and 256.
<default line type>: The name of the line type to use for the layer if no
line type is specified on the correlation line. The line type specified must be
either:
defined in the mapping file,
copied from a specified template file, or
be the predefined line type named CONTINUOUS.
<attribute name> <attribute type>: The definition of an attribute
which is to be stored within the extended entity data of features for the layer. If
no attributes are defined then all feature attributes (except those which start with
autocad_ are stored. The storing of attributes can be turned off by specifying
a value of external_attributes for the autocad_attributes
feature attribute on the correlation line.
The example below defines a layer called boundary in which entities are drawn
using color 13 (unless otherwise specified), and a linetype called dash-dot (unless
otherwise specified). The feature also has several attributes specified which will be
written to the extended entity data of each feature within the layer.
1. Layers can also be defined through the use of a TEMPLATEFILE.
AUTOCAD DWG/DXF READER/WRITER Safe Software Inc.
10-10 FME Reference Manual Version 2.0
DWG_DEF boundary \
autocad_color 13 \
autocad_linetype dash-dot \
FEATCODE char(12) \
PPID char(10) \
DATECHNG date \
SURVEYDIST number(8,2)
10.4 Feature Representation
Special FME feature attributes are used to hold AutoCAD entity attributes. The
AutoCAD writer uses these attribute values as it fills in an entity structure during
output. The AutoCAD reader sets these attributes in the FME feature it creates for
each entity it reads.
The FME considers the AutoCAD layer
2
to be the FME feature type of an AutoCAD
feature. Each AutoCAD entity, regardless of its entity type, shares a number of other
attributes, as described in the following table. Subsequent sections will describe
attributes specific to each of the supported entity types.
2. The feature layer name corresponds to be the feature type and autocad_layer when reading. This
enables the layer name to be extracted without the need to use the @FeatureType function.
Attribute Name Content
autocad_layer The name of the features layer. This is the same value as the
features type and is stored when reading for reasons of
convenience. This value is ignored when entities are being
written to a drawing file.
Value: char(33)
Default: No default
autocad_color The color number of the entity. If the value is 0, then the color
of the entity is that of the enclosing block; if the value is 256,
then the color of the entity is that specified by the entitys
layer; otherwise, the number specified determines the color of
the entity.
Range: 0...256
Default: 256
autocad_linetype The name of the features linetype.
Range: char[33]
Default: BYLAYER
autocad_thickness The thickness of the entitys lines.
Range: 64 bit Real
Default: 0
10-11 FME Reference Manual Version 2.0
Safe Software Inc. AUTOCAD DWG/DXF READER/WRITER
10.4.1 Extended Entity Data
Each entity in an AutoCAD file may have associated extended entity data. This data
is typically used by applications to store attribute information. The AutoCAD reader
attempts to make extended entity data as simple to use as possible by storing it in three
different formats within the FME feature object. The first two formats merely store
the data as found in the drawing file in the feature, while the third format attempts to
present the attribute information in a more useful manner. It is important to remember
that when extended entity data is read from an AutoCAD file all three formats are
stored within a single FME feature. The format which is actually used (if any) is
dependent on the configuration of the remainder of the FME mapping file.
The AutoCAD writer understands only the interpreted format (described below) for
extended entity data. When writing extended entity data, the FME features being
output must structure their attributes in this way. That is, the attribute data is stored
with each attribute being a single extended entity string in the form <attribute
name> = <attribute value>. Storing the data in this manner enables the
data to be viewed easily by AutoCAD and read by the FME reader module.
10.4.2 List Format
In this format the data is simply stored in a list as found in the AutoCAD file. The data
is stored in a single list named extended_data_list{}. Each value in the list is
of the form <attribute tag>: <attribute value>. The <attribute
tag>s supported by the FME are restricted to those given in the table below. The
<attribute tag>s define the domain for the associated <attribute
value>. Note that the AutoCAD codes associated with each kind of extended entity
data are not stored in the FME feature.
autocad_entity The FME name for the type of entity this feature represents.
Range: See Table 10-1
Default: No default
autocad_attributes Used by the writer module only. This directs the writer on
how the attributes for the feature are to be stored. If this
attribute is not specified or is specified as extended_
entity_data then the attribution associated with the
feature is written to the extended entity portion. If the value is
insert_attributes, insert entities are created for the
attributes. If the value is external_attributes then the
attribution is not written to extended entity data.
Range: extended_entity_data |
insert_attributes |
external_attributes
Default: extended_entity_data
Attribute Name Content
AUTOCAD DWG/DXF READER/WRITER Safe Software Inc.
10-12 FME Reference Manual Version 2.0
Attribute Name Content
application_name The name of the application which the following entity data is
associated. This application_name remains in effect
until another application_name entry is specified.
AutoCAD Code: 1001
Example: application_name:ACAD
autocad_layer The name of the layer the extended data is associated.
AutoCAD Code: 1003
Example: autocad_layer:Water
string A character string value from 0 to 255 characters in length.
AutoCAD Code: 1000
Example: string:Thompson
three_reals Three 64 bit real numbers separated by commas.
AutoCAD Code: 1010,1020,1030
Example: three_reals:2.3,4.5,3.4
world_position Three real numbers which represent a world position. Each of
the numbers is separated by a comma.
AutoCAD Code: 1011, 1021, 1031
Example: world_position:23.4, -123.5, 0
world_displacement Three real values which represent a world displacement
value. Each of the values is separated by a comma.
AutoCAD Code: 1012, 1022, 1032
Example: world_displacement:1.5, 2.3, 0
world_direction Three real values which represent a world direction vector.
Each of the values is separated by a comma.
AutoCAD Code: 1013,1023,1033
Example: world_direction: 30.0, -12.4, 10
real A 64 bit real number.
AutoCAD Code: 1040
Example: real:3.1415926
distance A 64 bit real number which represents a distance.
AutoCAD Code: 1041
Example: distance:4.56
scale A 64 bit real number which represents a scaling factor.
AutoCAD Code: 1042
Example: scale:34.5
16Bit_integer A 16 bit integer value.
AutoCAD Code: 1070
Example: 16Bit_integer:245
32Bit_integer A 32 bit integer value.
AutoCAD Code: 1071
Example: 32Bit_integer:12983
10-13 FME Reference Manual Version 2.0
Safe Software Inc. AUTOCAD DWG/DXF READER/WRITER
For example, if the following data was stored in extended entity data:
1001 C_NODE
1000 CONNOBJ_1=43F4
1000 COUNT=3
1000 CONNOBJ_2=43F3
1000 CONNOBJ_3=43F2
1010 45.4
1020 -123.5
1030 0
1001 DPRINT
1000 postscript
then the FME AutoCAD reader would store this information as a list within the FME
feature as shown by the in-memory snapshot below:
Notice how the AutoCAD codes are converted to attribute tags when stored in the
FME features.
10.4.3 Structure Format
In this representation of extended entity data, the fields are stored with the tags
forming part of the attribute names for each of the extended entity entries. The data
is stored in a single structure in the FME feature named extended_data. As the
extended entity data within AutoCAD is grouped into sections with each section
beginning with an application group code, the extended_data structure itself is
also divided into different sections with each section beginning with
extended_data{#}. The remainder of the attribute name consists of one of the
parameters described in the table below.
Attribute Name Attribute Value
extended_data_list{0} application_name:C_NODE
extended_data_list{1} string:CONNOBJ_1=43F4
extended_data_list{2} string:COUNT=3
extended_data_list{3} string:CONNOBJ_2=43F3
extended_data_list{4} string:CONNOBJ_3=43F2
extended_data_list{5} three_reals:45.4,-123.5,0
extended_data_list{6} application_name:DPRINT
extended_data_list{7} string:postscript
AUTOCAD DWG/DXF READER/WRITER Safe Software Inc.
10-14 FME Reference Manual Version 2.0
For example, given the following extended entity data:
1001 C_NODE
1000 CONNOBJ_1=43F4
1000 COUNT=3
1000 CONNOBJ_2=43F3
1000 CONNOBJ_3=43F2
1010 45.4
1020 -123.5
1030 0
1001 DPRINT
1000 postscript
the information will be stored in the FME feature using structure notation as follows:
Extended Entity Parameter Contents
application_name The name of the application which the entity data is
associated.
AutoCAD Code: 1001
autocad_layer{#} The name of the layer the extended data is associated.
AutoCAD Code: 1003
string{#} A character string value from 0 to 255 characters in length.
AutoCAD Code: 1000
three_reals{#}.real1
three_reals{#}.real2
three_reals{#}.real3
Three real numbers.
AutoCAD Code: 1010,1020,1030
world_position{#}.x
world_position{#}.y
world_position{#}.z
Three values represent the x, y, and z components of a
world_position value.
AutoCAD Code: 1011, 1021, 1031
world_displacement{#}.x
world_displacement{#}.y
world_displacement{#}.z
Three values which represent a world displacement value.
AutoCAD Code: 1012, 1022, 1032
world_direction{#}.x
world_direction{#}.y
world_direction{#}.z
Three real values which represent a world direction vector.
AutoCAD Code: 1013,1023,1033
real{#} A 64 bit real number.
AutoCAD Code: 1040
distance{#} A 64 bit real number which represents a distance.
AutoCAD Code: 1041
scale{#} A 64 bit real number which represents a scaling factor.
AutoCAD Code: 1042
16Bit_integer{#} A 16 bit integer value.
AutoCAD Code: 1070
32Bit_integer{#} A 32 bit integer value.
AutoCAD Code: 1071
10-15 FME Reference Manual Version 2.0
Safe Software Inc. AUTOCAD DWG/DXF READER/WRITER
Notice how in this case the AutoCAD codes are used to form extensions for the
attribute names. Also notice how the extended_data items are grouped in the
FME feature as they are within the drawing file.
10.4.4 Interpreted Format
Finally, the FME AutoCAD reader module also attempts to interpret any string held
in the extended entity data. If it is successful in interpreting any data then it stores it
as attributes within the feature. As it is reading each extended entity string entry it
attempts to determine if the value is composed of an attribute name/value pair and if
it does it stores the information as such. For example, if the extended entity data from
the previous example were read, the following interpreted values would be stored
within the FME feature.
The reader is able to do this by recognizing the = divider within each of the string
attributes as the separator between an encoded attribute name and attribute value. The
reader also recognizes a space character as a separator.
The remaining sections discuss the representation of each supported AutoCAD entity
type.
Attribute Name Attribute Value
extended_data{0}.application_name C_NODE
extended_data{0}.string{0} CONNOBJ_1=43F4
extended_data{0}.string{1} COUNT=3
extended_data{0}.string{2} CONNOBJ_2=43F3
extended_data{0}.string(3} CONNOBJ_3=43F2
extended_data{0}.three_reals{0}.real1 45.4
extended_data{0}.three_reals{0}.real2 -123.5
extended_data{0}.three_reals{0}.real3 0
extended_data{1}.application_name DPRINT
extended_data{1}.string{0} postscript
Attribute Name Attribute Value
CONNOBJ_1 43F4
COUNT 3
CONNOBJ_2 43F3
CONNOBJ_3 43F2
AUTOCAD DWG/DXF READER/WRITER Safe Software Inc.
10-16 FME Reference Manual Version 2.0
10.4.5 Lines
autocad_entity: autocad_line
Features with autocad_entity set to autocad_line are stored in and read
from drawing files in one of two ways, depending on the number of coordinates they
have.
.
10.4.6 XLines
autocad_entity: autocad_xline
Features with autocad_entity set to autocad_xline are stored in and read
from drawing files as an FME feature with two coordinates, representing a line. The
reader and writer modules automatically convert the xline to and from its unit vector
representation into a line.
There are no attributes specific to this type of entity.
10.4.7 Points
autocad_entity: autocad_point
Features with autocad_entity set to autocad_point are stored in and read
from drawing files as a single coordinate feature.
There are no attributes specific to this type of entity.
Number of
Coordinates
AutoCAD
Entity Type
Description
2 line If the feature contained exactly two points, then an
AutoCAD line entity is used to store the data.
Greater than 2 polyline If the number of coordinates is greater than 2, then
the AutoCAD polyline entity is used to store the
coordinates. The polyline closed flag is set to
indicate that the polyline entity is not closed.
Attribute Name Content
autocad_bulge Comma separated value list of the vertex bulges. This is only
useful when performing AutoCAD to AutoCAD translation
and is a measurement of the curvature at each vertex.
10-17 FME Reference Manual Version 2.0
Safe Software Inc. AUTOCAD DWG/DXF READER/WRITER
10.4.8 Ellipses
autocad_entity: autocad_ellipse
Ellipse features are point features used to represent both AutoCAD circle and
AutoCAD ellipse entities. The point serves as the center of the ellipse. Ellipse entities
with an autocad_primary_axis equal to the autocad_secondary_axis
are stored within the drawing file as a circle entity. Additional attributes specify the
rotation, major axis, and minor axis of the ellipse.
TIP: The function @Arc() can be used to convert an ellipse to a polygon. This is useful for representing
ellipses in systems which do not support them directly.
10.4.9 Shapes
autocad_entity: autocad_shape
Features with autocad_entity set to autocad_shape are point features
which identify where to place an AutoCAD shape object. The reader and writer
modules process all the attributes needed to fully specify the shape object reference.
TIP: When an AutoCAD file is output, any shape files it references must be shipped together with the file.
Attribute Name Content
autocad_primary_axis The length of the semi-major axis in ground units.
Range: Any real number > 0
Default: No default
autocad_secondary_axis The length of the semi-minor axis in ground units.
Range: Any real number > 0
Default: No default
autocad_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
AUTOCAD DWG/DXF READER/WRITER Safe Software Inc.
10-18 FME Reference Manual Version 2.0
Attribute Name Contents
autocad_scale The scale of the shape object for this point.
Range: Any real number.
Default: 1
autocad_shape_index This identifies the index of the particular shape
within the shape file. A single shape file may contain
many different shapes.
Range: Any real number > 0
Default: No default
autocad_rotation The rotation of the shape for this entity.
Range: -360.0..360.0
Default: 0
autocad_width_factor The width factor for the shape.
Range: Any real number > 0
Default: 0
autocad_oblique The oblique angle of the shape.
Range: -360.0 ..360.0
Default: 0
auotocad_big_fontname The name of the file which contains fonts for large
character sets.
Range: char[65]
Default: NULL
autocad_shape_name The name of the shape which is being read or written.
Range: char[33]
Default: No default
autocad_shape_filename The name of the file in which the shape is defined.
Range: char[65];
Default: No default
autocad_shape_rotation The rotation of the shape definition relative to the
shape file specification.
Range: Any real number
Default: 0
autocad_shape_height The height of the shape.
Range: Any real number
Default: 0
autocad_shape_width The width of the shape.
Range: Any real number
Default: 1
10-19 FME Reference Manual Version 2.0
Safe Software Inc. AUTOCAD DWG/DXF READER/WRITER
10.4.10 Polygons
autocad_entity: autocad_polygon
Features with autocad_entity set to autocad_polygon are stored in and
read from drawing files as closed polyline entities.
There are no attributes specific to this type of entity.
10.4.11 Faces
autocad_entity: autocad_face
Features with autocad_entity set to autocad_face are stored as AutoCAD
face entities. Additional attributes are used to define the visibility of the edges of the
Face entity. Within the FME they are stored as four sided (five vertex) polygons.
10.4.12 Arcs
autocad_entity: autocad_arc
This geometry type is stored in an AutoCAD arc entity. Arc features are just like
ellipse features, only two additional angles control the portion of the ellipse boundary
which is drawn.
TIP: The function @Arc() can be used to convert an arc to a line. This is useful for representing arcs in systems
which do not support them directly.
Attribute Name Contents
autocad_edge_1 The visibility of the first edge of the Face.
Range: visible|invisible
Default: visible
autocad_edge_2 The visibility of the second edge of the Face.
Range: visible|invisible
Default: visible
autocad_edge_3 The visibility of the third edge of the Face.
Range: visible|invisible
Default: visible
autocad_edge_4 The visibility of the final edge of the Face.
Range: visible|invisible
Default: visible
AUTOCAD DWG/DXF READER/WRITER Safe Software Inc.
10-20 FME Reference Manual Version 2.0
Attribute Name Contents
autocad_primary_axis The length of the semi-major axis in ground units.
Currently the value of the primary axis is always
equal to the value of the secondary axis as
AutoCAD arcs must be circular. When writing to
an AutoCAD file only the primary axis value is
used.
Range: Any real number > 0
Default: No default
autocad_secondary_axis The length of the semi-minor axis in ground units.
Currently the value of the primary axis is always
equal to the value of the secondary axis as
AutoCAD arcs must be circular. When writing to
an AutoCAD file only the primary axis value is
used.
Range: Any real number > 0
Default: No default
autocad_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
autocad_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
autocad_rotation The rotation of the major axis. The rotation is
measured in degrees counter clockwise up from
horizontal. This value is fixed at 0 as AutoCAD
doesnt support rotation of arcs at this time.
Range: 0
Default: 0
Secondary
Axis
Rotation = 0
Start
Angle
= 135
Sweep
Angle
= 135
Primary
Axis
rotation
10-21 FME Reference Manual Version 2.0
Safe Software Inc. AUTOCAD DWG/DXF READER/WRITER
10.4.13 Traces
autocad_entity: autocad_trace
Features with autocad_entity set to autocad_trace are stored in and read
from drawing files as a 4 coordinate AutoCAD trace entity.
There are no attributes specific to this type of entity.
10.4.14 Solids
autocad_entity: autocad_solid
Features with autocad_entity set to autocad_solid are stored in and read
from drawing files as a 3 or 4 coordinate AutoCAD solid entity.
There are no attributes specific to this type of entity.
10.4.15 Rays
autocad_entity: autocad_ray
Features with autocad_entity set to autocad_ray are stored in and read from
drawing files as a two coordinate line. The reader and writer modules automatically
convert the ray to and from its unit vector representation into a line.
There are no attributes specific to this type of entity.
10.4.16 Text Entities
autocad_type: autocad_text
Features with autocad_entity set to autocad_text are stored in and read
from drawing files as text entities. A text entity is represented by a single coordinate
and the following attributes.
Attribute Name Contents
autocad_text_string The text string.
Range: char[1024]
Default: No default
autocad_rotation The rotation of the text for this entity.
Range: -360.0..360.0
Default: 0
AUTOCAD DWG/DXF READER/WRITER Safe Software Inc.
10-22 FME Reference Manual Version 2.0
a. AutoCAD shape files should not be confused with ESRI Shape files. The former hold font
and symbol definitions; the latter hold spatial features.
autocad_text_size The text height.
Range: Any real number > 0
Default: 10
autocad_oblique The oblique angle of the shape.
Range: -360.0 ..360.0
Default: 0
auotocad_big_fontname The name of the file which contains fonts for large character
sets.
Range: char[65]
Default: NULL
autocad_shape_name The name of the shape which contains the text font definition.
Range: char[33]
Default: STANDARD
autocad_shape_filename The name of the file which contains the text font
a
definition.
Range: char[65];
Default: txt
autocad_shape_rotation The angle for the text as defined in shape file.
Range: Any real number
Default: 0
autocad_shape_height The height of the text as defined in shape file.
Range: Any real number
Default: 0
autocad_shape_width The width of the text as defined in shape file.
Range: Any real number
Default: 1
autocad_generation The generation of the text entry.
Range: autocad_normal |
autocad_upside_down |
autocad_backwards |
autocad_upsidedown_backwards
Default: autocad_normal
autocad_justification The justification of the text relative to its insert point.
Range: autocad_top_left |
autocad_top_center |
autocad_top_right|
autocad_middle_left |
autocad_middle_center |
autocad_middle_right|
autocad_bottom_left |
autocad_bottom_center |
autocad_bottom_right|
Default: autocad_bottom_left
Attribute Name Contents
10-23 FME Reference Manual Version 2.0
Safe Software Inc. AUTOCAD DWG/DXF READER/WRITER
10.4.17 Inserts
autocad_entity: autocad_insert
Inserts are point features used in AutoCAD to specify block locations and associated
attribution. Inserts are another way in which attribution is stored within an AutoCAD
drawing file. The features returned from the AutoCAD reader encapsulate all the
information from the AutoCAD insert entity and all attribute entities which are
associated with the insert entity. Apart from the user defined attributes specified
within it, each insert entity also has the following attributes.
Attribute Name Contents
autocad_xscale The scale factor for the inserted block in the x direction.
Range: Any real number.
Default: 1
autocad_yscale The scale factor for the inserted block in the y direction.
Range: Any real number
Default: 1
autocad_zscale The scale factor for the inserted block in the z direction.
Range: Any real number.
Default: 1
autocad_rotation The rotation of the inserted block, counterclockwise from
horizontal.
Range: -360.0 ..360.0
Default: 0
auotocad_number_columns The column count for the insert.
Range: 0..65536
Default: 1
autocad_number_rows The row count for the insert.
Range: 0..65536
Default: 1
autocad_column_distance The column spacing for the insert.
Range: Any real number > 0
Default: 0
autocad_row_distance The row spacing for the insert.
Range: Any real number > 0
Default: 0
autocad_block_name The name of the block entity which is to be inserted.
Range: char[33]
Default: No Default
rotation
AUTOCAD DWG/DXF READER/WRITER Safe Software Inc.
10-24 FME Reference Manual Version 2.0
10.5 AutoCAD Mapping File Example 1
The mapping file below performs generic translation from AutoCAD to ESRI Shape
files. Each AutoCAD entity type is stored in a separate Shape/DBF pair and retains
all of the standard attribution for each of the different entities.
# Generic autocad to Shape file translation
# This mapping file configures the FME to copy the contents
# of an autocad Design File into shape files.
# Each entity type will be output into its own shape file,
# and the attributes in the shape file are the attributes from the
# autocad entities.
# In this mapping file, NO autocad extended entity attributes or
# insert attributes are preserved, though they very easily could
# be if that were desired.
#
GUI TITLE Generic AutoCAD to Shape File Translation
# --------------------------------------------------------------
# First set up the reader and writer the FME will use. While we do
# specify the reader_type as DWG the same mapping file can also be
# used to process DXF files. To process a DXF file the user simply
# selects a DXF file as the input dataset from the FME GUI. The
# FME reader automatically detects that it is a DXF file and
# processes it accordingly.
READER_TYPE DWG
WRITER_TYPE SHAPE
# --------------------------------------------------------------
# Now identify the input and output datasets (the GUI will supply
# the macro values).
autocad_attributes_follow Indicates if attributes are also to be stored with the insert
entity. This must be specified if feature attributes are to be
written to the AutoCAD output file.
Range: true | false
Default: true
autocad_attribute_display Indicates if the attribute values are to be visible or
invisible.
Range: visible | invisible
Default:invisible
autocad_<attr_name>_x
autocad_<attr_name>_y
Used when attributes are associated with the insert
elements enabling the location of the attributes to be
specified for display purposes.
Range: any 64 bit floating point value
Default: x and y value of insert coordinate
Attribute Name Contents
10-25 FME Reference Manual Version 2.0
Safe Software Inc. AUTOCAD DWG/DXF READER/WRITER
GUI FILENAME autocadFile
DXF_FILES(*.dxf)|*.dxf|All_files(*.*)|*.*
Original autocad File:
DWG_DATASET $(autocadFile)
GUI DIRNAME ShapeDir Output Shape Directory:
SHAPE_DATASET $(ShapeDir)
# ---------------------------------------------------------------
# Define macros used by all the entity type definitions.
# This keeps us from retyping this for each entity type.
MACRO StandardAutocadAttrs \
autocad_layer %layer \
autocad_linetype %linetype \
autocad_thickness %thickness \
autocad_color %color
MACRO autocadinShapeAttrs \
LAYER %layer \
NOTE: MACROs reduce the size of the mapping file.
LINETYPE %linetype \
THICKNESS %thickness \
COLOR %color
MACRO autocadinShapeAttrDefs \
LAYER char(33) \
LINETYPE char(33) \
COLOR number(4,0) \
THICKNESS number(4,0)
# ---------------------------------------------------------------
# Now for each autocad entity type, write the transformation
# specification for it into SHAPE. Define # the Shape file
# which will hold them.
# ---------------------------------------------------------------
# autocad Line entities
DWG * autocad_entity autocad_line \
$(StandardAutocadAttrs) \
elevation %elevation:0
SHAPE line \
$(autocadinShapeAttrs) \
ELEVATION %elevation
SHAPE_DEF line SHAPE_GEOMETRY shape_arc \
$(autocadinShapeAttrDefs) \
ELEVATION number(14,6)
# ---------------------------------------------------------------
# autocad Points
DWG * autocad_entity autocad_point \
$(StandardAutocadAttrs)
SHAPE points \
$(autocadinShapeAttrs)
SHAPE_DEF points SHAPE_GEOMETRY shape_point \
$(autocadinShapeAttrDefs)
AUTOCAD DWG/DXF READER/WRITER Safe Software Inc.
10-26 FME Reference Manual Version 2.0
# ---------------------------------------------------------------
# autocad ellipse
DWG * autocad_entity autocad_ellipse \
$(StandardAutocadAttrs) \
autocad_primary_axis %primary \
autocad_secondary_axis %secondary \
autocad_rotation %rotation
SHAPE ellipse \
$(autocadinShapeAttrs) \
PRIM_AXIS %primary \
SEC_AXIS %secondary \
ROTATION %rotation
SHAPE_DEF ellipse SHAPE_GEOMETRY shape_point \
$(autocadinShapeAttrDefs) \
PRIM_AXIS number(14,6) \
SEC_AXIS number(14,6) \
ROTATION number(14,6)
# ---------------------------------------------------------------
# autocad Shapes
DWG * autocad_entity autocad_shape \
$(StandardAutocadAttrs) \
autocad_scale %scale \
autocad_shape_index %index \
autocad_width_factor %factor \
autocad_oblique %oblique \
autocad_rotation %rotation \
autocad_big_fontname %fontname \
autocad_shape_name %shapename \
autocad_shape_filename %filename \
autocad_shape_rotation %shaperotation \
autocad_shape_height %height \
autocad_shape_width %width
SHAPE shapes \
$(autocadinShapeAttrs) \
SCALE %scale \
SHAPEINDEX %index \
WFACTOR %factor \
OBLIQUE %oblique \
ROTATION %rotation \
BFONTNAME %fontname \
SHAPENAME %shapename \
FILENAME %filename \
ROTATION %shaperotation \
HEIGHT %height \
WIDTH %width
SHAPE_DEF shapes SHAPE_GEOMETRY shape_point \
$(autocadinShapeAttrDefs) \
SCALE number(14,6) \
SHAPEINDEX number(4,0) \
WFACTOR number(14,6) \
OBLIQUE number(14,6) \
ROTATION number(14,6) \
BFONTNAME char(65) \
SHAPENAME char(33) \
10-27 FME Reference Manual Version 2.0
Safe Software Inc. AUTOCAD DWG/DXF READER/WRITER
FILENAME char(65) \
ROTATION number(14,6) \
HEIGHT number(14,6) \
WIDTH number(14,6)
#---------------------------------------------------------------
# autocad Text
DWG * autocad_entity autocad_text \
$(StandardAutocadAttrs) \
autocad_text_string %text \
autocad_rotation %rotation \
autocad_text_size %height \
autocad_big_fontname %fontname \
autocad_shape_name %shapename \
autocad_shape_filename %filename \
autocad_shape_rotation %shaperotation \
autocad_shape_height %shapeheight \
autocad_shape_width %shapewidth \
autocad_justification %justification \
autocad_generation %generation
SHAPE textnode \
$(autocadinShapeAttrs) \
TEXT %text \
ROTATION %rotation \
HEIGHT %height \
BFONTNAME %fontname \
SHAPENAME %shapename \
FILENAME %filename \
SHAPEROT %shaperotation \
SHAPEHGHT %shapeheight \
SHAPEWIDTH %shapewidth \
JUSTIFY %justification \
GENERATION %generation
SHAPE_DEF textnode SHAPE_GEOMETRY shape_point \
$(autocadinShapeAttrDefs) \
TEXT char(255) \
ROTATION number(14,6) \
HEIGHT number(14,6) \
BFONTNAME char(65) \
SHAPENAME char(33) \
FILENAME char(65) \
SHAPEROT number(14,6) \
SHAPEHGHT number(14,6) \
SHAPEWIDTH number(14,6) \
JUSTIFY number(4,0) \
GENERATION char(30)
# ---------------------------------------------------------------
# autocad arcs
DWG * autocad_entity autocad_arc \
$(StandardAutocadAttrs) \
autocad_primary_axis %primary \
autocad_secondary_axis %secondary \
autocad_rotation %rotation \
autocad_start_angle %startangle \
autocad_sweep_angle %sweepangle
AUTOCAD DWG/DXF READER/WRITER Safe Software Inc.
10-28 FME Reference Manual Version 2.0
SHAPE arc \
$(autocadinShapeAttrs) \
PRIM_AXIS %primary \
SEC_AXIS %secondary \
ROTATION %rotation \
STARTANGLE %startangle \
SWEEPANGLE %sweepangle
SHAPE_DEF arc SHAPE_GEOMETRY shape_point \
$(autocadinShapeAttrDefs) \
PRIM_AXIS number(14,6) \
SEC_AXIS number(14,6) \
ROTATION number(14,6) \
STARTANGLE number(14,6) \
SWEEPANGLE number(14,6)
# ---------------------------------------------------------------
# autocad Trace entities
DWG * autocad_entity autocad_trace \
$(StandardAutocadAttrs)
SHAPE trace \
$(autocadinShapeAttrs)
SHAPE_DEF trace SHAPE_GEOMETRY shape_polygon \
$(autocadinShapeAttrDefs)
# ---------------------------------------------------------------
# autocad Solid entities
DWG * autocad_entity autocad_solid \
$(StandardAutocadAttrs)
SHAPE solid \
$(autocadinShapeAttrs)
SHAPE_DEF solid SHAPE_GEOMETRY shape_polygon \
$(autocadinShapeAttrDefs)
#---------------------------------------------------------------
# autocad Insert Entities
DWG * autocad_entity autocad_insert \
$(StandardAutocadAttrs) \
autocad_xscale %xscale \
autocad_yscale %yscale \
autocad_zscale %zscale \
autocad_number_columns %number_columns \
autocad_number_rows %number_rows \
autocad_column_distance %column_distance \
autocad_row_distance %row_distance \
autocad_block_name %block_name
SHAPE insert \
$(autocadinShapeAttrs) \
XSCALE %xscale \
YSCALE %yscale \
ZSCALE %zscale \
COLUMNS %number_columns \
ROWS %number_rows \
CDISTANCE %column_distance \
RDISTANCE %row_distance \
BLOCKNAME %block_name
10-29 FME Reference Manual Version 2.0
Safe Software Inc. AUTOCAD DWG/DXF READER/WRITER
SHAPE_DEF insert SHAPE_GEOMETRY shape_point \
$(autocadinShapeAttrDefs) \
XSCALE number(14,6) \
YSCALE number(14,6) \
ZSCALE number(14,6) \
COLUMNS number(4,0) \
ROWS number(4,0) \
CDISTANCE number(14,6) \
RDISTANCE number(14,6) \
BLOCKNAME char(33)
#--------------------------------------------------------------
# autocad polygon
DWG * autocad_entity autocad_polygon \
$(StandardAutocadAttrs) \
autocad_elevation %elevation @Log()
SHAPE polygon \
$(autocadinShapeAttrs) \
ELEVATION %elevation
SHAPE_DEF polygon SHAPE_GEOMETRY shape_polygon \
$(autocadinShapeAttrDefs) \
ELEVATION number(14,6)
#---------------------------------------------------------------
# autocad Face
DWG * autocad_entity autocad_face \
$(StandardAutocadAttrs) \
autocad_edge_1 %edge1 \
autocad_edge_2 %edge2 \
autocad_edge_3 %edge3 \
autocad_edge_4 %edge4
SHAPE face \
$(autocadinShapeAttrs) \
EDGE1 %edge1 \
EDGE2 %edge2 \
EDGE3 %edge3 \
EDGE4 %edge4
SHAPE_DEF face SHAPE_GEOMETRY shape_polygon \
$(autocadinShapeAttrDefs) \
EDGE1 char(20) \
EDGE2 char(20) \
EDGE3 char(20) \
EDGE4 char(20)
#---------------------------------------------------------------
# autocad RAY entities
DWG * autocad_entity autocad_ray \
$(StandardAutocadAttrs)
SHAPE ray \
$(autocadinShapeAttrs)
SHAPE_DEF ray SHAPE_GEOMETRY shape_arc \
$(autocadinShapeAttrDefs)
AUTOCAD DWG/DXF READER/WRITER Safe Software Inc.
10-30 FME Reference Manual Version 2.0
#---------------------------------------------------------------
# autocad XLINE entities
DWG * autocad_entity autocad_xline \
$(StandardAutocadAttrs)
SHAPE xline \
$(autocadinShapeAttrs)
SHAPE_DEF xline SHAPE_GEOMETRY shape_arc \
$(autocadinShapeAttrDefs)
10.6 AutoCAD Mapping File Example 2
The mapping file below illustrates how to translate data from Shape to AutoCAD
DWG or DXF files.
# ===============================================================
# The below line defines the title presented to the user when this
# mapping file is run through the FME GUI. You may modify this
# if a more meaningful title would be appropriate.
GUI TITLE SHAPE to DWG Translation
# ===============================================================
# The below line names the log file to which useful statistics
# about the translation will be written. This line can be removed
# if you do not wish to keep these statistics
LOG_FILENAME c:\tmp\fmelog.txt
# ===============================================================
# The below line instructs the FME to log any features that do not
# match any of the source feature patterns listed further below in
# this file. If you are modifying this mapping file, this will be
# useful to describe to you exactly which features you are losing
# during translation, if the statistics indicate that features are
# not being correlated or grouped. Uncorrelated features do not
# match any source specification, ungrouped features do not have
# any corresponding _DEF line.
FME_DEBUG UNGROUPED UNCORRELATED
#===============================================================
# The below two lines define the type of reader and writer to be
# used for this translation.
READER_TYPE SHAPE
WRITER_TYPE DWG
# Specify the version of DWG file which is to be written.
# Either Release11,Release12, or Release13 are currently
# supported.
DWG_VERSION Release12
10-31 FME Reference Manual Version 2.0
Safe Software Inc. AUTOCAD DWG/DXF READER/WRITER
#===============================================================
# The AutoCAD file which contains definitions for blocks and line
# types which are to be copied to the destination and used in the
# translation.
DWG_TEMPLATEFILE c:\tmp\test.dwg
#===============================================================
# The below GUI line prompts for a drawing file to be used as the
# destination of the feature data.
GUI FILENAME DestDataset
DXF_FILES(*.dxf)|*.dxf|DWG_FILES(*.dwg)|*.dwg|All_files(*.*)|*.*
Output AutoCAD Dataset:
DWG_DATASET $(DestDataset)
#===============================================================
# The below GUI line prompts for a directory to be used as the
# source for the Shape files.
GUI DIRNAME SourceDataset Original Shape Directory:
SHAPE_DATASET $(SourceDataset)
#===============================================================
# The main body of the mapping file starts here. Each of the
# _DEF lines describes the data model of the particular feature
# type, and the correlation lines describe how the feature is
# transformed from the source type to the destination type.
# You may edit the below lines to add or remove attributes, change
# attribute definitions, or invoke other FME functions as the
# features are translated.
#===============================================================
SHAPE_DEF survmnmt \
SHAPE_GEOMETRY shape_point \
PARENTTYPE char(1) \
SMNUMBER number(8,0) \
FEATCODE char(12) \
PPID char(10) \
DATECHNG date \
PTWPPLAN char(10)
DWG_LINETYPE SAMPLE \
autocad_textpict "_____"
DWG_DEF points \
autocad_color 12 \
autocad_linetype CONTINUOUS \
PARENTTYPE char(1) \
SMNUMBER number(8,0) \
FEATCODE char(12) \
PPID char(10) \
DATECHNG date \
PTWPPLAN char(10)
DWG points \
autocad_entity autocad_insert \
autocad_block_name TESTBLK \
autocad_attribute_display invisible \
autocad_attributes_follow true \
AUTOCAD DWG/DXF READER/WRITER Safe Software Inc.
10-32 FME Reference Manual Version 2.0
PARENTTYPE %parenttype \
SMNUMBER %smnumber \
FEATCODE %featcode \
PPID %ppid \
DATECHNG %datechng \
PTWPPLAN %ptwpplan
SHAPE survmnmt \
PARENTTYPE %parenttype \
SMNUMBER %smnumber \
FEATCODE %featcode \
PPID %ppid \
DATECHNG %datechng \
PTWPPLAN %ptwpplan
#===============================================================
# Now define the correlation lines for shape features with Arc
geometry.
SHAPE_DEF boundary \
SHAPE_GEOMETRY shape_arc \
FEATCODE char(12) \
PPID char(10) \
DATECHNG date \
SURVEYDIST number(8,2)
DWG_DEF lines \
autocad_color 13 \
autocad_linetype SAMPLE \
FEATCODE char(12) \
PPID char(10) \
DATECHNG date \
SURVEYDIST number(8,2)
SHAPE boundary \
FEATCODE %featcode \
PPID %ppid \
DATECHNG %datechng \
SURVEYDIST %surveydist
DWG lines \
autocad_entity autocad_line \
FEATCODE %featcode \
PPID %ppid \
DATECHNG %datechng \
SURVEYDIST %surveydist
#===============================================================
# Now translate a few polygons.
SHAPE_DEF waterbdy \
SHAPE_GEOMETRY shape_polygon \
INSIDEY number(10,2) \
PPID char(10) \
INSIDEX number(9,2) \
DATECHNG date \
NAME char(45) \
PRNTTOWN char(10)
10-33 FME Reference Manual Version 2.0
Safe Software Inc. AUTOCAD DWG/DXF READER/WRITER
DWG_DEF polygon \
autocad_color 13 \
autocad_linetype CONTINUOUS \
SHAPE_GEOMETRY shape_polygon \
INSIDEY number(10,2) \
PPID char(10) \
INSIDEX number(9,2) \
DATECHNG date \
NAME char(45) \
PRNTTOWN char(10)
SHAPE waterbdy \
INSIDEY %insidey \
PPID %ppid \
INSIDEX %insidex \
DATECHNG %datechng \
NAME %name \
PRNTTOWN %prnttown
DWG polygon \
autocad_entity autocad_polygon \
INSIDEY %insidey \
PPID %ppid \
INSIDEX %insidex \
DATECHNG %datechng \
NAME %name \
PRNTTOWN %prnttown
AUTOCAD DWG/DXF READER/WRITER Safe Software Inc.
10-34 FME Reference Manual Version 2.0
11-1 FME Reference Manual Version 2.0
11
11 B.C. MINISTRY OF
ENVIRONMENT AND PARKS
(MOEP) READER/WRITER
The British Columbia (B.C.) Ministry of Environment and Parks (MOEP)
format is a compact binary format used in the provide of B.C., Canada. MOEP
features have few attributes, one of which is a feature code which encodes the
features properties. MOEP files can store only integer coordinates.
The MOEP reader and writer modules provide the Feature Manipulation
Engine (FME) with the capability to read and write files in binary MOEP
format, with either 16-bit or 32-bit integer coordinates. Support for ASCII
MOEP files is not provided.
TIP: Throughout this section, a binary MOEP file will be referred to simply as an MOEP file; this
reader/writer provides no support for ASCII MOEP files.
11.1 Overview
Each MOEP file starts with a small header, which is immediately followed by
a sequence of geometric features. The header contains information which is
global to the MOEP file, including a file type, a name for the content of the
file (such as a mapsheet ID), and whether the coordinates are specified with
16-bit or 32-bit integers. Each feature has a feature code, a single optional
attribute, a geometric type (point, line, text, etc.), and some type-specific
information (coordinates, rotation, text size, etc.).
B.C. MINISTRY OF ENVIRONMENT AND PARKS (MOEP) READER/WRITER Safe Software Inc.
11-2 FME Reference Manual Version 2.0
The FME considers an MOEP dataset to be a collection of MOEP files in a single
directory.
MOEP files are referred to in the mapping file by IDs rather than by physical
filenames. The mapping between IDs and physical names is defined by the MOEP file
definition lines within the mapping file.
11.2 Reader Overview
The MOEP reader produces FME features for all the feature data held in MOEP files
residing in a given directory. The MOEP reader first scans the directory it is given for
the MOEP files which have been defined in the mapping file. For each MOEP file that
it finds, it checks to see if it the ID corresponding to the file is requested by looking
at the list of IDs specified in the mapping file. If a match is found (or no IDs were
specified in the mapping file), the MOEP file is opened for read. The MOEP reader
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 MOEP reader starts on the next
file in the directory.
11.3 Reader Keywords
The following table lists the keywords processed by the MOEP reader. The suffixes
shown will be prefixed by the current <ReaderKeyword> in a mapping file. By
default, the <ReaderKeyword> for the MOEP reader is MOEP.
11.3.1 DATASET
The value for this keyword is the directory containing the MOEP files to be read. A
typical mapping file fragment specifying an input MOEP dataset looks like:
Keyword Suffix Value Required/
Optional
DATASET Contains the directory name of the input MOEP files. Required
DEF Defines a MOEP file. Each MOEP file must be defined
before it can be read. The definition maps a physical
filename to an ID which is used to refer to the file within
the mapping file. In addition, global attributes for the file
can be specified in the definition. There may be many
DEF lines, one for each file to be read.
Required
IDs Contains a list of IDs corresponding to MOEP files to
process. If other MOEP files were in the directory, they
are ignored. If this is not specified, then all defined
MOEP files in the directory will be read.
Optional
11-3 FME Reference Manual Version 2.0
Safe Software Inc. B.C. MINISTRY OF ENVIRONMENT AND PARKS (MOEP) READER/WRITER
MOEP_DATASET /usr/data/moep/92i080
11.3.2 DEF
Each MOEP file must be defined before it may be read. The definition specifies the
ID to be used to refer to the file along with the physical filename (including its
extension). In addition to the filename, other global attributes (from the table below)
can be specified in the definition. When additional attributes are specified for an
MOEP file being read, the reader will generate warnings if the specified values do not
match those specified in the files header. The writer uses the global attributes to fill
in the header of the MOEP file being written.
The syntax of an MOEP DEF line is:
<ReaderKeyword>_DEF <fileID> \
MOEP_FILENAME <physFileName> \
[<attrName> <attrVal>]*
The following table shows all of the global attributes which are supported.
The following mapping file fragment defines two MOEP files, one containing DEM
data with 16-bit coordinates, and one containing contours, with 32-bit coordinates:
Attribute Name Comments
MOEP_FILENAME Name of physical file within MOEP dataset.
MOEP_RESOLUTION The size of integer used to represent each X and Y
coordinate value within the MOEP file. This can be either
16 or 32, indicating 16-bit or 32-bit integers, respectively.
(Z coordinates are always 16 bits, regardless of this
attributes value.)
MOEP_FILE_TYPE An integer in the range 0..9 denoting the type of data this file
contains.
MOEP_NAME An ASCII string (0 to 11 characters in length) providing a
logical name for the file. This is stored in the files header;
it typically contains a mapsheet ID.
MOEP_DATE The date of submission of the MOEP file. The format for
this date is YYMMDD, where YY is the last two digits of
the year, MM is the month (01-12), and DD is the day within
the month (01-31).
MOEP_OFFSET_MINIMUM The MOEP writer module uses this value to determine the
origin from which 16-bit (X,Y) coordinates are measured.
As features are written to the MOEP file, their minimum
bounding rectangle is maintained; once the MBR is larger
than MOEP_OFFSET_MINIMUM in both the X and Y
directions, its center point is chosen as the origin for all
coordinates written to the file. This attribute has no effect on
32-bit coordinates, which are always measured from (0,0).
B.C. MINISTRY OF ENVIRONMENT AND PARKS (MOEP) READER/WRITER Safe Software Inc.
11-4 FME Reference Manual Version 2.0
MOEP_DEF dem_data MOEP_FILENAME 92b053d.arc \
MOEP_FILE_TYPE 1 \
MOEP_RESOLUTION 16 \
MOEP_NAME 92b053d \
MOEP_DATE 960913 \
MOEP_OFFSET_MINIMUM 1000
MOEP_DEF contour_data MOEP_FILENAME 92b053t \
MOEP_FILE_TYPE 2 \
MOEP_RESOLUTION 32 \
MOEP_NAME 92b053t \
MOEP_DATE 960913
11.3.3 IDs
This optional specification is used to limit the available and defined MOEP files read.
If no IDs are specified, then all defined and available MOEP files are read. The
syntax of the IDs keyword is:
<ReaderKeyword>_IDs <fileID1> \
<fileID1> \
<fileIDn>
The fileIDs must match those used in DEF lines.
The below example selects only the dem_data MOEP file for input during a
translation:
MOEP_IDs dem_data
11.4 Writer Overview
The MOEP writer creates and writes feature data to MOEP files in the directory
specified by the DATASET keyword. If the directory did not exist before the
translation, the writer will create it. Any old MOEP files in the directory will be
overwritten with the new feature data. The FME determines which file features are to
be written to as they are routed to the MOEP writer. Many MOEP files can be written
during a single FME session.
11.5 Writer Keywords
The MOEP writer processes the DATASET and DEF keywords as described in the
reader keywords section. It does not make use of the IDs keyword.
11-5 FME Reference Manual Version 2.0
Safe Software Inc. B.C. MINISTRY OF ENVIRONMENT AND PARKS (MOEP) READER/WRITER
11.6 Feature Representation
Special FME attributes are used to hold the parameters to MOEP features. The MOEP
writer uses these attributes to define aspects of the geometries of the features it writes
out, and the MOEP reader will define these attributes from the MOEP features it
reads.
One of these attributes is an optional user attribute which can contain up to 66
characters of arbitrary data.
The FME considers the ID of the MOEP file to be the FME feature type of an MOEP
feature. The feature type of an MOEP feature must match the ID of an MOEP file
defined by an MOEP DEF line.
Every MOEP feature, regardless of its geometry type, shares the parameters shown
in the following table. Subsequent subsections will describe parameters specific to
each feature type.
11.6.1 Line Features
moep_type: moep_line
MOEP line features have two or more coordinates. FME features with an moep_type
of moep_line correspond to non-contour MOEP features with a type of 02, 03, 12,
or 13; the moep_display_type and moep_line_type differentiate between
the different types.
The following attributes are defined for moep_line features:
Attribute Name Contents
moep_type The type of the geometry for the feature. This attribute will
contain one of:
moep_line
moep_contour_line
moep_point
moep_text
moep_arc
moep_code Character string with up to 10 characters designating the
feature code of the feature. If this is not specified for a feature
being written, the feature will have the same feature code as
the feature which was most recently written to the MOEP file.
moep_attribute An optional attribute (MOEP type 05 feature) which can
contain up to 66 characters of arbitrary text. (See also the
moep_font, moep_weight, and moep_text_group
attributes defined on moep_text features.)
B.C. MINISTRY OF ENVIRONMENT AND PARKS (MOEP) READER/WRITER Safe Software Inc.
11-6 FME Reference Manual Version 2.0
11.6.2 Contour Features
moep_type: moep_contour_line
MOEP contour line features have three or more coordinates. FME features with an
moep_type of moep_contour correspond to MOEP features with a type of 02, 03,
12, or 13 which are represent contour data; the moep_display_type and
moep_line_type differentiate between the different types.
Aside from the moep_line_type and moep_display_type attributes that
contour lines inherit from moep_line features, the following attribute is defined for
moep_contour_line features:
11.6.3 Point Features
moep_type: moep_point
In addition to an (X,Y,Z) location, an MOEP point has some additional attributes
which affect the display of its point symbol. The symbol will always be centred
around its location, but can be rotated and/or scaled, in both the X and Y directions.
Attribute Name Contents
moep_line_type Determines whether the MOEP feature is simple or complex
(curvilinear). Legal values are curve and line. (The
default is line.)
moep_display_type Determines whether the line is a primary line or a duplicate.
Legal values are primary and construction. (The
default is primary.)
Attribute Name Contents
moep_contour_elevation The elevation of the contour line.
Attribute Name Contents
moep_rotation Determines the rotation applied to the point symbol,
measured in degrees counter-clockwise from horizontal. (The
default is 0.0 degrees.)
moep_scale_x Multiplier applied to scale the point symbol in the X direction.
(If this is not provided, it defaults to 1.0.)
moep_scale_y Multiplier applied to scale the point symbol in the Y direction.
(If this is not provided, it defaults to 1.0.)
11-7 FME Reference Manual Version 2.0
Safe Software Inc. B.C. MINISTRY OF ENVIRONMENT AND PARKS (MOEP) READER/WRITER
11.6.4 Arc Features
moep_type: moep_arc
MOEP arc features represent a directed circular segment between two points on an
ellipse. The representation of an arc is a set of three (X,Y,Z) coordinates - start of arc,
end of arc, and origin of arc - along with a the direction of the arc.
11.6.5 Text Features
moep_type: moep_text
MOEP text features represent textual annotation placed at specific world coordinates.
The full specification of the geometry includes an (X,Y,Z) position, the rotation of
the text, the text string itself, the size of the text, and a specification of font, weight,
and text group number.
Attribute Name Contents
moep_sweep_direction The direction in which the arc is drawn. Legal values are
clockwise and counter-clockwise. (The default is
clockwise.)
Attribute Name Contents
moep_rotation Determines the rotation applied to the text, measured in
degrees counter-clockwise from horizontal.
moep_text_string The characters which make up a line of the text feature. The
maximum length of a line of text is 66 characters. (Several
text features can be grouped into a single feature using the
moep_text_group attribute.)
moep_text_size The size of the text feature, measured in ground metres.
moep_font Specifies a font number for the text (an integer in the range
0..99). See the discussion below this table regarding the
encoding of font, weight, and text group.
moep_weight Specifies the weight of the text (an integer in the range 0..99).
See the discussion below this table regarding the encoding of
font, weight, and text group.
moep_text_group Specifies a group number; several text features can be
logically grouped together by giving them the same group
number. This number is a five digit, decimal integer. See the
discussion below this table regarding the encoding of font,
weight, and text group.
rotation
B.C. MINISTRY OF ENVIRONMENT AND PARKS (MOEP) READER/WRITER Safe Software Inc.
11-8 FME Reference Manual Version 2.0
It is important to note the relationship between the font, weight, text group, and the
optional attribute for the feature. If font, weight, and text group attributes are
specified, MOEP uses the optional attribute of a text feature to store their values.
When these are specified, the format of the attribute string is FFFWWWGGGGGG,
where FFF is the font number, WWW is the weight, and GGGGGG is the text group
number. Each number is right-justified in its field, padded to the left with spaces as
necessary.
Similarly, when reading a text feature, the optional attribute (if present) will be
broken down into a font, weight, and text group.
11.7 MOEP Mapping File Example 1
The mapping file below performs generic translation from MOEP to ESRI Shape
files. Each MOEP feature type is stored in a separate Shape/DBF pair thereby
retaining all of the standard attribution for each of the different entities.
# Generic MOEP to Shape file translation
# This mapping file configures the FME to copy the contents
# of a set of MOEP file for mapsheet 92b051 into shape files.
# Each feature type will be output into its own shape file,
# and the attributes in the shape file are the attributes from the
# MOEP features.
#
#---------------------------------------------------------------
# The title for the form
LOG_FILENAME /tmp/moep2shp.log
GUI TITLE Generic MOEP to Shape File Translation
#---------------------------------------------------------------
# First set up the reader and writer the FME will use.
READER_TYPE MOEP
WRITER_TYPE SHAPE
#---------------------------------------------------------------
# Now identify the input and output datasets (the GUI will supply
the macros)
GUI FILENAME SourceDataset
MOEP_Files(*.arc)|*.arc|MOEP_Files(*.bin)|*.bin|All_files(*.*
)|*.* Source MOEP Dataset:
GUI DIRNAME ShapeDir Output Shape Directory:
SHAPE_DATASET $(ShapeDir)
# ---------------------------------------------------------------
# Map input MOEP filenames to identifiers.
#
11-9 FME Reference Manual Version 2.0
Safe Software Inc. B.C. MINISTRY OF ENVIRONMENT AND PARKS (MOEP) READER/WRITER
MOEP_DEF moep_dem \
MOEP_FILENAME 92b053d.arc
MOEP_DEF moep_toponymy \
MOEP_FILENAME 92b053g.arc
MOEP_DEF moep_non_positional \
MOEP_FILENAME 92b053n.arc
MOEP_DEF moep_planimetric \
MOEP_FILENAME 92b053p.arc
MOEP_DEF moep_contours \
MOEP_FILENAME 92b053t.arc
#===============================================================
SHAPE_DEF lines \
SHAPE_GEOMETRY shape_arc \
MOEP_CODE char(10) \
ATTRIBUTE char(66) \
TYPE char(12) \
LINE_TYPE char(5) \
FILE_CODE char(23)
MOEP * \
moep_type moep_line \
moep_code %moep_code \
moep_attribute %moep_attribute \
moep_display_type %moep_display_type \
moep_line_type %moep_line_type \
@FeatureType(%moep_file_code)
SHAPE lines \
MOEP_CODE %moep_code \
ATTRIBUTE %moep_attribute \
TYPE %moep_display_type \
LINE_TYPE %moep_line_type \
FILE_CODE %moep_file_code
#===============================================================
SHAPE_DEF contours \
SHAPE_GEOMETRY shape_arc \
MOEP_CODE char(10) \
ELEVATION number(5,0) \
ATTRIBUTE char(66) \
TYPE char(12) \
LINE_TYPE char(5) \
FILE_CODE char(23)
MOEP * \
moep_type moep_contour_line \
moep_code %moep_code \
moep_contour_elevation %moep_contour_elevation \
moep_attribute %moep_attribute \
moep_display_type %moep_display_type \
moep_line_type %moep_line_type \
@FeatureType(%moep_file_code)
SHAPE contours \
MOEP_CODE %moep_code \
B.C. MINISTRY OF ENVIRONMENT AND PARKS (MOEP) READER/WRITER Safe Software Inc.
11-10 FME Reference Manual Version 2.0
ELEVATION %moep_contour_elevation \
ATTRIBUTE %moep_attribute \
TYPE %moep_display_type \
LINE_TYPE %moep_line_type \
FILE_CODE %moep_file_code
#===============================================================
SHAPE_DEF point \
SHAPE_GEOMETRY shape_point \
MOEP_CODE char(10) \
SCALE_Y number(6,2) \
ATTRIBUTE char(66) \
SCALE_X number(6,2) \
ROTATION number(8,4) \
FILE_CODE char(23)
MOEP * \
moep_type moep_point \
moep_code %moep_code \
moep_scale_y %moep_scale_y \
moep_attribute %moep_attribute \
moep_scale_x %moep_scale_x \
moep_rotation %moep_rotation \
@FeatureType(%moep_file_code)
SHAPE point \
MOEP_CODE %moep_code \
SCALE_Y %moep_scale_y \
ATTRIBUTE %moep_attribute \
SCALE_X %moep_scale_x \
ROTATION %moep_rotation \
FILE_CODE %moep_file_code
#===============================================================
SHAPE_DEF text \
SHAPE_GEOMETRY shape_point \
MOEP_CODE char(10) \
ATTRIBUTE char(66) \
STRING char(66) \
MOEP_FONT char(3) \
WEIGHT char(3) \
TEXT_GROUP char(6) \
TEXT_SIZE number(5,0) \
ROTATION number(8,4) \
FILE_CODE char(23)
MOEP * \
moep_type moep_text \
moep_code %moep_code \
moep_attribute %moep_attribute \
moep_text_string %moep_text_string \
moep_font %moep_font \
moep_weight %moep_weight \
moep_text_group %moep_text_group \
moep_text_size %moep_text_size \
moep_rotation %moep_rotation \
@FeatureType(%moep_file_code)
11-11 FME Reference Manual Version 2.0
Safe Software Inc. B.C. MINISTRY OF ENVIRONMENT AND PARKS (MOEP) READER/WRITER
SHAPE text \
MOEP_CODE %moep_code \
ATTRIBUTE %moep_attribute \
STRING %moep_text_string \
MOEP_FONT %moep_font \
WEIGHT %moep_weight \
TEXT_GROUP %moep_text_group \
TEXT_SIZE %moep_text_size \
ROTATION %moep_rotation \
FILE_CODE %moep_file_code
11.8 MOEP Mapping File Example 2
The mapping file below illustrates how to translate Shape files generated by the above
example back into MOEP files. The only real differences are the switching of reader
type and writer type, the Graphical User Interface (GUI) line changes, and the
additional global attributes added to the MOEP_DEF lines of the output files.
#===============================================================
# The below line defines the title presented to the user when this
# mapping file is run through the FME GUI. You may modify this
# if a more meaningful title would be appropriate.
GUI TITLE SHAPE to MOEP Translation
#===============================================================
#The below line names the log file to which useful statistics about
#the translation will be written. This line can be removed if you
#do not wish to keep these statistics
LOG_FILENAME c:\tmp\fmelog.txt
#===============================================================
# The below two lines define the type of reader and writer to be
# used for this translation.
READER_TYPE SHAPE
WRITER_TYPE MOEP
#===============================================================
# The below GUI line prompts for a directory into which to write the
# resulting MOEP files.
GUI DIRNAME moepDir Output MOEP Directory:
MOEP_DATASET $(moepDir)
#===============================================================
# The below GUI line prompts for a directory to be used as the
# the source for the Shape files.
GUI DIRNAME SourceDataset Original Shape Directory:
SHAPE_DATASET $(SourceDataset)
# ---------------------------------------------------------------
# Map output MOEP filenames to identifiers and define global attributes
# to be placed into the new files headers.
B.C. MINISTRY OF ENVIRONMENT AND PARKS (MOEP) READER/WRITER Safe Software Inc.
11-12 FME Reference Manual Version 2.0
#
MOEP_DEF moep_dem \
MOEP_FILENAME 92b053d.arc \
MOEP_FILE_TYPE 1 \
MOEP_RESOLUTION 32 \
MOEP_NAME 92b053d \
MOEP_DATE 960916
MOEP_DEF moep_toponymy \
MOEP_FILENAME 92b053g.arc \
MOEP_FILE_TYPE 5 \
MOEP_RESOLUTION 32 \
MOEP_NAME 92b053g \
MOEP_DATE 960916
MOEP_DEF moep_non_positional \
MOEP_FILENAME 92b053n.arc \
MOEP_FILE_TYPE 3 \
MOEP_RESOLUTION 32 \
MOEP_NAME 92b053n \
MOEP_DATE 960916
MOEP_DEF moep_planimetric \
MOEP_FILENAME 92b053p.arc \
MOEP_FILE_TYPE 4 \
MOEP_RESOLUTION 32 \
MOEP_NAME 92b053p \
MOEP_DATE 960916
MOEP_DEF moep_contours \
MOEP_FILENAME 92b053t.arc \
MOEP_FILE_TYPE 2 \
MOEP_RESOLUTION 32 \
MOEP_NAME 92b053t \
MOEP_DATE 960916
#===============================================================
SHAPE_DEF lines \
SHAPE_GEOMETRY shape_arc \
MOEP_CODE char(10) \
ATTRIBUTE char(66) \
TYPE char(12) \
LINE_TYPE char(5) \
FILE_CODE char(23)
MOEP * \
moep_type moep_line \
moep_code %moep_code \
moep_attribute %moep_attribute \
moep_display_type %moep_display_type \
moep_line_type %moep_line_type \
@FeatureType(%moep_file_code)
SHAPE lines \
MOEP_CODE %moep_code \
ATTRIBUTE %moep_attribute \
TYPE %moep_display_type \
LINE_TYPE %moep_line_type \
FILE_CODE %moep_file_code
11-13 FME Reference Manual Version 2.0
Safe Software Inc. B.C. MINISTRY OF ENVIRONMENT AND PARKS (MOEP) READER/WRITER
#===============================================================
SHAPE_DEF contours \
SHAPE_GEOMETRY shape_arc \
MOEP_CODE char(10) \
ELEVATION number(5,0) \
ATTRIBUTE char(66) \
TYPE char(12) \
LINE_TYPE char(5) \
FILE_CODE char(23)
MOEP * \
moep_type moep_contour_line \
moep_code %moep_code \
moep_contour_elevation %moep_contour_elevation \
moep_attribute %moep_attribute \
moep_display_type %moep_display_type \
moep_line_type %moep_line_type \
@FeatureType(%moep_file_code)
SHAPE contours \
MOEP_CODE %moep_code \
ELEVATION %moep_contour_elevation \
ATTRIBUTE %moep_attribute \
TYPE %moep_display_type \
LINE_TYPE %moep_line_type \
FILE_CODE %moep_file_code
#===============================================================
SHAPE_DEF point \
SHAPE_GEOMETRY shape_point \
MOEP_CODE char(10) \
SCALE_Y number(6,2) \
ATTRIBUTE char(66) \
SCALE_X number(6,2) \
ROTATION number(8,4) \
FILE_CODE char(23)
MOEP * \
moep_type moep_point \
moep_code %moep_code \
moep_scale_y %moep_scale_y \
moep_attribute %moep_attribute \
moep_scale_x %moep_scale_x \
moep_rotation %moep_rotation \
@FeatureType(%moep_file_code)
SHAPE point \
MOEP_CODE %moep_code \
SCALE_Y %moep_scale_y \
ATTRIBUTE %moep_attribute \
SCALE_X %moep_scale_x \
ROTATION %moep_rotation \
FILE_CODE %moep_file_code
#===============================================================
SHAPE_DEF text \
SHAPE_GEOMETRY shape_point \
MOEP_CODE char(10) \
B.C. MINISTRY OF ENVIRONMENT AND PARKS (MOEP) READER/WRITER Safe Software Inc.
11-14 FME Reference Manual Version 2.0
ATTRIBUTE char(66) \
STRING char(66) \
MOEP_FONT char(3) \
WEIGHT char(3) \
TEXT_GROUP char(6) \
TEXT_SIZE number(5,0) \
ROTATION number(8,4) \
FILE_CODE char(23)
MOEP * \
moep_type moep_text \
moep_code %moep_code \
moep_attribute %moep_attribute \
moep_text_string %moep_text_string \
moep_font %moep_font \
moep_weight %moep_weight \
moep_text_group %moep_text_group \
moep_text_size %moep_text_size \
moep_rotation %moep_rotation \
@FeatureType(%moep_file_code)
SHAPE text \
MOEP_CODE %moep_code \
ATTRIBUTE %moep_attribute \
STRING %moep_text_string \
MOEP_FONT %moep_font \
WEIGHT %moep_weight \
TEXT_GROUP %moep_text_group \
TEXT_SIZE %moep_text_size \
ROTATION %moep_rotation \
FILE_CODE %moep_file_code
12-1 FME Reference Manual Version 2.0
12
12 DESIGN FILE READER/WRITER
The Intergraph Design File reader and writer modules provide the Feature
Manipulation Engine (FME) with access to files used by the MicroStation and
Intergraph Interactive Graphics Design System (IGDS). Intergraph has made
public the specification for this file format, which they call the Intergraph
Standard File Format (ISFF)
1
. This section assumes familiarity with this
format.
12.1 Overview
Design files consist of a header, followed by a series of elements. The header
contains global information including the transformation equation from
design units to user coordinates, as well as the dimension of the elements in
the file. Each element contains standard display information, such as its
color, level, class, and style, as well as a number of attributes specific to its
element type. For example, a text element has fields for font, size, and the text
string in addition to the standard display attributes.
TIP: The IGDS reader and writer modules support both 2 and 3 dimensional design files and cell
libraries.
Individual design file elements must be less than a system imposed maximum
number of bytes. Complex elements solve this problem by physically
grouping individual elements together into an object that will be manipulated
1. Throughout this section, the terms IGDS file and Design file are used interchangeably to refer
to the ISFF format.
DESIGN FILE READER/WRITER Safe Software Inc.
12-2 FME Reference Manual Version 2.0
as a whole. The FME transparently handles such complex elements as single FME
features. This situation occurs when text elements are grouped together into a single
complex element headed up by a text node, and when linear or polygonal features
have more than 101 vertices. Cells are complex elements used as symbols, and are
treated as atomic entities by the FME.
Each IGDS file element may have one or more attribute linkages associated with it.
The IGDS reader and writer support both user data and database linkages. The linkage
values may be used to join elements with attributes stored in relational tables through
the use of the @Relate FME Transformation Function. Linkages may also be used
to specify a fill color for IGDS Shape elements, and other application specific data.
Because design files support three interpretations of units, IGDS reader and writer
must be told how to interpret the feature coordinate units and how they will be
converted to and from Units of Resolution (UORs). The feature coordinate units may
be interpreted as Master Units, SubUnits, or as raw UORs, depending on the setting
of IGDS_UNITS in the mapping file.
The IGDS reader and writer use symbolic names for the IGDS element types rather
than the IGDS numeric values. This greatly simplifies element type specification. The
following table maps the IGDS element type number to its corresponding FME
feature igds_type attribute value that is used by the IGDS reader and writer.
Subsequent subsections describe the handling of each of these element types in detail.
IGDS Element Type FME igds_type
2 igds_cell
3 igds_point
4,12 igds_line
6,14 igds_shape
7 igds_text_node
11,12 igds_curve
15 igds_ellipse
16 igds_arc
17 igds_text
7,17 igds_multi_text
2,6,14 igds_solid
12-3 FME Reference Manual Version 2.0
Safe Software Inc. DESIGN FILE READER/WRITER
12.2 Reader Overview
The IGDS reader first reads the header information from the design file being
processed, and extracts the conversion parameters required to translate coordinates
from internal IGDS UORs to ground units. It also determines the dimension of the
input file.
It then extracts each individual element, one at a time, and passes it on to the rest of
the FME for processing. Complex elements are extracted as single FME features. If
a complex element contains an arc then the reader automatically converts it to a
linestring enabling it to be processed by all other readers and writers within the FME.
If the element had any attribute linkages attached to it, these are read and added as
attributes to the FME feature being created.
When the IGDS reader encounters an element types it does not know how to process,
it simply ignores it and moves on to read the next element.
12.3 Reader Keywords
The IGDS reader processes the <ReaderKeyword>_DATASET keyword in the
mapping file. The value for this keyword is the filename of the IGDS file to be read.
By default, the <ReaderKeyword> for the IGDS reader is IGDS, so a typical
mapping file fragment specifying an input IGDS file looks like:
IGDS_DATASET /usr/data/dgn/92b034.dgn
The IGDS reader also processes the <ReaderKeyword>_UNITS keyword in the
mapping file. This keyword controls the conversion between UORs in the design file
and FME coordinates. There are three possibilities, outlined in the table below. If no
UNITS keyword is specified, then IGDS_SUB_UNITS is assumed.
The IGDS reader processes several other keywords in the mapping file, as shown in
the following table. These enable the FME to override the Global Origin and Scaling
IGDS_UNITS Value Description
IGDS_MASTER_UNITS The UORs read from the design file will be converted into
master units, according to the conversion factor read from the
design file header, before being stored in an FME feature.
IGDS_SUB_UNITS The UORs read from the design file will be converted into
subunits, according to the conversion factor read from the
design file header, before being stored in an FME feature.
This is the default.
IGDS_UORS The UORs read from the design file will be stored directly in
an FME feature, with no conversion.
DESIGN FILE READER/WRITER Safe Software Inc.
12-4 FME Reference Manual Version 2.0
information. The first four keywords are normally used only when reading design
files which have bad header information. If the FME detects a difference between
these settings and those read from the design file, a warning is output to the log file
and these settings prevail.
The IGDS reader can also be configured to output all the elements composing cells,
or symbols. This is useful if the graphical representation of the design file is to be
preserved. This is true when, for example, a design file is translated to a GIF image.
All settings in the following table are prefixed by the current <ReaderKeyword>.
12.4 Writer Overview
When creating a new design file, header information is typically extracted from an
previously existing design file, called a seed file. The IGDS writer first copies the
seed files header information to the destination file, and then extracts the conversion
parameters required to translate coordinates from feature coordinate units to internal
IGDS Units of Resolution (UORs)
2
. It also determines the dimension of the seed file.
Because seed files with a sufficient ground range and resolution may be difficult to
obtain, the IGDS writer allows seed parameters to be overridden in the mapping file.
When a seed file with insufficient range available is used, the IGDS writer will report
that features were outside of the bounds of the seed file, and suggest values for the
global origin and UOR/subunit/master unit ratios to use.
A cell library file may optionally be used by the IGDS writer. Cell libraries contain
named symbol definitions which can be used to depict point features. If a cell library
2. Since coordinates in design files are ultimately stored as integer UORs, it is possible for precision to
be lost or overflow to occur when they are output. Care must be taken to ensure that the conversion
parameters in the seed file preserve the data precision and range.
Keyword Suffix Value Required/
Optional
UOR_SCALE The number of ground units per UOR Optional
UOR_GLOBAL_ORIGIN_X The global origin of x measured in UORs. Optional
UOR_GLOBAL_ORIGIN_Y The global origin of y measured in UORs. Optional
UOR_GLOBAL_ORIGIN_Z The global origin of z measured in UORs. Optional
EXPAND_CELLS Controls whether or not all the components of a
cell will be output by the reader.
If the value is YES, then they are.
If it is NO, then only the cell header is output.
The default is NO.
Optional
12-5 FME Reference Manual Version 2.0
Safe Software Inc. DESIGN FILE READER/WRITER
is specified, the IGDS writer reads in all the cell definitions for later when cell
features are output. The IGDS writer can use either 2 or 3 dimension cell libraries,
and will automatically convert the cell definitions to be of the correct dimension for
output.
The IGDS writer then outputs each FME feature it is given. Most often, a single FME
feature corresponds to a single IGDS element. If any linkages are specified for the
element, they are also output. However, some of the IGDS element types cause
several elements to be output as a complex unit (with the complex bit turned on). This
occurs when a multi-line text object, a cell, or a closed shape or linear feature with
more than 101 coordinates is output. The IGDS writer hides all of the details of
complex element output.
The IGDS writer can be configured to do one of two things with linear features that
have exactly two points. By default, a type 4 linestring will be created for such
features. However, if IGDS_CREATE_LINE_ELEMENTS is set to yes in the
mapping file, then a type 3 line element will be created for the two point linear
feature.
12.5 Writer Keywords
The IGDS writer processes several keywords in the mapping file, as shown in the
following table. These are all prefixed by the current <WriterKeyword>.
Keyword Suffix Value Required/
Optional
DATASET The filename of the output IGDS File. Required
SEED_FILE The filename of the design file which will be used to seed
the output files header information.
Required
CELL_LIBRARY The filename of an IGDS cell library, which contains the
definitions of cells which may later be output.
Optional
UNITS Specifies how FME feature coordinates will be
interpreted and converted into UORs. See the
documentation under the IGDS reader for details.
Optional
CREATE_LINE_
ELEMENTS
Controls whether or not type 3 line elements will be used
for two point linear features. Valid values are yes or no.
By default, no is assumed.
Optional
UOR_GLOBAL_
ORIGIN_X
The global origin of x, measured in UORs. Overrides that
read from the seed file.
Optional
UOR_GLOBAL_
ORIGIN_Y
The global origin of y, measured in UORs. Overrides that
read from the seed file.
Optional
UOR_GLOBAL_
ORIGIN_Z
The global origin of z, measured in UORs. Overrides that
read from the seed file.
Optional
DESIGN FILE READER/WRITER Safe Software Inc.
12-6 FME Reference Manual Version 2.0
By default, the <WriterKeyword> for the IGDS writer is IGDS, so a typical
mapping file fragment configuring the IGDS writer would be:
IGDS_DATASET /usr/data/dgn/92b034.dgn
IGDS_SEED_FILE /usr/data/dgn/2dseed.dgn
IGDS_CELL_LIBRARY /usr/data/dgn/cartog.cel
12.6 Feature Representation
Special FME feature attributes are used to hold IGDS element parameters. The IGDS
writer will use these attribute values as it fills in an element structure during output.
The IGDS reader will set these attributes in the FME feature it creates for each
element it reads.
The FME considers the IGDS level to be the FME feature type of an IGDS feature.
Each IGDS element, regardless of its geometry type, shares a number of other
parameters, as described in the following table. Subsequent subsections will describe
parameters specific to each of the supported element types.
MASTER_UNIT_
NAME
The two character master unit name to use. Overrides that
read from the seed file.
Optional
SUB_UNIT_NAME The two character sub unit name to use. Overrides that
read from the seed file.
Optional
SUBS_PER_
MASTER
The number of sub units per master unit. Overrides that
read from the seed file.
Optional
UORS_PER_SUB The number of UORs per sub unit. Overrides that read
from the seed file.
Optional
Attribute Name Contents
igds_color The elements color setting.
Range: 0..255
Default: 0
igds_class The elements class.
Range: 0..15
Default: 0
igds_graphic_group The elements graphic group number.
Range: 0..65535
Default: 0
Keyword Suffix Value Required/
Optional
12-7 FME Reference Manual Version 2.0
Safe Software Inc. DESIGN FILE READER/WRITER
12.6.1 Attribute Linkages
Each element in an IGDS file may have one or more attribute linkages attached to it.
The IGDS reader and writer support both user data and database attribute linkages.
Because an element may have more than one linkage, linkages are stored in an FME
feature attribute list named igds_linkage{#}. As with other feature attribute
lists, # starts at zero and increments for each successive linkage.
TIP: By using a common value for graphic group value, several otherwise separate elements may be tied
together into a logical super-element for later processing by application programs.
The following attribute list item names are used by all linkages:.
igds_style The elements line style.
Range: 0..7
Default: 0
igds_type The FME name for the type of element this feature
represents.
Range: See Table in Overview
Default: No default
igds_weight The elements line weight.
Range: 0..31
Default: 0
Linkage Parameter Contents
type The type of linkage.
Range: user|dbase|
oracle|informix|ris
Default: No default
class Linkage Class.
Range: 0..15
Default: 0
ibit Linkage ibit value.
Range: 0|1
Default: 0
mbit Linkage mbit value.
Range: 0|1
Default: 0
rbit Linkage rbit value.
Range: 0|1
Default: 0
Attribute Name Contents
DESIGN FILE READER/WRITER Safe Software Inc.
12-8 FME Reference Manual Version 2.0
If the linkage is of type user, then these attribute list item names are used to specify
the values for the user linkage:
If the linkage is of type dbase, oracle, ris, or informix, then these attribute
list item names are used to specify the values for the database linkage.
For example, the FME feature specified by the below partial transfer specification
would have two linkages. The first linkage is a user linkage, which specifies that the
shape be filled with color 12, and the second linkage is a dbase linkage which to the
record with the key value of 1001.
ubit Linkage ubit value.
Range: 0|1
Default: 1
Linkage Parameter Contents
userId The user -ID of the linkage. This is application
specific.
Range: 0..65535
Default: No default
long{#} The user data associated with a user linkage may be
specified as a list of 32 bit long integers or as a list
of 16 bit words. If 32 bit long integers are used to
fill out the attribute linkage, they have this suffix
and are numbered sequentially starting from 0.
Range: 32 bit integer
Default: 0
word{#} If 16 bit words are used to fill out the attribute
linkage, they have this suffix and are numbered
sequentially starting from 0.
Range: 0..65535
Default: 0
Linkage Parameter Contents
entity_number The entity number of the linkage.
Range: 0..65535
Default: 1
key The key value of the database linkage. This
value corresponds to the value in a field in the
attribute row associated with the element in
the database.
Range: 32 bit integer
Default: No default
Linkage Parameter Contents
12-9 FME Reference Manual Version 2.0
Safe Software Inc. DESIGN FILE READER/WRITER
MACRO fillUserId 65
MACRO fillMagic 67586
IGDS 32 igds_type igds_shape \
igds_color 8 igds_weight 1 \
igds_linkage{0}.type user \
igds_linkage{0}.userId $(fillUserId) \
igds_linkage{0}.long{0} $(fillMagic) \
igds_linkage{0}.long{1} 12 \
igds_linkage{1}.type dbase \
igds_linkage{1}.key 1001
12.6.2 Cells
igds_type: igds_cell
Cells correspond to IGDS element type 2. The FME feature used to hold a cell
element does not contain the complete set of elements which make up the cells
definition. Instead, FME features representing IGDS cells contain only the cells
name, as well as rotation and scaling parameters. The IGDS reader skips all the
elements which define the cell (extracting only the text strings from any text elements
in the cell), and the IGDS writer will extract the cell description from the supplied cell
library to be output. Cell features are point features, and have only a single
coordinate.
The IGDS reader may be set to expand cells. If the control file contains a yes setting
for IGDS_EXPAND_CELLS, then each member element of the cell is read and
output. In addition, the cell and all of its members are assigned a unique cell sequence
number in the igds_cell_sequence. This number can be used to later regroup
the cell with its components if that is required.
Both graphic and point cells are supported. Graphic cells use the level, color, and
style information from the cell library, and must always have a feature type of 0. Point
cells use the level, color, and style information provided in the mapping file.
Attribute Name Contents
igds_cell_name The name of the cell. Corresponds to the name of the
cell in a cell library.
Range: Character String
Default: No default
igds_cell_x_scale
igds_cell_y_scale
igds_cell_z_scale
The scaling factors to apply to the cell.
Range: Any real number > 0
Default: 1
igds_rotation The rotation of the entire cell. The rotation is measured
in degrees counter clockwise up from horizontal.
Range: -360.0..360.0
Default: 0
rotation
DESIGN FILE READER/WRITER Safe Software Inc.
12-10 FME Reference Manual Version 2.0
12.6.3 Points
igds_type: igds_point
Strictly speaking, the IGDS file format does not support point data. However, for
easier interoperability with other formats, the IGDS reader and writer define a
synthetic IGDS type for point data. Such features have only a single coordinate, and
are stored in an IGDS type 3 element
3
as a zero length line with the start and the end
point the same. When the IGDS reader encounters such an element, it assigns an
igds_type of igds_point. If the IGDS reader encounters a type 3 element
with a different start and end point, it will assign an igds_type of igds_line.
There are no attributes specific to this type of element.
12.6.4 Lines
igds_type: igds_line
Features with their igds_type set to igds_line are stored in and read from
IGDS files in one of three ways, depending on the number of coordinates they have.
3. IGDS type 3 elements with different start and end points are treated as igds_line features by the
FME.
igds_text_string{#} When reading only, this contains the text string of the
#
th
text element in the cell.
Range: Any string
igds_cell_sequence When reading only with IGDS_EXPAND_CELLS set
to yes, this contains a unique number that can be used
to regroup a cell with its component elements.
Number of
Coordinates
IGDS
Element
Type
Description
2 3 If the feature contained exactly two points, then an
IGDS type 3 element is used to store the data if
IGDS_CREATE_LINE_ELEMENTS was yes,
otherwise, a type 4 element will be created.
Between 3 and 101 4 If the coordinates can fit in a single element, then an
IGDS type 4 element is used to store the line.
Attribute Name Contents
12-11 FME Reference Manual Version 2.0
Safe Software Inc. DESIGN FILE READER/WRITER
There are no attributes specific to this type of element.
12.6.5 Shapes
igds_type: igds_shape
Shape features are used in IGDS to represent closed polygons. The first coordinate in
a shape feature must be equal to the last coordinate. Such features are stored in and
read from IGDS files in one of two ways, depending on the number of coordinates in
their boundaries:
There are no attributes specific to this type of element.
12.6.6 Text Nodes
igds_type: igds_text_node
Text nodes correspond to IGDS element type 7. Text node features are point features,
and only have a single coordinate. Normally, text nodes are used to group together
lines of text into a single complex element. However, such text groups are handled by
Greater than 101 12, 4 If the coordinates cannot fit into a single element,
then they are grouped together into a complex line
string element (type 12). This consists of a single
type 12 element, followed by as many type 4
elements as required to hold all the coordinate data.
The type 4 elements have their complex bit turned
on.
Number of
Coordinates
IGDS
Element
Type
Description
Between 3 and 101 6 If the coordinates can fit in a single element, then an
IGDS type 6 element is used to store the shape.
Greater than 101 14, 4 If the coordinates cannot fit into a single element,
then they are grouped together into a complex shape
element (type 14). This consists of a single type 14
element, followed by as many type 4 elements as
required to hold all the coordinate data. The type 4
elements have their complex bit turned on.
Number of
Coordinates
IGDS
Element
Type
Description
DESIGN FILE READER/WRITER Safe Software Inc.
12-12 FME Reference Manual Version 2.0
the igds_multi_text type and not by this type, which is used only for text nodes
with no attached text.
TIP: Free standing text nodes are often used as point features in IGDS files, with the text node number holding
a key to related attribution
Text node elements have the following attributes.
Attribute Name Contents
igds_node_number The node number assigned to the text node.
Range: 0..65535
Default: 0
igds_font The IGDS font number for the text node. For free standing text
nodes, this value is relatively meaningless.
Range: 0..255
Default: 25
igds_rotation The rotation of the text node. The rotation is measured in
degrees counter clockwise up from horizontal. For free standing
text nodes, this value is relatively meaningless.
Range: -360.0..360.0
Default: 0
igds_justification The justification code for the text node.
Range: 0..14
0 is Left Margin/Top
1 is Left Margin/Center
2 is Left Margin/Bottom
3 is Left/Top
4 is Left/Center
5 is Left /Bottom
6 is Center/Top
7 is Center/Center
8 is Center/Bottom
9 is Right/Top
10 is Right/Center
11 is Right/Bottom
12 is Right Margin/Top
13 is Right Margin/Center
14 is Right Margin/Bottom
Default: 5
igds_text_size The text size of the text in the node. The text size is measured in
ground units.
Range: Any real number > 0
Default: 20
rotation
12-13 FME Reference Manual Version 2.0
Safe Software Inc. DESIGN FILE READER/WRITER
12.6.7 Curves
igds_type: igds_curve
Curve features are used in design files to represent smooth bezier curves. Curve
features have four extra points which are used to determine the slope at the starting
and ending points of the curve. These points are not part of the real coordinates of the
feature, and are stored in the attribute list igds_curve_slope{}. The first two
entries in the list define the slope points for the start of the feature, and the last two
define the slope points for the end of the feature. The IGDS reader and writer interpret
the curves coordinates as the points which define the curve. In particular, the reader
does not interpolate points along the curve.
A curve feature has these attributes:
TIP: When a curve feature is reprojected, its slope points are automatically reprojected.
12.6.8 Ellipses
igds_type: igds_ellipse
This geometry type is stored in an IGDS type 15 element. Ellipse features are point
features, and only have a single coordinate. This point serves as the center of the
ellipse. Additional attributes specify the rotation, major axis, and minor axis of the
ellipse.
TIP: The function @Arc() can be used to convert an ellipse to a polygon. This is useful for storing ellipses in
systems which do not support them directly.
Attribute Name Contents
igds_curve_slope{0}.x
igds_curve_slope{0}.y
igds_curve_slope{0}.z
igds_curve_slope{1}.x
igds_curve_slope{1}.y
igds_curve_slope{1}.z
The ground coordinates of the slope points for the
beginning of the feature.
If the design file was two dimensional (2D), then
the .z attributes will not be present.
igds_curve_slope{2}.x
igds_curve_slope{2}.y
igds_curve_slope{2}.z
igds_curve_slope{3}.x
igds_curve_slope{3}.y
igds_curve_slope{3}.z
The ground coordinates of the slope points for the
end of the feature.
If the design file was 2D, then the .z attributes will
not be present.
DESIGN FILE READER/WRITER Safe Software Inc.
12-14 FME Reference Manual Version 2.0
TIP: The primary ellipse axis is not necessarily the longest axis, but rather the one whose orientation is
specification by the rotation value.
12.6.9 Arcs
igds_type: igds_arc
This geometry type is stored in an IGDS type 16 element. Arc features are just like
ellipse features, only two additional angles control the portion of the ellipse boundary
which is drawn.
TIP: The function @Arc() can be used to convert an arc to a linestring. This is useful for storing arcs in systems
which do not support them directly.
Attribute Name Contents
igds_primary_axis The length of the semi-major axis in ground units.
Range: Any real number > 0
Default: No default
igds_secondary_axis The length of the semi-minor axis in ground units.
Range: Any real number > 0
Default: No default
igds_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
rotation
Primary
Axis
Secondary
Axis
Rotation = 90
12-15 FME Reference Manual Version 2.0
Safe Software Inc. DESIGN FILE READER/WRITER
Attribute Name Contents
igds_primary_axis The length of the semi-major axis in ground units.
Range: Any real number > 0
Default: No default
igds_secondary_axis The length of the semi-minor axis in ground units.
Range: Any real number > 0
Default: No default
igds_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: No default
igds_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: Any real number > 0
Default: No default
igds_rotation The rotation of the major axis. The rotation is
measured in degrees counterclockwise up from
horizontal.
Range: -360.0..360.0
Default: 0
Secondary
Axis
Rotation = 90
Start
Angle
= 45
Sweep
Angle
= 135
Primary
Axis
rotation
DESIGN FILE READER/WRITER Safe Software Inc.
12-16 FME Reference Manual Version 2.0
12.6.10 Text Strings
igds_type: igds_text
Text string features correspond to IGDS element type 17. Normally, text strings are
grouped together into a single complex element within Microstation by text nodes.
However, such text groups are handled in the FME by the igds_multi_text
type and not by this type, which is used only for single, free standing text strings. Text
string features are point features, and only have a single coordinate.
TIP: Some applications may use the graphic group field to logically group related text elements together.
Text strings have the following attributes.
TIP: When a text string feature is reprojected, its rotation and text size are also automatically adjusted to be
correct in the new coordinate system.
Attribute Name Contents
igds_text_string The text string to be output.
Range: Any string
Default: No Default
igds_font The IGDS font number for the text string.
Range: 0..255
Default: 25
igds_rotation The rotation of the text string. The rotation is measured in
degrees counter clockwise up from horizontal.
Range: -360.0..360.0
Default: 0
igds_justification The justification code for the text node. See the text node
documentation (subsection 12.6.6) for the mapping of
numbers to alignments.
Range: 0..14
Default: 5 (see the documentation for Text Nodes,
subsection 12.6.6)
igds_text_size The text size of the text. The text size is measured in ground
units.
Range: Any real number > 0
Default: 20
igds_original_
justification
This attribute only applies to text elements read from design
files. It is not used when text elements are written. It contains
the text justification that was used when the text element was
originally placed. However, once placed, all text elements are
stored in the design file using lower left corner (code 5)
justification.
Therefore, all text elements returned by the reader will have
an igds_justification of 5. To examine the original
justification code, this attribute must be used.
Range: 0..14
rotation
12-17 FME Reference Manual Version 2.0
Safe Software Inc. DESIGN FILE READER/WRITER
12.6.11 Multi Text Strings
igds_type: igds_multi_text
Multi text string features correspond to an IGDS text node (element type 7) grouping
together a series of IGDS text elements (element type 17), each of which have their
complex bit turned on. This feature uses the same attribute names as a text node, plus
it has a feature attribute list of text string attributes. The list is called
igds_text_elements{#}, where # starts at 0 and increments for each text
element. The lists item names are identical to the text string features attributes.
TIP: Multi text strings can be used to group together text so that it will be manipulated as a single entity with
Microstation.
Multi text features are point features, and only have a single coordinate. This
coordinate is used when the text node is created. If the feature had no coordinates of
its own, the text node is created with the coordinates of the first text string. The
coordinates for each of the text strings are stored in the FME feature using the
following attribute names.
If a setting for a particular text element is not present in the
igds_text_elements list, then the setting specified for the previous text
element will be used. If the first element does not have some settings specified, then
the corresponding settings will be borrowed from the text node.
For example, the FME feature specified by the below partial transfer specification
would create a text node, followed by two text strings, as a single complex element.
IGDS 32 igds_type igds_multi_text \
igds_node_number 15 \
igds_font 31 \
igds_rotation 0 \
igds_text_size 40 \
igds_color 2 \
igds_justification 1 \
igds_text_elements{0}.igds_font 33 \
Attribute Name Contents
igds_text_elements{#}.x The x coordinate of the #
th
text element.
Range: Any real number
Default: No Default
igds_text_elements{#}.y The y coordinate of the #
th
text element.
Range: Any real number
Default: No Default
igds_text_elements{#}.z The z coordinate of the #
th
text element.
Range: Any real number
Default: 0
DESIGN FILE READER/WRITER Safe Software Inc.
12-18 FME Reference Manual Version 2.0
igds_text_elements{0}.igds_rotation 3.1 \
igds_text_elements{0}.igds_text_size 52 \
igds_text_elements{0}.igds_color 4 \
igds_text_elements{0}.igds_text Hello \
igds_text_elements{0}.x 477556 \
igds_text_elements{0}.y 5360183 \
igds_text_elements{0}.z 20 \
igds_text_elements{1}.igds_text World \
igds_text_elements{1}.x 477556 \
igds_text_elements{1}.y 5359177 \
igds_text_elements{1}.z 20
Note that in this example, the justification code (1) used for the text node would be
propagated to each of the text elements, but that the color used in the text node (2)
would not be used in any of the text elements because the first one set the color to 4.
The in-memory snapshot of the FME feature created by the IGDS writer from this
transfer specification is shown below.
Feature Type: 32
Attribute Name Value
igds_type igds_multi_text
igds_node_number 15
igds_font 31
igds_weight 1
igds_text_size 40
igds_color 2
igds_rotation 0
igds_justification 1
igds_text_elements{0}.igds_text Hello
igds_text_elements{0}.igds_font 33
igds_text_elements{0}.igds_rotation 3.1
igds_text_elements{0}.igds_justification 1
igds_text_elements{0}.igds_text_size 52
igds_text_elements{0}.x 477556
igds_text_elements{0}.y 536018
igds_text_elements{0}.z 20
igds_text_elements{1}.igds_text World
igds_text_elements{1}.igds_font 33
12-19 FME Reference Manual Version 2.0
Safe Software Inc. DESIGN FILE READER/WRITER
12.6.12 Solids
igds_type: igds_solid
Solids correspond to the grouped shapes in MicroStation. Solids consist of polygons
or donut polygons. When a donut polygon is written out as an solid, all holes are
output with the hole bit turned on, and are grouped together with the enclosing
polygon. Groups are created in the design file by creating an unnamed cell header
element, and making each shape in the donut polygon a member of the group.
TIP: Using a solid to output a polygon with no holes is roughly equivalent to using an igds_shape with a fill
linkage. However, the solid will also have the unnamed cell header.
Solids are always filled, and accept an additional parameter to defined the fill color.
Holes within a solid will not be filled with the color.
The IGDS file format imposes a limit on the number of coordinates which can be
present in a solid. This limit is around 16,000 for two dimensional IGDS files, and
around 10,000 for three dimensional IGDS files. If a solid with more than allowable
number of coordinates is encountered, it is rejected and a message to that effect is
logged to the FME logfile.
TIP: Solids will not be filled in MicroStation unless the View Attributes: Fill checkbox is ticked.
Solid elements have the following attributes.
igds_text_elements{1}.igds_rotation 3.1
igds_text_elements{1}.igds_justification 1
igds_text_elements{1}.igds_text_size 52
igds_text_elements{1}.x 477556
igds_text_elements{1}.y 5359177
igds_text_elements{1}.z 20
Coordinates: (477553,5360181,20)
Attribute Name Contents
igds_fill_color The color used to fill the solid.
Range: 0..255
Default: 0
Feature Type: 32
Attribute Name Value
DESIGN FILE READER/WRITER Safe Software Inc.
12-20 FME Reference Manual Version 2.0
12.7 IGDS Mapping File Example
The mapping file below converts data from a shape file to a design file. As features
are written to the design file, they are linked to their attributes with a database linkage.
It also provides an example of the @Lookup and @Relate commands, and uses the
@Area and @Length functions within the RELATION_DEF of the @Relate
command.
LOG_FILENAME fme.log
WRITER_TYPE IGDS
READER_TYPE SHAPE
# Stuff the IGDS Writer needs to know about.
IGDS_DATASET tracts.dgn
IGDS_SEED_FILE zeroseed.2d
# Stuff the SHAPE reader needs to know about.
SHAPE_DATASET
# Filename of the tracts table.
Relate TABLE_LOCATION tractTab tracttab.dbf
#---------------------------------------------------------------
# Macros for IGDS
MACRO fillUserId 65
MACRO fillMagic 67586
#---------------------------------------------------------------
# Color macros -- nice names for an IGDS Color Map
MACRO white 0
MACRO blue 1
MACRO green 2
MACRO red 3
MACRO yellow 4
MACRO magenta 5
MACRO orange 6
MACRO turq 7
MACRO black 8
MACRO grey 9
MACRO darkGreen 114
MACRO cyan 121
MACRO purple 125
MACRO indianRed 83
MACRO baise 84
MACRO medPurple 85
MACRO darkGray 144
MACRO seventies 164
MACRO brown 126
MACRO desktop 159
MACRO nt 95
MACRO bisque 217
12-21 FME Reference Manual Version 2.0
Safe Software Inc. DESIGN FILE READER/WRITER
#---------------------------------------------------------------
# This lookup table maps the county fips number to a color.
Lookup CntyFipsToColorLUT \
035 $(bisque) \
013 $(nt) \
117 $(desktop) \
223 $(brown) \
247 $(seventies) \
077 $(medPurple) \
297 $(baise) \
217 $(darkGreen) \
113 $(orange) \
097 $(turq) \
151 $(purple) \
255 $(cyan) \
057 $(grey) \
063 $(darkGray) \
135 $(magenta) \
067 $(indianRed) \
089 $(blue) \
121 $(red)
# ---------------------------------------------------------------
# The IGDS auxiliary attribute table definition and relation
# definition.
Relate TABLE_DEF tractTab DBF \
I_AREA number(12,3) \
I_AREA2 number(12,5) \
I_PERIM number(12,3) \
I_PERIM2 number(12,5) \
I_TRACT_ID number(11,0) \
I_STATE_FP char(2) \
I_CNTY_FP char(3) \
I_TRACT char(6) \
I_CNTY_TRT char(9) \
I_SQ_MILES number(11,3)
# Note that in the relation definition the functions @Area and
# @Length are used to compute values for the table fields I_AREA2
# and I_PERIM2 when the relation is used to output to the table.
Relate RELATION_DEF tractRelation 1:1 \
TABLE tractTab \
UNIQUE(I_TRACT_ID) \
JOIN I_TRACT_ID TO TRACT_ID \
TRANSFER I_AREA TO AREA \
TRANSFER I_PERIM TO PERIMETER \
TRANSFER I_AREA2 TO @Area() \
TRANSFER I_PERIM2 TO @Length() \
TRANSFER I_TRACT_ID TO TRACT_ \
TRANSFER I_STATE_FP TO STATE_FIPS \
TRANSFER I_CNTY_FP TO CNTY_FIPS \
TRANSFER I_TRACT TO TRACT \
TRANSFER I_CNTY_TRT TO CNTY_TRACT \
TRANSFER I_SQ_MILES TO SQ_MILES
DESIGN FILE READER/WRITER Safe Software Inc.
12-22 FME Reference Manual Version 2.0
# ---------------------------------------------------------------
# The Shape definition
SHAPE_DEF tracts SHAPE_GEOMETRY shape_polygon \
AREA number(12,3) \
PERIMETER number(12,3) \
TRACT_ number(11,0) \
TRACT_ID number(11,0) \
STATE_FIPS char(2) \
CNTY_FIPS char(3) \
TRACT char(6) \
CNTY_TRACT char(9) \
SQ_MILES number(11,3)
# ---------------------------------------------------------------
# Transfer specification for these features
# On the shape side, the @Relate will retrieve values from the IGDS
# attribute table into the Shape feature when shape is the
# destination, and when we are reading from shape is the source
# the @Relate will output values to the IGDS attribute table.
#
# Notice that the %tract_id transfer variable is stored in both the
# graphic_group and the linkage_2_key attributes.
# This allows the tract_id to be easily viewed in microstation
SHAPE tracts \
TRACT_ID %tract_id \
CNTY_FIPS %fips \
@Relate(tractRelation, DestReadSrcWrite)
IGDS 32 \
igds_type igds_shape \
igds_color $(green) \
igds_weight 1 \
igds_graphic_group %tract_id \
igds_linkage{0}.type user \
igds_linkage{0}.userId $(fillUserId) \
igds_linkage{0}.long{0} $(fillMagic) \
igds_linkage{0}.long{1} @Lookup(CntyFipsToColorLUT,%fips) \
igds_linkage{1}.type dbase \
igds_linkage{1}.key %tract_id
TIP: Note how the %tract_id transfer variable is assigned to two different attributes.
13-1 FME Reference Manual Version 2.0
13 DIGITAL LINE GRAPH READER
The Digital Line Graph (DLG) reader provides the FME with the ability to
import Level 3 DLG data and export it to any of the FME output formats.
DLG is a published ASCII format developed by the United States Geological
Survey (USGS) Federal Agency and is intended to assist in data exchange
with the National Digital Cartographic Data Base (NDCDB).
The DLG reader supports all three distinct types of DLG data:
large-scale DLG data (1:24,000-scale)
intermediate-scale DLG (1:100,000-scale)
small-scale DLG data (1:2,000,000-scale)
The three scales of DLG data are physically formatted into files in one of
these ways: standard, optional, and graphics formats. The FME supports both
the standard and the optional DLG distribution formats. However, the
graphics format is not supported. Most DLG data is distributed in the optional
format.
13.1 Overview
DLG data files consist of ASCII fixed field records. The records may or may
not be stored with embedded carriage returns or end of line markers. The
intelligently determines the end of each record, and interprets files with or
without explicit end of record markers.
DIGITAL LINE GRAPH READER Safe Software Inc.
13-2 FME Reference Manual Version 2.0
The DLG file structure was designed to accommodate all categories of spatial data
represented on a conventional line map. Node, line, and area data types are present
within the DLG format, along with linkages and attribute codes.
Linkages are references to other features within the same DLG dataset, used in a
variety of contexts.
DLG files do not explicitly store attribute values but use a feature coding approach in
which unique feature codes are assigned to the different types of features stored
within the dataset. Each geometric entity present in a DLG file may be assigned major
and minor attribute codes which always appear as a pair. Together these codes often
form complex relationships to assign specific attributes for each feature. The attribute
coding scheme is designed to accommodate basic cartographic data categories such
as hypsography, hydrography, or political and cultural features, as well as additional
thematic data categories. The FME supports a maximum of 12 attribute code pairs per
feature.
The FME looks for an extension of either .dlg or .opt for the input DLG files, but
accepts any DLG file as input regardless of filename or extension.
Although mapping files may be created from scratch to work with the features as
presented directly by the DLG reader, starting with an FME generated mapping file
provides an easy way to harness the rich semantic interpretation of all attribute codes
and linkages built into the FME distribution. This section will first outline the features
and attributes produced directly by the DLG reader. These features and attributes
produced by using an FME generated mapping file are presented at the end of this
section.
13.2 Reader Overview
The DLG reader simply opens the input file and immediately starts reading features
and 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 by the DLG reader has its feature type set to one of the
following: dlg_point, dlg_line, or dlg_area.
13-3 FME Reference Manual Version 2.0
Safe Software Inc. DIGITAL LINE GRAPH READER
13.2.1 Reader Keywords
The following table lists the keywords processed by the DLG reader. The suffixes
shown are prefixed by the current <ReaderKeyword> in a mapping file. By
default, the <ReaderKeyword> for the DLG reader is DLG.
13.2.1.1Dataset
The value for this keyword is the file containing the DLG dataset to be read. A typical
mapping file fragment specifying an input DLG dataset looks like:
DLG_DATASET /usr/data/dlg/HYF3.dlg
13.2.2 Feature Representation
DLG features consist of geometry, linkages, and attribute code information. All DLG
FME features contain the dlg_type attribute, which identifies the geometric type
as well as several other standard attributes and are listed in the following table.
Keyword Suffix Value Required/
Optional
DATASET Contains the filename of the input DLG dataset. Required
Attribute Name Contents
dlg_type The DLG geometric type of this entity.
Range: dlg_point|
dlg_line|
dlg_area
Default: No default
dlg_element_number The elements internal identification number.
The numbers are unique, positive, and
sequential within each element type.
Range: 1 - 32000
dlg_record_type The character element type of the feature.
Valid values include:
N = Node Element
L = Line Element
A = Area Element
dlg_num_text_characters Number of pairs of text characters attached to
the feature.
Although this field is present within the DLG
format, it is not currently used.
Range: 1 - 32000
DIGITAL LINE GRAPH READER Safe Software Inc.
13-4 FME Reference Manual Version 2.0
dlg_linkage{#} A list of linkages. These values refer to the
features by their dlg_element_number.
These linkages have different uses depending
on their context. For example, a linkage list on
an area feature refers to the line features that
form the boundary of the area.
Note: For area features, linkages with a value
of zero are not included in this list.
Range: 1 - 32000
dlg_num_attribute_codes Number of attribute codes attached to the
feature.
Range: 1 - 32000
dlg_attribute_code{#}.major A list of major attribute codes. This list will
have a maximum of 12 entries.
Range: 0 - 999
dlg_attribute_code{#}.minor A list of minor attribute codes. This list will
have a maximum of 12 entries.
Range: 0 - 9999
dlg_attribute_code{#}.
padmajor
This list is identical to the
dlg_attribute_code{#}.major list
except all values in this list are padded with
zeros to exactly three character places. For
example, if
dlg_attribute_code{0}.major was 90,
dlg_attribute_code{0}.padmajor
would be 090.
Range: 000 - 999
dlg_attribute_code{#}.
padminor
This list is identical to the
dlg_attribute_code{#}.minor list
except all values in this list are padded with
zeros to exactly four character places. For
example, if
dlg_attribute_code{0}.minor was 214,
dlg_attribute_code{0}.padminor
would be 0214.
Range: 0000 - 9999
dlg_attribute_code{#}.
partminor1
This list contains the first character of the
corresponding entry in the
dlg_attribute_code{#}.padminor list.
For example, if
dlg_attribute_code{0}.padminor was
0214,
dlg_attribute_code{0}.partminor1
would be 0.
Range: 0 - 9
Attribute Name Contents
13-5 FME Reference Manual Version 2.0
Safe Software Inc. DIGITAL LINE GRAPH READER
Depending on the geometric type, the feature may contain additional feature coding
attributes specific to the geometric type. These are described in subsequent sections.
13.2.3 Points
dlg_type: dlg_point
DLG point features specify a single x and y coordinate. While the DLG format does
allow for points to be defined as degenerate lineslines containing two identical
pointsthe DLG reader converts these into standard points with a single set of
coordinates.
dlg_attribute_code{#}.
partminor2
This list contains the second character of the
corresponding entry in the
dlg_attribute_code{#}.padminor list.
For example, if
dlg_attribute_code{0}.padminor was
0214,
dlg_attribute_code{0}.partminor2
would be 2.
Range: 0 - 9
dlg_attribute_code{#}.
partminor34
This list contains the third and fourth
characters of the corresponding entry in the
dlg_attribute_code{#}.padminor list.
For example, if
dlg_attribute_code{0}.padminor was
0214,
dlg_attribute_code{0}.partminor34
would be 14.
Range: 0 - 9
dlg_code_list A text string containing all major and minor
codes assigned to this feature, in the following
format:
Range: <null> | <code list>
<code list> = (<major code>-
<minor code>
[,<major code>-<minor
code>]*)
For example, if the feature had major and
minor code pairs of 180/201, 180/605, and
180/210, the string value of dlg_code_list
attribute would be (180-201,180-605,180-
210)
Attribute Name Contents
DIGITAL LINE GRAPH READER Safe Software Inc.
13-6 FME Reference Manual Version 2.0
There is one attribute specific to point features.
13.2.4 Lines
dlg_type: dlg_line
DLG line features represent two dimensional linear features.
There are several attributes specific to line features.
Field Name Description
dlg_num_linkage_records The number of linkages associated with this
feature. This number indicates the number of
entries in the dlg_linkage{#} attribute list.
Range: 1 - 32000
Field Name Description
dlg_num_coordinates The number of coordinates associated with
this line feature.
Range: 1 - 32000
dlg_starting_node This number refers a node feature which is
located at the initial point of the line. The value
refers to the feature by its
dlg_element_number.
Range: 1 - 32000
dlg_ending_node This number refers a node feature which is
located at the final point of the line. The value
refers to the feature by its
dlg_element_number.
Range: 1 - 32000
dlg_left_area This number refers an area feature which is
located to the immediate left of the line. The
value refers to the feature by its
dlg_element_number.
Range: 1 - 32000
dlg_right_area This number refers an area feature which is
located to the immediate right of the line. The
value refers to the feature by its
dlg_element_number.
Range: 1 - 32000
13-7 FME Reference Manual Version 2.0
Safe Software Inc. DIGITAL LINE GRAPH READER
13.2.5 Areas
dlg_type: dlg_area
DLG area features represent polygonal features in 2D. These features are actually
point features with one x and one y coordinate. This coordinate location may have
little utility, as the boundary of the area is specified indirectly through the use of the
dlg_linkage{} list attribute. Each entry in this list refers to a dlg_line which,
together, form the boundary of the area. Additional attributes assigned to this area are
attached to the original dlg_area feature.
There are several attributes specific to area features.
13.3 Features Created by Generated DLG Mapping Files
The attribute and geometric information within DLG datasets are encoded indirectly
with major, minor, and linkage codes. The FME generates mapping files that can
interpret all of these codes. The suggested method of creating custom mapping files
for reading DLG data is to start with a generated mapping file. This provides an easy
way to harness the rich semantic interpretation of all attribute codes and linkages built
into the FME distribution. The following information pertains to the features and
attributes produced by the mapping files generated to read DLG data.
13.3.1 Feature Representation
The DLG features produced by the generated mapping file consist of geometry and
explicit attribute information. Each feature that has passed through all of the factories
in the generated mapping file has its feature type set to one of the following: HP, HY,
SC, NV, BD, SM, RD, RR, MT, MS, or PL. These features correspond to the
Field Name Description
dlg_num_islands The number of islands or holes within this area
feature.
Range: 1 - 32000
dlg_num_linkage_records The number of entries in the
dlg_linkage{#} list attribute. This list
contains references to the line features that
define the border of the area. (Note: linkages
with a value of zero are not included in this
count.)
Range: 1 - 32000
dlg_num_points_area_list The number of coordinates associated with the
linear features necessary to define the border
of this area feature.
Range: 1 - 32000
DIGITAL LINE GRAPH READER Safe Software Inc.
13-8 FME Reference Manual Version 2.0
category abbreviations as outlined in the DLG standardssee the next table. The
geometry of each feature is appropriate to the dlg_type: dlg_point features
have a single coordinate pair, dlg_line features contain multiple coordinates, and
dlg_area features define closed polygons with holes where appropriate.
Table 13-1 DLG Categories
All features share several attributes however, the feature will contain additional
feature coding specific to the feature type. These are described in subsequent
sections. All features tagged with major and minor codes of zero, indicating an
outside area, are deleted.
13.3.2 DLG Attributes
The following table lists the different DLG attributes attached to every feature which
has passed through the generated mapping file.
Name in Full Abbreviation
Hypsography HP
Hydrography HY
Vegetative Surface Cover SC
Non-Vegetative Features NV
Boundaries BD
Survey Control and Markers SM
Roads and Trails RD
Railroads RR
Pipelines, Transmission Lines, and
Miscellaneous Transportation Features
MT
Man-made Features MS
U.S. Public Land Survey System PL
Field Name Description
dlg_element_number The elements internal identification number.
The numbers are unique, positive, and
sequential within each element type.
Range: 1 - 32000
13-9 FME Reference Manual Version 2.0
Safe Software Inc. DIGITAL LINE GRAPH READER
13.3.3 Hypsography
FEATURE_TYPE: HP
This category of data consists of information on topographic reliefprimarily
contour dataand supplementary spot elevations.
There is one attribute specific to Hypsography features.
dlg_type The DLG geometric type of this entity.
Range: dlg_point|
dlg_line|
dlg_area
Default: No default
dlg_code_list A text string containing all Major and Minor
codes assigned to this feature, in the following
format:
Range: <null> | <code list>
<code list> = (<major code>-
<minor code>
[,<major code>-<minor
code>]*)
For example, if the feature had major and
minor code pairs of 180/201, 180/605, and
180/210, the string value of dlg_code_list
attribute would be (180-201,180-605,180-
210)
category The full length text string of the features
category, as defined in the DLG standards.
(See Table 13-1.)
description A text string containing all descriptive terms
assigned to the feature through the Major and
Minor codes. The source of these strings are
the DLG standards documentation. Each
description is separated by a semicolon.
For example, if the feature had major and
minor code pairs of 180/201, 180/605, and
180/210, the string value of description
would be Railroad; Underpassing; Arbitrary
line extension [Code Deleted 07/95]
coincidentFeature If not null, this value indicates the other feature
it is coincident with. The value refers to the
coincident feature by its
dlg_element_number.
Range: 1 - 32000
Field Name Description
DIGITAL LINE GRAPH READER Safe Software Inc.
13-10 FME Reference Manual Version 2.0
13.3.4 Hydrography
FEATURE_TYPE: HY
This category of data consists of all flowing water, standing water, and wetlands.
There are several attributes specific to Hydrography features.
13.3.5 Vegetative Surface Cover
FEATURE_TYPE: SC
This category of data consists of information about vegetative surface cover such as
woods, scrub, orchards, and vineyards. Vegetative features associated with wetlands,
such as marshes and swamps, are collected under Hydrography.
There are no attributes specific to Vegetative Surface Cover features.
13.3.6 Non-Vegetative Features
FEATURE_TYPE: NV
This category of data consists of information about the natural surface of the Earth as
symbolized on the map such as lava, sand, and gravel features. This category is not
all inclusive, as other non-vegetative surface features, such as glaciers, are found in
the category of Hydrography.
There are no attributes specific to Non-Vegetative Features.
Field Name Description
elevation The elevation of the feature. The
description attribute indicates whether the
units are feet or meters.
Range: -99999999.9 - +99999999.
Field Name Description
elevation The elevation of the feature. The
description attribute indicates whether the
units are feet or meters.
Range: -99999999.9 - +99999999.9
rotationAngle The angle of clockwise rotation of the feature.
13-11 FME Reference Manual Version 2.0
Safe Software Inc. DIGITAL LINE GRAPH READER
13.3.7 Boundaries
FEATURE_TYPE: BD
This category of data consists of:
1. political boundaries that identify States, counties, cities, and other
municipalities, and
2. administrative boundaries that identify areas such as national and State forests.
Political and administrative boundaries are always collected as a single data set.
There are several attributes specific to Boundaries features.
13.3.8 Survey Control and Markers
FEATURE_TYPE: SM
This category of data consists of information about points of established horizontal
position and third order or better elevations used as fixed references in positioning
and correlating map features.
There are several attributes specific to Survey Control and Markers features.
Field Name Description
state The full name of the American state or the
state equivalent.
Range: ALABAMA - VIRGIN
ISLANDS
county The full name of an American county or a
county equivalent for all states.
Range: Abbeville - Ziebach
township The full name of an American civil township
or a civil township equivalent for all states.
Range: Aasu - Zwolle
population1990 The 1990 complete-count population of the
American county or the county equivalent.
monument The alphanumeric monument number of the
feature.
DIGITAL LINE GRAPH READER Safe Software Inc.
13-12 FME Reference Manual Version 2.0
13.3.9 Roads and Trails
FEATURE_TYPE: RD
This category of data includes major transportation systems.
There are several attributes specific to Roads and Trails features.
13.3.10 Railroads
FEATURE_TYPE: RR
This category of data includes major transportation systems.
There are several attributes specific to Railroads features.
Field Name Description
elevation The elevation of the feature. The description
attribute indicates whether the units are feet or
meters.
Range: -99999999.9 - +99999999.9
state The full name of the American state or the state
equivalent.
Range: ALABAMA - VIRGIN ISLANDS
county The full name of an American county or a county
equivalent for all states.
Range: Abbeville - Ziebach
Field Name Description
numberOfLanes The number of lanes the road or trail has.
routeNumber The alphanumeric route number or the road or the
trail.
routeType This attribute indicates whether the route is an
Interstate, U.S., State, County, Reservation, Park, or
Military Route.
Field Name Description
numberOfTracks The number of tracks the railroad has.
rotationAngle The angle of clockwise rotation of the feature.
13-13 FME Reference Manual Version 2.0
Safe Software Inc. DIGITAL LINE GRAPH READER
13.3.11 Pipelines, Transmission Lines, and Miscellaneous Transportation
Features
FEATURE_TYPE: MT
This category of data includes major transportation systems.
There is one attribute specific to Pipelines, Transmission Lines, and Miscellaneous
Transportation Features.
13.3.12 Man-made Features
FEATURE_TYPE: MS
This category of data includes cultural features not included in the other major data
categories, such as buildings and other related industrial, commercial, and residential
features.
There are several attributes specific to Man-made Features.
13.3.13 U.S. Public Land Survey System
FEATURE_TYPE: PL
This category of data describes the rectangular system of land surveys which is
administered by the U.S. Bureau of Land Management. Public Land Survey System
(PLSS) data exist only for areas falling solely or in part within the States which were
formed from the public domain. The PLSS subdivides the public domain and
represents property boundaries or references to property boundaries. These DLG data
are not intended to be official or authoritative. They are presented as cartographic
reference information. The only legal basis for determining land boundaries remains
the original survey.
Field Name Description
rotationAngle The angle of clockwise rotation of the feature.
Field Name Description
featureWidth Width in mils of feature to scale.
rotationAngle The angle of clockwise rotation of the feature.
DIGITAL LINE GRAPH READER Safe Software Inc.
13-14 FME Reference Manual Version 2.0
There are several attributes specific to U.S. Public Land Survey System features.
13.4 Example
The example below shows an FME mapping file used to translate some Hypsography
features from the DLG format into MIF/MID format. The mapping file defines the
dataset location, and gives the correlation lines between DLG features and MIF/MID.
This mapping file was created by first generating a mapping file, then editing it. All
MAPINFO macros, MIF_DEF and correlation lines were removed from the
generated mapping file except for those dealing with the Hypsography category. A
factory at the bottom of the file was added to generalize all linear features with more
than 10 points to a 5 meter tolerance.
#
=========================================================================
#
# This mapping file was automatically generated by the FME
# on 05/21/97 13:29:28 for lossless translation between DLG and MIF.
#
# You may edit this mapping file to customize its operation. Comments are
# placed throughout to assist you.
#
Field Name Description
section The alphanumeric Section Identifier number.
township Township Identifier numbers north and south of
baseline, including fractions.
Examples: 101 South, 23 1/2 North
range Range Identifier numbers east and west of principal
meridian including fractions, duplicate, and
triplicate notification.
Examples: 5 East, 79 1/2 West, 47 West,
duplicate to north or east of the original township
origin Full text string identifying the origin of the survey,
including township, state, and date.
Examples: Boise - PM ID 1867, Ohio River -
OH OH,IN 1785
nonsectionID Full text string of the Non-Section Identifier.
Examples: 51, W, San Ignacio de la Canoa
grant in Arizona, Pueblo of Santa Ana grant in
New Mexico
monument Land grant corner, location, or mineral monument
number.
Range: 0000 - 9999
13-15 FME Reference Manual Version 2.0
Safe Software Inc. DIGITAL LINE GRAPH READER
# Modification History:
#
# Name Date Description
# ================= ======== =========================================
# Safe Software 05/21/97 Removed all lines except for Hypsography,
# removed MAPINFO macros, and added a
# Factory to generalize lines.
#
#
=========================================================================
#
=========================================================================
# The following line defines the title presented to the user when this
# mapping file is run through the FME GUI. You may modify this
# if a more meaningful title would be appropriate.
GUI TITLE DLG to MIF Translation
#
=========================================================================
# The following line names the log file to which useful statistics about
# the translation will be written. This line can be uncommented and
# updated if you do wish to keep these statistics.
# LOG_FILENAME translation.log
#
=========================================================================
# The following line instructs the FME to log any features that do not
# match any of the source feature patterns listed further down in
# this file. If you are modifying this mapping file, this will be
# useful to describe to you exactly which features you are losing
# during translation, if the statistics indicate that features are
# not being correlated or grouped. Uncorrelated features do not
# match any source specification, ungrouped features do not have
# any corresponding _DEF line.
# FME_DEBUG UNGROUPED UNCORRELATED
#
=========================================================================
# The following two lines define the type of reader and writer to be
# used for this translation. If you want to translate your data
# back into its original format, you may make a copy of this file
# and switch the reader and writer types. If you rerun the FME, you
# will get your original data back again (together with any modifications
# you made in the meantime). Note that several formats are NOT
# bi-directional (for example, GIF can only be used as a WRITER)
# so a reverse translation may not always be possible.
READER_TYPE DLG
WRITER_TYPE MIF
#
=========================================================================
# The following GUI line prompts for a DLG file to be used as the
# source of the translation.
# The user input is stored in a MACRO, which is then used to define
# the dataset to be read.

GUI FILENAME SourceDataset DLG_FILES(*.dlg)|*.dlg|All_files(*.*)|*.*
Source DLG File:
DIGITAL LINE GRAPH READER Safe Software Inc.
13-16 FME Reference Manual Version 2.0
#
=========================================================================
# This factory will resolve all the links from each area feature
# to the surrounding linework, and form polygons.

FACTORY_DEF DLG ReferenceFactory \
INPUT REFERENCEE FEATURE_TYPE dlg_line \
INPUT REFERENCER FEATURE_TYPE dlg_area \
REFERENCEE_FIELDS dlg_element_number \
REFERENCER_FIELDS dlg_linkage{} \
REFERENCE_INFO GEOMETRY \
OUTPUT COMPLETE FEATURE_TYPE * \
OUTPUT INCOMPLETE FEATURE_TYPE Incomplete \
OUTPUT REFERENCED FEATURE_TYPE * \
OUTPUT UNREFERENCED FEATURE_TYPE *

INCLUDE $(FME_HOME)/dlg/dlg_codes.fmi
#
=========================================================================
# This factory scans all area features and tests to see if
# they are Outside Areas by checking the dlg_code_list attribute.
# (A Major and Minor code pair of 0-0 indicates an Outside Area.)
# These areas are removed and all other areas are left unchanged.
FACTORY_DEF DLG TestFactory \
INPUT FEATURE_TYPE * dlg_type dlg_area \
TEST &dlg_code_list != (0-0) \
OUTPUT PASSED FEATURE_TYPE *

DLG_DATASET $(SourceDataset)
#
=========================================================================
# The following GUI line prompts for a directory to be used as the
# the destination for the MIF/MID files.
# The user input is stored in a macro, which is then used to define
# the dataset to be written.

GUI DIRNAME DestDataset Destination MIF/MID Directory:

MIF_DATASET $(DestDataset)
#
=========================================================================
# The main body of the mapping file starts here. Each of the
# _DEF lines describes the data model of the particular feature
# type, and the correlation lines describe how the feature is
# transformed from the source type to the destination type.
# You may edit the following lines to add or remove attributes, change
# attribute definitions, or invoke other FME functions as the
# features are translated.
#
=========================================================================
#
=========================================================================
MIF_DEF HP \
category char(100) \
description char(128) \
elevation decimal(10,1) \
dlg_element_number decimal(11,7) \
dlg_code_list char(101) \
coincidentFeature decimal(4,0) \
dlg_type char(10)
13-17 FME Reference Manual Version 2.0
Safe Software Inc. DIGITAL LINE GRAPH READER
DLG HP \
dlg_type dlg_point \
category %category \
description %description \
elevation %elevation \
dlg_element_number %dlg_element_number \
dlg_code_list %dlg_code_list \
coincidentFeature %coincidentfeature \
dlg_type %dlg_type
MIF HP \
mif_type mif_point \
category %category \
description %description \
elevation %elevation \
dlg_element_number %dlg_element_number \
dlg_code_list %dlg_code_list \
coincidentFeature %coincidentfeature \
dlg_type %dlg_type
DLG HP \
dlg_type dlg_line \
category %category \
description %description \
elevation %elevation \
dlg_element_number %dlg_element_number \
dlg_code_list %dlg_code_list \
coincidentFeature %coincidentfeature \
dlg_type %dlg_type
MIF HP \
mif_type mif_polyline \
category %category \
description %description \
elevation %elevation \
dlg_element_number %dlg_element_number \
dlg_code_list %dlg_code_list \
coincidentFeature %coincidentfeature \
dlg_type %dlg_type
DLG HP \
dlg_type dlg_area \
category %category \
description %description \
elevation %elevation \
dlg_element_number %dlg_element_number \
dlg_code_list %dlg_code_list \
coincidentFeature %coincidentfeature \
dlg_type %dlg_type
MIF HP \
mif_type mif_region \
category %category \
description %description \
elevation %elevation \
dlg_element_number %dlg_element_number \
dlg_code_list %dlg_code_list \
coincidentFeature %coincidentfeature \
dlg_type %dlg_type
DIGITAL LINE GRAPH READER Safe Software Inc.
13-18 FME Reference Manual Version 2.0
#
# This factory was added to the bottom of the generated
# mapping file.
#
# This factory scans all linear features and tests to see if
# they have more than 10 points. These lines are generalized
# to a 5 meter tolerance. All other lines are left unchanged.
FACTORY_DEF DLG TestFactory \
INPUT FEATURE_TYPE * dlg_type dlg_line \
TEST @NumCoords() > 10 \
OUTPUT PASSED FEATURE_TYPE * @Generalize(Douglas,5) \
OUTPUT FAILED FEATURE_TYPE * \
14-1 FME Reference Manual Version 2.0
14 ESRI ARCINFO EXPORT
FORMAT (E00) READER
The E00 reader provides the FME with the capability to read option 0
(uncompressed) ArcInfo Export (E00) files. Support for compressed E00 files
is not provided.
14.1 Overview
A single E00 file defines a complete ArcInfo coverage. The file itself is
actually an archive of several smaller files, referred to as subfiles. Some of
these subfiles have fixed names which do not vary from coverage to coverage,
and follow a predefined data format. These are referred to as the standard
subfiles.
The remainder of the subfiles contained within an E00 are the info files. These
files may contain user-defined attributes, and have names which vary from
coverage to coverage. The ways in which the names vary are discussed in the
subsection titled Info Files.
No support for writing E00 files is available at this time.
ESRI ARCINFO EXPORT FORMAT (E00) READER Safe Software Inc.
14-2 FME Reference Manual Version 2.0
14.2 Reader Keywords
The E00 reader processes the keyword <ReaderKeyword>_DATASET, where
<ReaderKeyword> is the keyword assigned to the E00 reader. By default, the
reader keyword for E00 is E00.
The <ReaderKeyword>_DATASET keyword specifies the dataset to be read by
the E00 reader. This is the name of the E00 file, including the .e00 suffix.
There are no other keywords processed by the E00 reader, meaning there are no DEF
lines for E00 features. The features obtained from the specified dataset take the form
described in the remainder of this chapter.
14.3 Feature Representation
This subsection discusses the way geometry and attributes are defined on features
extracted from various files within an E00 file. There is quite a difference between
the features that the E00 reader emits, and those formed from the generic,
automatically-generated mapping file. This discussion focuses primarily on the raw
output from the E00 reader; subsection 14.5, titled Generated Mapping Files,
provides a description of the feature the generated mapping file creates.
14.3.1 Geometry Composition
There are essentially four types of geometry defined in E00 files:
arcs (lines)
points
polygons
text
The geometries are formed by forming relations between certain standard subfiles
and certain info files. The reader itself does not form these relations, but provides the
attributes on the features allowing the mapping file to form the relations.
Automatically generated mapping files form the necessary joins between the subfiles
and the info files, and are a good starting point when creating custom mapping files
to read E00 data. A description of the features output from automatically generated
mapping files is given in subsection14.5 titled Generated Mapping Files.
The following table summarizes the geometry types and lists the additional attributes
required to fully define the geometry, as is the case for text features.
14-3 FME Reference Manual Version 2.0
Safe Software Inc. ESRI ARCINFO EXPORT FORMAT (E00) READER
14.3.2 Feature Types
The features emitted from the E00 reader have a feature type dependent on the subfile
or the info file from which the feature originated. The following table summarizes the
feature types generated for each subfile. If a subfile name in the table below contains
an asterisk, then it is really a pattern to match info file names. This convention is
required because the names of info files vary from coverage to coverage. The +
symbol is used for an alternate asterisk for files containing two wildcard expressions.
Therefore, the info file defining text attributes for the ERR annotation layer of the
HYDR_SUR coverage is named HYDR_SUR.TATERR, and is referred to as *.TAT+
in the following table. References in the rest of the table row expand * to HYDR_SUR
and + to ERR.
Geometry Type Description Additional Attributes
Required
e00_arc A string of geographic points that does not
join or cross with itself. Features read from
the ARC subfile contain arcs as their
geometry.
None
e00_poly A solid area, with an outer boundary and zero
or more holes. No features is given a polygon
geometry by the reader. They must be formed
by factories in the mapping file.
None
e00_point A simple (x,y) coordinate. The E00 reader
creates points for features read from CNT and
LAB standard subfiles.
None
e00_text Defines annotation text at a particular
location, with a rotation measured in degrees
counter-clockwise from the horizontal and
text height measured in ground units. The
geometry portion of a text feature is the single
(x,y) point that defines its position.
e00_text_string
e00_rotation
e00_text_height
Subfile Name Feature Type Geometry Additional Attributes
ARC e00_arcdef e00_arc E00_FEAT_ROLE = e00_arc_def
LPOLY = <id of left polygon>
RPOLY = <id of right polygon>
FNODE = <id of start node>
TNODE = <id of end node>
cover_id = <id of arc in coverage>
CNT e00_centroid e00_point E00_FEAT_ROLE = e00_poly_cnt
ESRI ARCINFO EXPORT FORMAT (E00) READER Safe Software Inc.
14-4 FME Reference Manual Version 2.0
LAB e00_label e00_point E00_FEAT_ROLE = e00_label
poly_id = <id of polygon containing label>
boundBoxMin.x = <min x of bounding box>
boundBoxMin.y = <min y of bounding box>
boundBoxMax.x = <max x of bounding box>
boundBoxMax.y = <max y of bounding box>
LOG
PAL e00_polyarc None E00_FEAT_ROLE = e00_poly_arc
arcnum{n} = <record number of ARC record
for segment #n>
arc{n}.arcnum = <record number of ARC
record for segment #n>
arc{n}.fnode = <start node of ARC record
for segment #n>
arc{n}.lpoly = <left polygon id of ARC
record for segment #n>
boundBox.minX = <min x coordinate of
bounding box>
boundBox.minY = <min y coordinate of
bounding box>
boundBox.maxX = <max x coordinate of
bounding box>
boundBox.maxY = <max y coordinate of
bounding box>
PRJ e00_
projection
None E00_FEAT_ROLE = e00_proj
datum = <Name of datum>
projection = <Name of projection>
units = <Unit type>
xshift = <Shift in x coordinate>
yshift = <Shift in y coordinate>
zunits = <YES/NO>
zone = <UTM zone number>
unknown_param{n}.name = <name of non-
standard parameter #n>
unknown_param{n}.value = <value of non-
standard parameter #n>
TOL e00_
tolerance
None E00_FEAT_ROLE = e00_tolerance
name = <name of tolerance type>
id = <numeric id of tolerance type>
state = <state of tolerance>
value = <value of tolerance>
(See the subsection Tolerances for a description of tolerance
records.)
TXT e00_text e00_text E00_FEAT_ROLE = e00_text_def
e00_anno_name =
e00_anno_id = <record number within
TXT file>
<Attributes for text geometry>
(See the Text Representation subsection for a discussion about
text geometry.
Subfile Name Feature Type Geometry Additional Attributes
14-5 FME Reference Manual Version 2.0
Safe Software Inc. ESRI ARCINFO EXPORT FORMAT (E00) READER
TX6 e00_text e00_text E00_FEAT_ROLE = e00_text_def
e00_anno_name = <name of anno section>
e00_anno_id = <position within anno
section>
parameter{} = <unnamed TX6 parameters>
<Attributes for text geometry>
(See the Text Representation subsection for a discussion about
text geometry.
e00_textarrow e00_arc E00_FEAT_ROLE = e00_text_arrow
e00_anno_name = <name of anno section>
e00_anno_id = <position within anno
section>
LNK LNK e00_point E00_FEAT_ROLE = LNK
*.AAT *_arcattr None E00_FEAT_ROLE = e00_arc_attr
FNODE_ = <Start node cover#>
TNODE_ = <End node cover#>
LPOLY_ = <Left polygon cover#>
RPOLY_ = <Right polygon cover#>
*_ID = <arc identifier>
*# = <coverage # of arc>
LENGTH = <length of arc>
<User-defined attributes>
*.BND *_bounds None E00_FEAT_ROLE = e00_bounds
XMIN = <min x of bounding box>
YMIN = <min y of bounding box>
XMAX = <max x of bounding box>
YMAX = <max y of bounding box>
*.PAT *_polyattr None E00_FEAT_ROLE = e00_poly_attr
AREA = <area of polygon>
PERIMETER = <perimeter of polygon>
*_ID = <id of polygon>
*# = <coverage # of polygon>
<User-defined attributes>
*_pointattr None E00_FEAT_ROLE = e00_point_attr
AREA = 0.0
PERIMETER = 0.0
*_ID = <id of point>
*# = <coverage # of point>
<User-defined attributes>
*.TIC *_tic None E00_FEAT_ROLE = e00_tic_point
IDTIC = <TIC point identifier>
XTIC = <TIC point x coordinate>
YTIC = <TIC point y coordinate>
*.TAT+ *_+_textattr None E00_FEAT_ROLE = e00_text_attr
e00_anno_name = <name of annotation layer>
*# = <coverage number for text>
Subfile Name Feature Type Geometry Additional Attributes
ESRI ARCINFO EXPORT FORMAT (E00) READER Safe Software Inc.
14-6 FME Reference Manual Version 2.0
In addition to the attributes shown in this table, all features have an attribute named
E00_RECORD_NUM, whose value corresponds to the position within the subfile of
the record defining the feature. The record numbers start at 1 for each file, and are
incremented for each record. This number provides the positional information
required to define the relationships between certain geometries and their attributes.
Note that the numbering of the text features is somewhat special. See the Text
Representation subsection for further details. Note that the features of most feature
types also contain an E00_FEAT_ROLE attribute, which defines the role of the
feature within the coverage. This is required to make it easier to create a generic
mapping file, when different files processed by that mapping file might have different
info file names. For example, the file BART.E00 might have an info file named
BART.TIC where JOSIE.E00 has an info file named JOSIE.TIC. The features
emitted for these two info files would have a type of BART_tic and JOSIE_tic,
respectively, but the features for both info files would have the value of
e00_tic_point for their E00_FEAT_ROLE attribute. The role is given to
features from the standard subfiles, as well as the info files which have one of the
known suffixes .AAT, .BND, .PAT, .TIC, .TAT*.
If features from a subfile have a particular type of geometry, then they will have an
attribute named e00_type, whose value is the geometry type. For example, features
from the ARC subfile will have line geometry attached, and will have an e00_type
attribute with the value e00_arc.
14.3.3 Text Representation
The main geometry for text features are defined from records in the TX6 or TXT
subfiles of the E00 coverage. This geometry consists of a text string, a location at
which to draw the text, and optionally a string of points that form a curved line along
which to place the characters. Additionally, text features from the TX6 subfile might
have arrows associated with them.
When these features are read into the FME, the form changes slightly. Since the FME
does not currently support text along a line, the start and end points of the text line are
used to compute the average rotation of the characters, and the first point in the line
becomes the text's position. The text feature's geometry is a point which defines the
position, along with the following attributes to define the rest of the feature.
*.XCODE *_textattr None E00_FEAT_ROLE = e00_text_attr
e00_anno_name =
*# = <coverage number for text>
*.+ *.+ None E00_FEAT_ROLE = .+
<User-defined attributes>
Subfile Name Feature Type Geometry Additional Attributes
14-7 FME Reference Manual Version 2.0
Safe Software Inc. ESRI ARCINFO EXPORT FORMAT (E00) READER
The contents of a TX6 subfile within an E00 coverage may contain annotation in
several different annotation layers. Each feature belongs to one annotation layer, and
this layers name is contained in the features e00_anno_name attribute. The
features within a given layer are numbered as they are read and the e00_anno_id
attribute is assigned the features sequence number, starting at 1, within the layer.
If there are no named annotation layers in the coverageas is always the case with
annotation from the TXT subfileall text features will have an empty string () as
the value for their e00_anno_name attribute.
If the text has an associated arrow, a separate line feature is generated. This feature is
type e00_textarrow, and contains the same values for its e00_anno_name and
e00_anno_id attributes as the associated e00_text feature.
Every text feature defined in a TX6 subfile of an E00 coverage has an associated set
of user-defined attributes from a particular info file. Each record of the info file is
returned from the E00 reader as a feature with the attributes defined on it. The features
have an E00_FEAT_ROLE attribute of e00_text_attr and a feature type of
<prefix>_<anno_name>_textattr, where <prefix> is an arbitrary prefix,
and <anno_name> is the name of the annotation layer containing the feature. If the
annotation layer is unnamed, the features defining the user attributes simply have a
feature type of <prefix>_textattr.
The text geometries are associated with their user-defined attributes according to their
position within the file. In other words, there is a one-to-one relationship between the
text geometries and the features defining the user attribute. This relationship is
formed by joining the text features e00_anno_name and e00_anno_id
attributes with the attribute features e00_anno_name and E00_RECORD_NUM
attributes.
Text features from TXT subfiles do not have named annotation layers, and
consequently behave like text features from TX6 files whose e00_anno_name
contains an empty string. Note that the user attributes for text defined in the TXT
Attribute Name Description
e00_anno_name Name of annotation layer containing text.
e00_anno_id Sequence number of text features within its annotation layer.
e00_rotation Rotation of text display, measured in degrees counter-clockwise from
horizontal.
e00_text_height Height of text, measured in ground units.
e00_text_string String of text being displayed.
ESRI ARCINFO EXPORT FORMAT (E00) READER Safe Software Inc.
14-8 FME Reference Manual Version 2.0
subfile come from a different info file than those for text from the TX6 subfile
*.XCODE rather than the *.TAT+ info filebut the E00 reader forms the features
generated from the two info files identically.
14.3.4 Tolerances
E00 coverages contain a list of ten tolerance values, which have a specific meaning
within ArcInfo. Each tolerance has a numerical identifier in the range 1..10, a state,
and a floating point value.
The E00 reader generates ten features from the TOL subfile. Each feature contains the
following attributes:
14.3.5 Projections
An E00 coverage may contain a subfile named PRJ, that defines the geographic
projection of the coordinates within the coverage. The E00 reader gathers all of the
information in this subfile into a single feature of the type e00_projection. The
attributes of this feature are listed above, in the subsection titled Feature Types.
The PRJ subfile contains a list of named parameters, followed by a list of apparently
unnamed parameters. Any of the named parameters, whose names are recognized, are
defined as standard attributesdatum, projection, units, etc.) on the
e00_projection feature. Named parameters, whose names are not recognized by
the reader, are placed into the attributes unknown_parameter{}.name
and unknown_parameter{}.value. Unnamed parameters are placed into the
attribute list param{}.value.
At the present time, the E00 reader does not attempt to interpret the projection feature.
Therefore, the coordinate system of E00 features must be set through the use of the
_COORDINATE_SYSTEM mapping file directive.
Attribute Name Description
id Original numerical id given to the tolerance.
name A standard name given to the tolerance record. This name provides a
description of the tolerance in question, and is really just a textual
version of the above ID.
(1=>FUZZY, 2=>GENERALIZE, 3=>NODE_MATCH,
4=>DANGLE, 5=>TIC_MATCH, 6=>EDIT, 7=>NODESNAP,
8=>WEED, 9=>GRAIN, 10=>SNAP)
state The state of the tolerance.
(1=>tolerance has been verified, 2=>tolerance has not been verified)
value The size of the tolerance. This is a floating point number, typically
smaller than 1.0.
14-9 FME Reference Manual Version 2.0
Safe Software Inc. ESRI ARCINFO EXPORT FORMAT (E00) READER
14.4 Info Files
Unlike the standard subfiles, whose names and formats are common to all E00
files, the info files names and data structures vary from one coverage to another. Each
info file starts with a header that defines its name and attributes on each record of the
file.
The name of the info file is in the form <prefix>.<extension>, where
<prefix> is arbitrary and <extension> defines the role of the records of the info
file. Typically, all info files within a single E00 coverage have the same <prefix>.
The <extension> is usually from a standard set, which includes the AAT (Arc
Attribute Table), PAT (Point or Polygon Attribute Table), and BND (coverage
bounding box). The E00 reader uses the extension to determine a role for the content
of this info file.
Each record of the info file is interpreted by the E00 reader as an FME feature with
no geometry. The <extension> of the info files name is used to define the feature
type and the value of the E00_FEAT_ROLE attribute of these features. The attributes
defined on the record as specified in the info files header are defined verbatim on the
output feature.
14.5 Generated Mapping Files
Mapping files generated by the FME to read E00 files manipulate and join the
features output from the E00 reader to form fully-formed, fully-attributed features
with arc, point, polygon, or text geometry. The following sections explain each type
of output feature and how it is put together.
Each coverage also contains a single polygon feature defining the bounding box of
the coverage, and usually a set of four point features representing the TIC points.
These features have polygon and point geometries, respectively, with the feature
types <prefix>_bounds and <prefix>_tic.
14.5.1 Arc Features
In ArcInfo, arcs are simply polyline features with attributes to define a topology, as
well as user-defined attributes. The geometry comes from the e00_arcdef
features, originating from the ARC subfile and the attributes come from the
e00_arc_attr features, originating from the <prefix>.AAT info file.
Typically, the attributes defining the topologyleft polygon, right polygon, from
node, to nodeare also defined in the info file, and will appear as attributes on the
resulting arc features.
ESRI ARCINFO EXPORT FORMAT (E00) READER Safe Software Inc.
14-10 FME Reference Manual Version 2.0
The arc features have a feature type of <prefix>_arc, where <prefix> is the
prefix from the info file name. The attributes defined on <prefix>_arc features
are summarized in the following table.
In addition, any other attributes defined in the <prefix>.AAT info file are defined
on the <prefix>_arc features generated with this mapping file.
14.5.2 Point Features
Point features are generated when the E00 coverage contains a LAB subfile, but no
PAL subfile. In this case, the e00_label features originating from the LAB subfile
are joined with the attributes of the e00_point_attr features originating from the
<prefix>.PAT info file. The resulting point features have a type of
<prefix>_point and the attributes from the following table.
In addition, any other attributes defined in the <prefix>.PAT info file are defined
on the <prefix>_point features generated with this mapping file.
Attribute Name Attribute Value
e00_type e00_arc
<prefix_ID> Numerical identifier for arc feature.
LENGTH Length of the line, measured in ground units.
FNODE_ Sequence number of starting node of the line.
TNODE_ Sequence number of ending node of the line.
LPOLY_ Sequence number of the polygon that lies to the left of the line when
travelling from FNODE to TNODE.
RPLOY_ Sequence number of the polygon that lies to the right of the line when
travelling from FNODE to TNODE.
Attribute Name Attribute Value
e00_type e00_point
<prefix_ID> Numerical identifier for point feature.
<prefix>_ Sequence number of the point feature.
PERIMITER 0.0
14-11 FME Reference Manual Version 2.0
Safe Software Inc. ESRI ARCINFO EXPORT FORMAT (E00) READER
14.5.3 Polygon Features
Polygon features are the most complex of the features created by the generated
mapping files. The polygon features result from combining four different types of
features output from the E00 reader: e00_arcdef, e00_centroid,
e00_polyarc, and e00_poly_attr. A combination of these features is
performed as follows.
1. The polylines defined by the e00_arcdef features in the ARC subfile form
the edges of the polygons. They are combined to form each polygon and its
holes, according to the contents of the arcnum{} attributes on each
e00_polyarc feature.
2. The point geometry from each e00_centroid feature is attached to the
corresponding polygon, providing the values for the attributes
e00_centroid_x and e00_centroid_y.
3. The attributes from the e00_poly_attr features originating in the
<prefix>.PAT info file are added to the formed polygon features.
The resulting polygon features have a type of <prefix>_poly and the attributes
from the following table.
In addition, any other attributes defined in the <prefix>.PAT info file are defined
on the <prefix>_poly features generated with this mapping file.
14.5.4 Text and Textarrow Features
There are two ways text features are formed in the automatically generated mapping
files. The first, and most common, is by combining the text geometries from the TX6
subfile with the attributes from the <prefix>.TAT<annoLayer> info file. In
this case, the resulting text features have a feature type of
<prefix>_<annoLayer>_text, or <prefix>_text if the annotation layer
Attribute Name Attribute Value
e00_type e00_poly
<prefix_ID> Numerical identifier for polygon feature.
<prefix>_ Sequence number of the polygon feature within the E00 file.
e00_centroid_x X coordinate of polygons centroid.
e00_centroid_y Y coordinate of polygons centroid.
PERIMITER Outer perimeter of polygon.
AREA Area of the polygon, measured in square ground units.
ESRI ARCINFO EXPORT FORMAT (E00) READER Safe Software Inc.
14-12 FME Reference Manual Version 2.0
is unnamed. See the subsection titled Text Representation for an explanation of
annotation layers.
Some E00 coverages have their annotation defined in a TXT subfile rather than in a
TX6 subfile. These features are combined with the attributes of the
<prefix>.XCODE info file instead of a <prefix>.TAT<annoLayer> subfile,
and will always be contained in an unnamed annotation layer.
In either case, text features will have a feature type of <prefix>_text or
<prefix>_<annoLayer>_text, depending on whether they are contained in a
named annotation layer, and will have the attributes shown in the following table.
In addition, any other attributes defined in the <prefix>.TAT<annoLayer> or
<prefix>.XCODE info file are defined on the <prefix>_text features
generated with this mapping file.
If the text geometry originates in the TX6 subfileas opposed to the TXT subfile
it might have a separate linear portion that acts as an arrow pointing from the text to
another location. These lines are written out as features with a feature type of
<prefix>_<annoLayer>_textarrow or <prefix>_textarrow, and
attributes e00_anno_name and e00_anno_id which take the same values as the
corresponding <prefix>_<annoLayer>_text or <prefix>_text features.
Occasionally, an E00 file will have e00_text features for which there are no
corresponding attributes in the info files. In this case, the feature types of the
corresponding text features generated are simply text and textarrow.
Attribute Name Attribute Value
e00_type e00_text
<prefix_ID> Numerical identifier for text feature.
<prefix>_ Sequence number of the text feature within the E00 file.
e00_anno_name Name of annotation layer containing text feature. This will be if it
is in an unnamed annotation layer.
e00_anno_id Sequence number of text feature within its annotation layer. This
number starts at 1 for the first feature in each annotation layer and is
incremented for every other feature.
e00_rotation Rotation at which to display text, measured in degrees counter-
clockwise from horizontal.
e00_text_string Textual portion of feature.
e00_text_height Height of text, measured in ground units.
e00_text_level Number indicating level of text.
14-13 FME Reference Manual Version 2.0
Safe Software Inc. ESRI ARCINFO EXPORT FORMAT (E00) READER
14.6 E00 Mapping File Example
The following mapping file illustrates how text features are formed from the features
that the E00 reader emits. The ReferenceFactory combines the text geometries from
the TX6 subfile with the corresponding attributes from the
<prefix>.TAT<annoLayer>, creating features with the types Text and
TextArrow. These features will have the original e00_text features
e00_anno_name and e00_anno_id attributes.
# =======================================================================
#
# E00 -> Shape Annotation Extraction Control File
#
#
# Notes:
# This control file takes an annotation E00 file as supplied
# outputs the contained annotation to a shape file.
#
# =======================================================================
# =======================================================================
# Set up a log file to use
LOG_FILENAME clrs_e00.log
# =======================================================================
# Define the SourceDataset MACRO to be the directory containing the
# source E00 file, and the FileBase MACRO to be the name of the input
# file (with no extensions).
GUI TITLE CLRS E00 -> Shape Annotation Control File
GUI DIRNAME SourceDataset Source CLRS E00 File Dir:
GUI TEXT FileBase Basename of CLRS E00 File:
GUI DIRNAME DestDataset Destination Shape File Dir:
# =======================================================================
# The following macro defines the name of the shape files containing
# the output annotation data, as well as that defining text-related
# arrow
MACRO ShapeAnno Text
MACRO ShapeArrow TextArrow
# =======================================================================
# The input will be the <FileBase>a.e00 file in the specified directory.
READER_TYPE E00
READER_KEYWORD E00_IN
E00_IN_DATASET $(SourceDataset)/$(FileBase)a.e00
# ======================================================================
# Now define our output
WRITER_TYPE SHAPE
WRITER_KEYWORD SHAPE_OUT
SHAPE_OUT_DATASET $(DestDataset)
# =======================================================================
ESRI ARCINFO EXPORT FORMAT (E00) READER Safe Software Inc.
14-14 FME Reference Manual Version 2.0
# This factory associates TX6 records with records from the
# *.TAT<annoName info files. We will tag all output text features
# with the feature type E00_text so that they will be correlated
# with the single annotation output.
FACTORY_DEF E00_IN ReferenceFactory \
INPUT REFERENCEE FEATURE_TYPE * \
E00_FEAT_ROLE e00_text_attr \
INPUT REFERENCER FEATURE_TYPE e00_text \
REFERENCEE_FIELDS E00_RECORD_NUM e00_anno_name \
REFERENCER_FIELDS E00_RECORD_NUM e00_anno_name \
REFERENCE_INFO ATTRIBUTES \
OUTPUT COMPLETE FEATURE_TYPE e00_text \
e00_type e00_text
# =======================================================================
# Now define the annotation feature type. We put an ANNO_NAME attribute
# on it, though it appears that this might always have the value DESC.
# (The geometry for text features with a given ANNO_NAME come from the
# part of the TX6 section which has a title of <ANNO_NAME>, and the
# attributes come from the info file <basename>.TAT<ANNO_NAME>.)
SHAPE_OUT_DEF $(ShapeAnno) \
SHAPE_GEOMETRY shape_point \
ANNO_NAME char(20) \
ANNO_ID number(11,0) \
TEXT_LEVEL number(11,0) \
TEXT_ANGLE number(14,6) \
TEXT_SIZE number(14,6) \
TEXTSTRING char(254)
# The Text arrows are simple lines
SHAPE_OUT_DEF $(ShapeArrow) \
SHAPE_GEOMETRY shape_arc \
ANNO_ID number(11,0)
# =======================================================================
# Now we correlate the input text features with the output text
# features, and likewise for the arrows
E00_IN e00_text \
e00_type e00_text \
e00_anno_name %anno_name \
e00_anno_id %anno_id \
e00_text_level %text_level \
e00_rotation %text_angle \
e00_text_string %text_string \
e00_text_height %text_height
SHAPE_OUT $(ShapeAnno) \
ANNO_NAME %anno_name \
ANNO_ID %anno_id \
TEXT_LEVEL %text_level \
TEXT_ANGLE %text_angle \
TEXT_SIZE %text_height \
TEXTSTRING %text_string
# =======================================================================
14-15 FME Reference Manual Version 2.0
Safe Software Inc. ESRI ARCINFO EXPORT FORMAT (E00) READER
E00_IN e00_textarrow \
e00_type e00_arc \
e00_anno_id %anno_id
SHAPE_OUT $(ShapeArrow) \
ANNO_ID %anno_id
ESRI ARCINFO EXPORT FORMAT (E00) READER Safe Software Inc.
14-16 FME Reference Manual Version 2.0
15-1 FME Reference Manual Version 2.0
15
15 ESRI ARCINFO GENERATE FILE
READER/WRITER
15.1 Overview
The ArcInfo Generate File reader and writer modules provide the Feature
Manipulation Engine (FME) with access to the simple ASCII format used by
the ArcInfo Generate command. There are several types of Generate files,
and each has their own syntax. Currently point line, and text Generate files are
supported. Both two-dimensional and three-dimensional data can be imported
and exported to line and point Generate files. Three-dimensional (3D)
Generate files are often used to input data into ArcInfos TINning package.
Text Generate Files are defined to accept only two- dimensional (2D)
coordinates.
The FME considers a Generate dataset to be a collection of Generate files in
a single directory. All Generate file names are required to end with a .gen
extension. The type of each Generate file must be defined in the mapping file
before it can be read or written.
TIP: The very simple format of Generate files makes them useful for testing purposes or for
transferring data between the FME and other unsupported systems.
15.2 Reader Overview
The Generate reader module produces FME features for all feature data held
in Generate files residing in a given directory. The Generate reader first scans
the directory it is given for all Generate files defined in the mapping file. For
ESRI ARCINFO GENERATE FILE READER/WRITER Safe Software Inc.
15-2 FME Reference Manual Version 2.0
each Generate file 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 if no IDs were
specified in the mapping file, the Generate file is opened for read. The Generate
reader 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 Generate reader starts
on the next file in the directory.
15.3 Reader Keywords
The following table lists the keywords processed by the Generate reader. The table
shows only the suffixes that will be prefixed by the current <ReaderKeyword> in
a mapping file. By default, the <ReaderKeyword> for the Generate reader is
ARCGEN.
15.3.1 DATASET
The value for this keyword is the directory containing the Generate files to be read.
A typical mapping file fragment specifying an input Generate dataset looks like:
ARCGEN_DATASET /usr/data/generate/92i080
15.3.2 DEF
Before it is read, each Generate file must be defined. The definition specifies the base
name of the file, the type of geometry it contains, and optionally a delimiter between
fields. The syntax of a Generate DEF line is:
<ReaderKeyword>_DEF <baseName> \
ARCGEN_GEOMETRY arcgen_point|arcgen_line|
arcgen_text \
[ARCGEN_DELIMITER <delimiter char>]
Keyword Suffix Value Required/
Optional
DATASET Contains the directory name of the input Generate files. Required
DEF Defines a Generate file. Each Generate file must be
defined before it can be read. The definition contains the
files base name (without the .gen extension), and the
type of geometry it holds. There may be many DEF lines,
one for each file to be read.
Optional
IDs Contains a list of Generate files to process. If more
Generate files are in the directory, they are ignored. If this
is not specified, then all defined Generate files in the
directory are read.
Optional
15-3 FME Reference Manual Version 2.0
Safe Software Inc. ESRI ARCINFO GENERATE FILE READER/WRITER
The filename of the Generate file is the basename plus the .gen extension.
The mapping file fragment below defines two Generate filesone containing point
features and the other containing linear features:
ARCGEN_DEF nodes ARCGEN_GEOMETRY arcgen_point
ARCGEN_DEF boundaries ARCGEN_GEOMETRY arcgen_line
If no delimiter clause is specified, a comma ( , ) is used as the delimiter.
15.3.3 IDs
This optional specification is used to limit which available and defined Generate files
will be read. If no IDs are specified, then all defined and available Generate files will
be 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 nodes Generate file for input during a
translation:
ARCGEN_IDs nodes
15.4 Writer Overview
The Generate writer creates and writes feature data to Generate files in the directory
specified by the DATASET keyword. As with the reader, the directory must exist
before the translation occurs. Any old Generate files in the directory are overwritten
with the new feature data. As features are routed to the Generate writer by the FME,
it determines which file to write to and outputs them according to the type of the file.
Many Generate files can be written during a single FME session.
15.5 Writer Keywords
The Generate writer processes the DATASET and DEF keywords as described in the
Section 15.3, Reader Keywords. It does not make use of the IDs keyword.
ESRI ARCINFO GENERATE FILE READER/WRITER Safe Software Inc.
15-4 FME Reference Manual Version 2.0
15.6 Feature Representation
All Generate features contain a numeric ID field. The numeric ID is stored in the
arcgen_id attribute of an FME feature read from a Generate file or destined to be
written to a Generate file.
TIP: Features being written to an ARCGEN file must have an arcgen_id attribute.
The FME considers the basename of the Generate file to be the FME feature type of
a Generate feature. The feature type of a Generate feature must match the basename
of a Generate file defined by a Generate DEF line.
15.6.1 Points
Generate files containing only points consist of a series of lines that follow this
syntax:
<idNumber>,<x>,<y>[,<z>]
TIP: By using the idNumber associated with each Generate feature as a key into a comma separated value file,
the @Relate command can be used to attach attributes to Generate features.
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 point is considered to be
two-dimensional. The file is terminated by a line containing only the word END. A
two-dimensional point Generate file example is shown below:
601,3,7
602,53,21
603,19,20
END
15.6.2 Lines
Generate files containing only linear features consist of a series of lines that follow
this syntax:
<idNumber>
<x0>,<y0>[,<z0>]
<x1>,<y1>[,<z1>]

<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, &centroidX, &centroidY)
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

You might also like