refman

Reference Manual

Safe Software Inc.E-mail: [email protected]

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 described 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-9965E-mail: [email protected]: 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 providersand 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 ManualVersion: 2.0 July 1997

Fourth Printing

Table of Contents

About This ManualIntended Audience .................................................................................................. xxiiiUsing This Manual .................................................................................................. xxivAbout Each Section ................................................................................................ xxivConventions Used in this Guide ............................................................................ xxviiFor More Information ........................................................................................... xxviii

1 INTRODUCTION1.1 Overview ................................................................................................................... 1-11.2 Data Source Merging ................................................................................................ 1-21.3 Topology Operations ................................................................................................ 1-31.4 Geometric Operations ............................................................................................... 1-31.5 Attribute Operations ................................................................................................. 1-41.6 Coordinate System Conversion ................................................................................ 1-41.7 Summary ................................................................................................................... 1-5

2 FME ARCHITECTURE2.1 FME Features ............................................................................................................ 2-22.2 Reader Modules ........................................................................................................ 2-32.3 Functions ................................................................................................................... 2-42.4 Feature Factory Pipeline ........................................................................................... 2-52.5 Transformation Module ............................................................................................ 2-52.6 Writer Modules ......................................................................................................... 2-52.7 Mapping File ............................................................................................................. 2-6

FME Reference Manual—Version 2.0 (iii)

Safe Software Inc. Table of Contents

3 FME FUNCTIONS3.1 Function Parameters ................................................................................................. 3-2

3.1.1 Constants ....................................................................................................... 3-33.1.2 Transfer Variables ......................................................................................... 3-33.1.3 Attribute Values ............................................................................................ 3-33.1.4 Attribute Functions ....................................................................................... 3-33.1.5 Composites .................................................................................................... 3-4

3.2 Forward Function Example ...................................................................................... 3-43.3 Inverse Function Example ........................................................................................ 3-53.4 Function Configuration ............................................................................................. 3-63.5 User Defined Functions ............................................................................................ 3-6

4 FME FEATURE FACTORIES4.1 Factory Architecture ................................................................................................. 4-2

4.1.1 Input Interface ............................................................................................... 4-24.1.2 Feature Processing Unit ................................................................................ 4-34.1.3 Output Interface ............................................................................................ 4-3

4.2 Factory Activation Sequence .................................................................................... 4-34.3 Factory Pipeline ........................................................................................................ 4-44.4 Factory Definitions ................................................................................................... 4-4

4.4.1 FACTORY_DEF .......................................................................................... 4-54.4.2 INPUT ........................................................................................................ 4-54.4.3 Factory Specific Directives ........................................................................... 4-64.4.4 GROUP_BY ................................................................................................. 4-64.4.5 OUTPUT ....................................................................................................... 4-6

4.5 Factory Example 1 .................................................................................................... 4-74.6 Factory Example 2 .................................................................................................... 4-8

5 FME TRANSLATION PROCESS5.1 Transformation Specification ................................................................................... 5-1

5.1.1 Source Line ................................................................................................... 5-35.1.2 Destination Line ............................................................................................ 5-35.1.3 Example ........................................................................................................ 5-45.1.4 Matching Process .......................................................................................... 5-4

5.2 Transfer Variables .................................................................................................... 5-55.3 Default Attribute Values ........................................................................................... 5-6

6 FME MAPPING FILE SYNTAX6.1 Overview ................................................................................................................... 6-16.2 Line Continuation ..................................................................................................... 6-16.3 Quoted Text .............................................................................................................. 6-26.4 Single Line Comments ............................................................................................. 6-26.5 Block Comments ...................................................................................................... 6-3

FME Reference Manual — Version 2.0 (iv)

Table of Contents Safe Software Inc.

6.6 MACRO Directive .................................................................................................... 6-36.7 Predefined Macros .................................................................................................... 6-46.8 DEFAULT_MACRO Directive ................................................................................ 6-56.9 INCLUDE Directive ................................................................................................. 6-56.10 Environment Variable Expansion ............................................................................. 6-66.11 Static Function Evaluation ........................................................................................ 6-6

7 FME CONFIGURATION7.1 Reader and Writer Selection ..................................................................................... 7-17.2 Reader and Writer Keywords ................................................................................... 7-27.3 Log File Configuration ............................................................................................. 7-37.4 Mapping File Debugging .......................................................................................... 7-4

8 COORDINATE SYSTEM SUPPORT8.1 Overview ................................................................................................................... 8-18.2 Coordinate System Identification ............................................................................. 8-28.3 Coordinate System Definition .................................................................................. 8-3

8.3.1 Example Coordinate System Definitions ...................................................... 8-48.3.2 Local Coordinate System Definitions ........................................................... 8-4

8.4 Coordinate Units ....................................................................................................... 8-58.4.1 Unit Definition .............................................................................................. 8-58.4.2 Example Unit Definition ............................................................................... 8-6

8.5 Projection Types ....................................................................................................... 8-68.5.1 AE: Albers Equal Area ................................................................................. 8-88.5.2 AZMED: Lambert Azimuthal Equidistant Projection .................................. 8-88.5.3 AZMEA: Lambert Azimuthal Equal Area Projection ................................ 8-108.5.4 BONNE: Bonne Projection ......................................................................... 8-118.5.5 BIPOLAR: Bipolar Oblique Conformal Conic .......................................... 8-118.5.6 EDCNC: Equidistant Conic Projection ....................................................... 8-128.5.7 EDCYL: Equidistant Cylindrical Projection .............................................. 8-128.5.8 ECKERT4: Eckert 4 Projection .................................................................. 8-138.5.9 ECKERT6: Eckert 6 Projection .................................................................. 8-138.5.10 GNOMONIC: Gnomonic Projection .......................................................... 8-148.5.11 GOODE: Goode Homolosine Projection .................................................... 8-148.5.12 LM: Lambert Conformal Conic Projection ................................................ 8-158.5.13 LMTAN: Lambert Tangential Projection ................................................... 8-158.5.14 LL: Latitude/Longitude ............................................................................... 8-168.5.15 MILLER: Miller Cylindrical Projection ..................................................... 8-178.5.16 MODPC: Modified Polyconic Projection ................................................... 8-178.5.17 MOLLWEID: Mollweide Projection .......................................................... 8-188.5.18 MRCAT: Traditional Mercator Projection ................................................. 8-188.5.19 MSTERO: Modified Stereographic Projection ........................................... 8-198.5.20 NEACYL: Normal Authalic Cylindrical Projection ................................... 8-19

(v) FME Reference Manual — Version 2.0


8.5.21 NZEALAND: New Zealand National Grid System ................................... 8-208.5.22 ORTHO: Orthographic Projection .............................................................. 8-208.5.23 PLYCN: American Polyconic Projection ................................................... 8-208.5.24 ROBINSON: Robinson Projection ............................................................. 8-218.5.25 SINUS: Sinusoidal Projection .................................................................... 8-218.5.26 STERO: Stereographic Projection .............................................................. 8-228.5.27 TEACYL: Transverse Authalic Projection ................................................. 8-238.5.28 TM: Transverse Mercator ........................................................................... 8-248.5.29 VDGRNTN: Van Der Grinten Projection .................................................. 8-24

8.6 Datums .................................................................................................................. 8-258.6.1 Datum Definition ........................................................................................ 8-298.6.2 Example Datum Definition ......................................................................... 8-308.6.3 Datum Shift Issues for North American Users ........................................... 8-31

8.7 Predefined Ellipsoids .............................................................................................. 8-328.7.1 Ellipsoid Definition ..................................................................................... 8-348.7.2 Example Ellipsoid Definition ..................................................................... 8-35

9 FME INTERFACES9.1 Command Line Interface .......................................................................................... 9-1

9.1.1 Overriding Mapping File Settings ................................................................ 9-19.1.2 Extending Mapping File Settings ................................................................. 9-29.1.3 Defining Macros ........................................................................................... 9-29.1.4 Automated Mapping File Generation ........................................................... 9-3

9.2 FME Configurable User Interface ............................................................................ 9-39.2.1 User Interface Directives .............................................................................. 9-49.2.2 Dialog Box Title ........................................................................................... 9-4

9.2.2.1 Filename Parameters ...................................................................... 9-49.2.2.2 Directory Parameters ..................................................................... 9-59.2.2.3 Integers Parameters ........................................................................ 9-69.2.2.4 Floating Point Parameters .............................................................. 9-69.2.2.5 Text Parameters ............................................................................. 9-79.2.2.6 Password Parameters ..................................................................... 9-7

10 AUTOCAD DWG/DXF READER/WRITER10.1 Overview ................................................................................................................. 10-110.2 Reader Overview .................................................................................................... 10-3

10.2.1 Reader Keywords ........................................................................................ 10-410.2.2 Block Resolution ......................................................................................... 10-4

10.3 Writer Overview ..................................................................................................... 10-410.3.1 Writer Keywords ......................................................................................... 10-610.3.2 DATASET .................................................................................................. 10-710.3.3 VERSION ................................................................................................... 10-710.3.4 TEMPLATEFILE ....................................................................................... 10-7

FME Reference Manual — Version 2.0 (vi)


10.3.5 LineType Representation ............................................................................ 10-810.3.6 Layer Representation .................................................................................. 10-9

10.4 Feature Representation ......................................................................................... 10-1010.4.1 Extended Entity Data ................................................................................ 10-1110.4.2 List Format ................................................................................................ 10-1110.4.3 Structure Format ....................................................................................... 10-1310.4.4 Interpreted Format .................................................................................... 10-1510.4.5 Lines .................................................................................................... 10-1610.4.6 XLines .................................................................................................... 10-1610.4.7 Points .................................................................................................... 10-1610.4.8 Ellipses .................................................................................................... 10-1710.4.9 Shapes .................................................................................................... 10-1710.4.10Polygons .................................................................................................... 10-1910.4.11Faces .................................................................................................... 10-1910.4.12Arcs .................................................................................................... 10-1910.4.13Traces .................................................................................................... 10-2110.4.14Solids .................................................................................................... 10-2110.4.15Rays .................................................................................................... 10-2110.4.16Text Entities .............................................................................................. 10-2110.4.17Inserts .................................................................................................... 10-23

10.5 AutoCAD Mapping File Example 1 ..................................................................... 10-2410.6 AutoCAD Mapping File Example 2 ..................................................................... 10-30

11 B.C. MINISTRY OF ENVIRONMENT AND PARKS (MOEP) READER/WRITER11.1 Overview ................................................................................................................. 11-111.2 Reader Overview .................................................................................................... 11-211.3 Reader Keywords .................................................................................................... 11-2

11.3.1 DATASET .................................................................................................. 11-211.3.2 DEF ...................................................................................................... 11-311.3.3 IDs ...................................................................................................... 11-4

11.4 Writer Overview ..................................................................................................... 11-411.5 Writer Keywords .................................................................................................... 11-411.6 Feature Representation ........................................................................................... 11-5

11.6.1 Line Features ............................................................................................... 11-511.6.2 Contour Features ......................................................................................... 11-611.6.3 Point Features ............................................................................................. 11-611.6.4 Arc Features ................................................................................................ 11-711.6.5 Text Features ............................................................................................... 11-7

11.7 MOEP Mapping File Example 1 ............................................................................ 11-811.8 MOEP Mapping File Example 2 .......................................................................... 11-11

(vii) FME Reference Manual — Version 2.0


12 DESIGN FILE READER/WRITER12.1 Overview ................................................................................................................. 12-112.2 Reader Overview .................................................................................................... 12-312.3 Reader Keywords .................................................................................................... 12-312.4 Writer Overview ..................................................................................................... 12-412.5 Writer Keywords .................................................................................................... 12-512.6 Feature Representation ........................................................................................... 12-6

12.6.1 Attribute Linkages ...................................................................................... 12-712.6.2 Cells ...................................................................................................... 12-912.6.3 Points .................................................................................................... 12-1012.6.4 Lines .................................................................................................... 12-1012.6.5 Shapes .................................................................................................... 12-1112.6.6 Text Nodes ................................................................................................ 12-1112.6.7 Curves .................................................................................................... 12-1312.6.8 Ellipses .................................................................................................... 12-1312.6.9 Arcs .................................................................................................... 12-1412.6.10Text Strings ............................................................................................... 12-1612.6.11Multi Text Strings ..................................................................................... 12-1712.6.12Solids .................................................................................................... 12-19

12.7 IGDS Mapping File Example ............................................................................... 12-20

13 DIGITAL LINE GRAPH READER13.1 Overview ................................................................................................................. 13-113.2 Reader Overview .................................................................................................... 13-2

13.2.1 Reader Keywords ........................................................................................ 13-313.2.1.1 Dataset .............................................................................. 13-3

13.2.2 Feature Representation ............................................................................... 13-313.2.3 Points ...................................................................................................... 13-513.2.4 Lines ...................................................................................................... 13-613.2.5 Areas ...................................................................................................... 13-7

13.3 Features Created by Generated DLG Mapping Files ............................................. 13-713.3.1 Feature Representation ............................................................................... 13-713.3.2 DLG Attributes ........................................................................................... 13-813.3.3 Hypsography ............................................................................................... 13-913.3.4 Hydrography ............................................................................................. 13-1013.3.5 Vegetative Surface Cover ......................................................................... 13-1013.3.6 Non-Vegetative Features .......................................................................... 13-1013.3.7 Boundaries ................................................................................................ 13-1113.3.8 Survey Control and Markers ..................................................................... 13-1113.3.9 Roads and Trails ....................................................................................... 13-1213.3.10Railroads ................................................................................................... 13-1213.3.11Pipelines, Transmission Lines, and Miscellaneous Transportation

Features .................................................................................................... 13-13

FME Reference Manual — Version 2.0 (viii)


13.3.12Man-made Features ................................................................................... 13-1313.3.13U.S. Public Land Survey System .............................................................. 13-13

13.4 Example ................................................................................................................ 13-14

14 ESRI ARCINFO EXPORT FORMAT (E00) READER14.1 Overview ................................................................................................................. 14-114.2 Reader Keywords .................................................................................................... 14-214.3 Feature Representation ........................................................................................... 14-2

14.3.1 Geometry Composition ............................................................................... 14-214.3.2 Feature Types .............................................................................................. 14-314.3.3 Text Representation .................................................................................... 14-614.3.4 Tolerances ................................................................................................... 14-814.3.5 Projections .................................................................................................. 14-8

14.4 Info Files ................................................................................................................. 14-914.5 Generated Mapping Files ........................................................................................ 14-9

14.5.1 Arc Features ................................................................................................ 14-914.5.2 Point Features ........................................................................................... 14-1014.5.3 Polygon Features ....................................................................................... 14-1114.5.4 Text and Textarrow Features .................................................................... 14-11

14.6 E00 Mapping File Example .................................................................................. 14-13

15 ESRI ARCINFO GENERATE FILE READER/WRITER15.1 Overview ................................................................................................................. 15-115.2 Reader Overview .................................................................................................... 15-115.3 Reader Keywords .................................................................................................... 15-2

15.3.1 DATASET .................................................................................................. 15-215.3.2 DEF ...................................................................................................... 15-215.3.3 IDs ...................................................................................................... 15-3

15.4 Writer Overview ..................................................................................................... 15-315.5 Writer Keywords .................................................................................................... 15-315.6 Feature Representation ........................................................................................... 15-4

15.6.1 Points ...................................................................................................... 15-415.6.2 Lines ...................................................................................................... 15-415.6.3 Text ...................................................................................................... 15-5

15.7 Example .................................................................................................................. 15-6

16 ESRI SHAPE FILE READER/WRITER16.1 Overview ................................................................................................................. 16-116.2 Reader Overview .................................................................................................... 16-316.3 Reader Keywords .................................................................................................... 16-3

16.3.1 DATASET .................................................................................................. 16-416.3.2 DEF ...................................................................................................... 16-416.3.3 IDs ...................................................................................................... 16-5

16.4 Writer Overview ..................................................................................................... 16-6

(ix) FME Reference Manual — Version 2.0


16.5 Writer Keywords .................................................................................................... 16-616.6 Feature Representation ........................................................................................... 16-616.7 Example .................................................................................................................. 16-7

17 ESRI SDE READER/WRITER17.1 Overview ................................................................................................................. 17-217.2 FME SDE Highlights .............................................................................................. 17-317.3 Reader Overview .................................................................................................... 17-417.4 Reader Keywords .................................................................................................... 17-5

17.4.1 DATASET .................................................................................................. 17-517.4.2 SERVER ..................................................................................................... 17-517.4.3 USERID ...................................................................................................... 17-617.4.4 PASSWORD ............................................................................................... 17-617.4.5 Where ...................................................................................................... 17-617.4.6 SEARCH_ENVELOPE .............................................................................. 17-717.4.7 LOGFILE .................................................................................................... 17-717.4.8 IDs ...................................................................................................... 17-717.4.9 Complete Reader Example ......................................................................... 17-8

17.5 Writer Overview ..................................................................................................... 17-817.6 Writer Keywords .................................................................................................... 17-9

17.6.1 SDE_LogFile .............................................................................................. 17-917.6.2 SDE_Transaction ...................................................................................... 17-10

17.7 SDE Layer Representation ................................................................................... 17-1017.7.1 <layerName> ............................................................................................ 17-1117.7.2 SDE_Base_Layer ...................................................................................... 17-1117.7.3 SDE_Layer ................................................................................................ 17-1217.7.4 SDE_Grid{0} ............................................................................................ 17-1217.7.5 SDE_Grid{1} ............................................................................................ 17-1217.7.6 SDE_Grid{2} ............................................................................................ 17-1217.7.7 SDE_Dimension ....................................................................................... 17-1317.7.8 SDE_AVERAGE_PTS ............................................................................. 17-1317.7.9 SDE_INIT_NUM_FEATS ....................................................................... 17-1317.7.10SDE_CONFIG_KEYWORD .................................................................... 17-1317.7.11SDE_Geometry ......................................................................................... 17-1317.7.12SDE_SecurityClass ................................................................................... 17-1417.7.13Attribute Definitions ................................................................................. 17-1517.7.14SDE_Index{#} .......................................................................................... 17-1617.7.15Example of a Layer Definition ................................................................. 17-16

17.8 Feature Representation ......................................................................................... 17-1717.9 SDE Control File Examples .................................................................................. 17-18

17.9.1 Example 1: SDE <-> MapInfo .................................................................. 17-1817.9.2 Example 2: SDE<->SDE .......................................................................... 17-21

FME Reference Manual — Version 2.0 (x)


18 GIF IMAGE WRITER18.1 Overview ................................................................................................................. 18-118.2 Writer Overview ..................................................................................................... 18-218.3 Writer Keywords .................................................................................................... 18-2

18.3.1 DATASET .................................................................................................. 18-318.3.2 DEF ...................................................................................................... 18-418.3.3 WIDTH ...................................................................................................... 18-418.3.4 HEIGHT ...................................................................................................... 18-418.3.5 GROUND_RANGE .................................................................................... 18-518.3.6 SQUARE_PIXELS ..................................................................................... 18-518.3.7 BACKGROUND_COLOR ......................................................................... 18-518.3.8 BACKGROUND_PATTERN .................................................................... 18-518.3.9 INTERLACE .............................................................................................. 18-618.3.10TRANSPARENT_COLOR ........................................................................ 18-6

18.4 Feature Representation ........................................................................................... 18-618.4.1 Polygons ...................................................................................................... 18-618.4.2 Lines ...................................................................................................... 18-718.4.3 Points ...................................................................................................... 18-818.4.4 Text ...................................................................................................... 18-9

18.5 Example ................................................................................................................ 18-10

19 MAPINFO DATA INTERCHANGE FORMAT READER/WRITER19.1 Overview ................................................................................................................. 19-119.2 Reader Overview .................................................................................................... 19-3

19.2.1 Reader Keywords ........................................................................................ 19-319.2.2 DATASET .................................................................................................. 19-319.2.3 DEF ...................................................................................................... 19-319.2.4 IDs ...................................................................................................... 19-5

19.3 Writer Overview ..................................................................................................... 19-519.3.1 Writer Keywords ......................................................................................... 19-5

19.4 Feature Representation ........................................................................................... 19-519.4.1 Points ...................................................................................................... 19-619.4.2 Font Points .................................................................................................. 19-719.4.3 Custom Points ............................................................................................. 19-719.4.4 Polylines ...................................................................................................... 19-819.4.5 Regions ...................................................................................................... 19-919.4.6 Text .................................................................................................... 19-1019.4.7 Ellipse .................................................................................................... 19-1119.4.8 Arc .................................................................................................... 19-1219.4.9 Rectangle .................................................................................................. 19-1419.4.10Rounded Rectangle ................................................................................... 19-14

19.5 Example of an SAIF to MIF Mapping File .......................................................... 19-14

(xi) FME Reference Manual — Version 2.0


20 MAPINFO NATIVE FORMAT READER/WRITER20.1 Overview ................................................................................................................. 20-120.2 Reader Overview .................................................................................................... 20-3

20.2.1 Reader Keywords ........................................................................................ 20-320.2.2 DATASET .................................................................................................. 20-420.2.3 DEF ...................................................................................................... 20-420.2.4 IDs ...................................................................................................... 20-5


20.4 Feature Representation ........................................................................................... 20-620.4.1 Points ...................................................................................................... 20-620.4.2 Font Points .................................................................................................. 20-720.4.3 Custom Points ............................................................................................. 20-820.4.4 Polylines ...................................................................................................... 20-920.4.5 Regions .................................................................................................... 20-1020.4.6 Text .................................................................................................... 20-1120.4.7 Ellipse .................................................................................................... 20-1320.4.8 Arc .................................................................................................... 20-1420.4.9 Rectangle .................................................................................................. 20-1520.4.10Rounded Rectangle ................................................................................... 20-15

20.5 Example of an SAIF to MAPINFO Mapping File ................................................ 20-16

21 MULTI-READER21.1 Overview ................................................................................................................. 21-121.2 Keywords ................................................................................................................ 21-221.3 Feature Representation ........................................................................................... 21-221.4 Example .................................................................................................................. 21-3

22 PHOCUS PHODAT READER22.1 Overview ................................................................................................................. 22-122.2 Reader Overview .................................................................................................... 22-2

22.2.1 Reader Keywords ........................................................................................ 22-222.2.2 DATASET .................................................................................................. 22-2

22.3 Feature Representation ........................................................................................... 22-222.4 PHOCUS Attributes ................................................................................................ 22-3

22.4.1 Points ...................................................................................................... 22-422.4.2 Lines ...................................................................................................... 22-522.4.3 Areas ...................................................................................................... 22-522.4.4 Text ...................................................................................................... 22-5

22.5 Example .................................................................................................................. 22-6

FME Reference Manual — Version 2.0 (xii)


23 RELATIONAL TABLE READER/WRITER23.1 Overview ................................................................................................................. 23-123.2 Reader Overview .................................................................................................... 23-2

23.2.1 Reader Keywords ........................................................................................ 23-223.2.2 DATASET .................................................................................................. 23-323.2.3 DEF ...................................................................................................... 23-3

23.2.3.1 ASCII Field Types ....................................................................... 23-423.2.3.2 ASCII Special Fields ................................................................... 23-523.2.3.3 CAT Field Types ......................................................................... 23-523.2.3.4 CAT Special Fields ...................................................................... 23-623.2.3.5 CSV/DBF Field Types ................................................................. 23-623.2.3.6 CSV Special Fields ...................................................................... 23-7


23.4 Feature Representation ........................................................................................... 23-823.5 Example .................................................................................................................. 23-8

24 SPATIAL ARCHIVE AND INTERCHANGE FORMAT (SAIF) READER/WRITER24.1 Overview ................................................................................................................. 24-1

24.1.1 SAIF Directory ........................................................................................... 24-224.1.2 SAIF Schema .............................................................................................. 24-324.1.3 SAIF Object Definitions ............................................................................. 24-3

24.2 Reader Overview .................................................................................................... 24-424.2.1 Reader Keywords ........................................................................................ 24-424.2.2 DATASET .................................................................................................. 24-424.2.3 IDs ...................................................................................................... 24-4

24.3 Writer Overview ..................................................................................................... 24-524.3.1 Writer Keywords ......................................................................................... 24-524.3.2 DATASET .................................................................................................. 24-624.3.3 DEF ...................................................................................................... 24-624.3.4 CSN ...................................................................................................... 24-924.3.5 XCOORD_TYPE ........................................................................................ 24-924.3.6 YCOORD_TYPE ...................................................................................... 24-1024.3.7 ZCOORD_TYPE ...................................................................................... 24-10

24.4 Feature Representation ......................................................................................... 24-1024.4.1 Geometric Entity Form ............................................................................. 24-1024.4.2 Text Entity Form ....................................................................................... 24-11

24.5 Example ................................................................................................................ 24-11

(xiii) FME Reference Manual — Version 2.0


25 VECTOR PRODUCT FORMAT (VPF) READER25.1 Reader Overview .................................................................................................... 25-1

25.1.1 Reader Keywords ........................................................................................ 25-125.1.2 DATASET .................................................................................................. 25-225.1.3 DEF ...................................................................................................... 25-225.1.4 IDs ...................................................................................................... 25-425.1.5 Feature Representation ............................................................................... 25-5

25.2 Special Attribute Handling ..................................................................................... 25-625.2.1 Coordinate Attributes .................................................................................. 25-7

25.3 Value Descriptor Tables ......................................................................................... 25-825.3.1 Table Relations ........................................................................................... 25-825.3.2 Text Primitive Attributes .......................................................................... 25-10

A FME FUNCTION REFERENCEA.1 @Abort ................................................................................................................... A-1A.2 @AddVertices ......................................................................................................... A-3A.3 @Affine ................................................................................................................... A-5A.4 @Arc ................................................................................................................... A-7A.5 @Area ................................................................................................................. A-10A.6 @Bounds ............................................................................................................... A-11A.7 @Circularity .......................................................................................................... A-13A.8 @Close ................................................................................................................. A-14A.9 @Concatenate ........................................................................................................ A-16A.10 @ConvertBase ....................................................................................................... A-17A.11 @ConvertToArc .................................................................................................... A-19A.12 @ConvertToLine ................................................................................................... A-22A.13 @ConvertToPoint .................................................................................................. A-24A.14 @Coordinate .......................................................................................................... A-25A.15 @CoordSys ............................................................................................................ A-27A.16 @Count ................................................................................................................. A-28A.17 @Dimension .......................................................................................................... A-30A.18 @Evaluate .............................................................................................................. A-31A.19 @FeatureType ....................................................................................................... A-36A.20 @Force2D .............................................................................................................. A-38A.21 @Generalize .......................................................................................................... A-39A.22 @GeneratePoint ..................................................................................................... A-41A.23 @GOID ................................................................................................................. A-42A.24 @KeepAttributes ................................................................................................... A-47A.25 @Length ................................................................................................................ A-49A.26 @Log ................................................................................................................. A-50A.27 @Lookup ............................................................................................................... A-52A.28 @NumCoords ........................................................................................................ A-55A.29 @NumElements ..................................................................................................... A-56

FME Reference Manual — Version 2.0 (xiv)


A.30 @NumHoles .......................................................................................................... A-58A.31 @Offset ................................................................................................................. A-59A.32 @Orient ................................................................................................................. A-60A.33 @Relate ................................................................................................................. A-62A.34 @Reproject ............................................................................................................ A-80A.35 @Rotate2D ............................................................................................................ A-82A.36 @RoundOffCoords ................................................................................................ A-83A.37 @SAIFAngle ......................................................................................................... A-85A.38 @Scale ................................................................................................................. A-87A.39 @Split ................................................................................................................. A-88A.40 @SupplyAttributes ................................................................................................ A-92A.41 @Timestamp .......................................................................................................... A-94A.42 @XValue ............................................................................................................... A-96A.43 @YValue ............................................................................................................. A-100A.44 @ZValue .............................................................................................................. A-101

B FACTORY REFERENCEB.1 AggregateFactory .....................................................................................................B-1B.2 ArcFactory ................................................................................................................B-4B.3 ChoppingFactory ......................................................................................................B-6B.4 ClippingFactory ........................................................................................................B-9B.5 CloseFactory ...........................................................................................................B-11B.6 ConnectionFactory ..................................................................................................B-14B.7 DeaggregateFactory ................................................................................................B-17B.8 DonutFactory ..........................................................................................................B-20B.9 DonutHoleFactory ..................................................................................................B-23B.10 ElementFactory .......................................................................................................B-25B.11 ListFactory ..............................................................................................................B-28B.12 MatchingFactory .....................................................................................................B-31B.13 PIPComponentsFactory ..........................................................................................B-35B.14 PolygonFactory .......................................................................................................B-37B.15 PolygonDissolveFactory .........................................................................................B-39B.16 ReferenceFactory ....................................................................................................B-41B.17 SamplingFactory .....................................................................................................B-46B.18 SDEQueryFactory ...................................................................................................B-47B.19 SortFactory .............................................................................................................B-55B.20 TeeFactory ..............................................................................................................B-57B.21 TestFactory .............................................................................................................B-59

C ACRONYMS

FME Reference Manual — Version 2.0 (xv)


(xvi) FME Reference Manual — Version 2.0

em

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 thfor the data model of their organization

(xvii)FME Reference Manual — Version 2.0

About This Manual Safe Software Inc.

few
• those who use the FME mapping files that come with the system, supplying aparameters like a file name or directory to perform translations.
This manual is primarily directed at the first group of users, while the FME User’s Manual applies to the second.

Using This Manual

This manual contains complete reference information on all of the FME’s 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 FME’s 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 1Introduction

This section describes the data processing and translation capabilities of the FME.

Section 2FME 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 3FME Functions

A unique and powerful capability of the FME is the application of functions to feature geometry and attributes during the translation process.

Section 4FME Feature Factories

Feature factories provide a mechanism for the FME to operate on groups of features.

(xviii) FME Reference Manual — Version 2.0

Safe Software Inc. About This Manual

n

s

g

g

g

g

Section 5FME Translation Process

The primary task of the FME is to translate features by selectively setting, transferring, and modifying feature attributes and geometry.

Section 6FME Mapping File Syntax

This section describes the syntax and facilities of FME mapping files.

Section 7FME Configuration

This section explains the FME’s core configuration — from the specificatioof the reader and writer modules a session uses, to the FME mapping filedebugging facilities.

Section 8Coordinate System Support

The FME tracks the coordinate system of each feature, automatically performing coordinate system conversions when necessary.

Section 9FME Interfaces

This section describes the command line and configurable user interface(FMEGUI) shipped with the FME. Mapping files may be invoked from a configurable graphical user interface, which prompts end users for missinmapping file settings.

Section 10AutoCAD DWG/DXF Reader/Writer

This section explains the facilities the FME provides for reading and writinAutoCAD DWG and DXF files.

Section 11B.C. Ministry of Environment and Parks (MOEP) Reader/Writer

This section explains the facilities the FME provides for reading and writinB.C. Ministry of Environment and Parks (MOEP) files.

Section 12Design File Reader/Writer

This section explains the facilities the FME provides for reading and writinIntergraph Design files.

Section 13Digital Line Graph Reader

This section explains the facilities the FME provides for importing Level 3Digital Line Graph (DLG) data and exporting it to any of the FME output formats.

Section 14ESRI ArcInfo Export Format (E00) Reader

This section explains the capability of the FME to read uncompressed ArcInfo Export (E00) files.

(xix)FME Reference Manual — Version 2.0


s

g

g

ut

dat

l

s n

Section 15ESRI ArcInfo Generate File Reader/Writer

This section explains the facilities the FME provides for reading and writing ArcInfo Generate files.

Section 16ESRI Shape File Reader/Writer

This section explains the facilities the FME provides for reading and writing ESRI Shape files.

Section 17ESRI SDE Reader/Writer

This section describes the FME facilities for importing and exporting data to and from ESRI’s Spatial Database Engine (SDE).

Section 18GIF Image Writer

This section explains the facilities the FME provides for creating GraphicInterchange Format (GIF) image files from input vector data.

Section 19MapInfo Data Interchange Format Reader/Writer

This section explains the facilities the FME provides for reading and writinMapInfo Data Interchange Format (MIF/MID) files.

Section 20MapInfo Native Format Reader/ Writer

This section explains the facilities the FME provides for reading and writinnative MapInfo Data (TAB) files.

Section 21Multi-Reader

This section explains the Multi-Reader, which allows several different inpdatasets to be read and combined during a single translation.

Section 22Phocus Phodat Reader

This section explains the facilities the FME provides to read Phocus Phointerchange format files.

Section 23Relational Table Reader/Writer

This section explains the facilities the FME provides for utilizing relationadatabases as the primary source of or destination for information during translation. It describes the facilities provided for files such as DBase File(DBFs), Comma Separated Values (CSVs), free-form ASCII, and ColumAligned Text (CAT).

(xx) 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 24Spatial 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 25Vector 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 AFME Function Reference

This section contains a description of all the FME functions which are currently available.

Appendix BFactory Reference

This section contains a description of all the factories available within the FME.

Appendix CAcronyms

All acronyms used in this manual are noted here.

Feature Snapshot This font is used when the in-memory contents of an FMEfeature are shown.

Monospaced type This font is used when mapping file contents are shown.

<atom name> Angle brackets enclose names which will be replaced witha 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 avertical bar.

<item>* An asterisk following any of the above indicates that zeroor more repetitions of the item are allowed.

<item>+ An plus sign following any of the above indicates that oneor more repetitions of the item are allowed.

Italics References to other documents, or to other sections orparagraphs within this document, are shown in italicizedtext. For example, “...refer to Section 2, FME Architecture”.

(xxi)FME Reference Manual — Version 2.0


3.2,

f

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 ManualPart II — FME TutorialPart III — FME Solutions Guide

Map Projections—A 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 January 1995

SAIF Toolkit API Programmer’s Reference Manual, Release 1.1, BC Ministry oEnvironment Lands and Parks, November, 1994

SAIF/ZIP File Format Description

SDE Reference Manual

SDE User’s Manual

Spatial Archive and Interchange Format: Formal Specification Release 3.2

Future Enhancement

Feature Snapshot

Important Point

(xxii) 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 vendor’s format and have been restricted to using one vendor’s 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.

1-1FME Reference Manual — Version 2.0

INTRODUCTION Safe Software Inc.

tion

s— aset.

ingle

Figure 1-1 Feature Manipulation Engine — provides a universal spatial data translasolution.

1.2 Data Source Merging

Through the use of the FME’s Multi-Reader, data from several different sourcepossibly of varied formats—can be read, processed, and output to a single datThis can be used to:

• Combine several 1:50,000 maps together, generalize them, and create a s1:250,000 map.

• Produce derived products for an area by combining input data from diversesources.

AutoCADDWG/DXF

ASCIICSV, CAT

ESRISHAPE

ESRISDEDBMS

(ODBC, ORACLEDBASE)

MAPINFO (MIF, TAB)

RASTER

VPF/DLG

ESRIARC/

GENERATE

BC MOEP,SAIF

IGDSDESIGN

ESRIE00

KF 85

PHOCUS PHODAT

1-2 FME Reference Manual — Version 2.0

Safe Software Inc. INTRODUCTION

data

tes re.

n the and

res by s of red.

mat

ns rent tions

red in cess.

• 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 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 attribuassociated with the point are then associated with the enclosing area featu

• Remove duplicate line segments from an input data set. This is useful wheinput data set is a collection of polygons which share common boundariesthe desired output is the set of arcs which define the polygon boundaries.

• Connect line segments together. This is used to reduce the number of featucombining their geometry. Line breaks occur only when the attribute valuethe line pieces change or when a topologically significant node is encounte

• Generate interior points for polygons. This is used when the destination forrequires 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 polygoand short lines to points, and converting small polygons to lines. Two diffeline thinning algorithms are available, and each of the generalization operais fully configurable on a feature by feature basis.

• Calculate feature area and length. These calculated values can then be stothe destination format or used to control other aspects of the translation pro

TIP: See Appendix A, @ConvertToLine, @ConvertToPoint, @Generalize, @Length and @Area for more details.



veral

ingle

nate ibly

ats cing

If the

te, the

gles the

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 (thiscapability eases migration to systems with an object-oriented data model)

• read or write feature attributes from/to external tables during translation (sedifferent types of attribute files are supported)

• join multiple relational tables together to extract or output data related to a sfeature

1.6 Coordinate System Conversion

All FME features know the coordinate system of their geometry. When a coordisystem change is requested, the FME completely transforms the feature, posschanging its type of geometry as it moves it to the new coordinate system.

The FME automatically extracts coordinate system information from those formwhich store this information. If a source format does not contain spatial refereninformation, then the user may specify it.

In any case, the coordinate system of the output format may also be specified.output coordinate system is different than the input one, then the FME will automatically convert the feature data. To ensure that the reprojection is accuraFME automatically vectorizes arcs, ellipses, rectangles, and rounded rectangle objects before doing the coordinate system change. In addition, text rotation anand sizes are adjusted during the change. The output system or format stores coordinate system of the data if it has the facilities to do this.

TIP: See Section 8, Coordinate System Support for more details.


Safe Software Inc. INTRODUCTION

lt is

this tible e

1.7 Summary

The FME provides a fully configurable geo-object-relational data processing environment with many capabilities. The FME’s processing abilities provide thebuilding blocks for solving difficult processing tasks quickly and easily. The resuthat 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, introduced a maintenance problem, as it resulted in a large number of incompaand inflexible translator programs. The FME solves this problem by allowing thsame translator program to be used to solve a variety of translation problems.




2

s in

and

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 format’s representation into another’s. Writer modules output the featurea 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, errors to a translation log file.

Feat

ures Features

TransformationModule

Reader Module Writer Module

Control File

Source FeatureData

DestinationFeature Data

Fea

ture

s

Feature Manipulation EngineArchitecture

Features

ExternalAttribute

DatabasesAttri

bute

Data

Feature Factory PipelineFeatures

Attribute

Data


FME ARCHITECTURE Safe Software Inc.

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 earth’s 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.

.

..

.

.. .

...

.. .

.... ...

.. .

.... ...


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



Coordinates: (477553,5360181,20)



ature

ecific

ture’s

of

ata ME alue

for

• 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 feattributes 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 spdata 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 feageometry. For example, the @Generalize function can be called on a feature tothin 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 librarypredefined 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 dto be extracted from or added to auxiliary attribute databases. Presently, the Fsupports only file-based attribute databases in the dBASE, comma separated v(CSV), column aligned text (CAT), or ASCII formats. In the near future, supportlive 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 ofthe available functions.

TIP: Functions operate on only one feature at a time.



ure r split rms

rce e the ute m by

l 12 ining

e mple, DE

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. Featfactories are able to combine input features together into one output feature, othem apart into numerous output features. For example, the polygon formationfeature factory combines line segments which have identical attribution, and fothem 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 souformat to a destination format. The first step in the transformation process is thmatching of a feature with the transformation specification which specifies howfeature is to be transformed. Matching is done based on feature type and attribvalues. When a match is found, the feature is transformed into its destination foradding, dropping, and modifying its attributes. For example, when translating features from an Intergraph Design File to ESRI’s SDE, linear features from levewith color 8 and style 0 could be correlated to features on the SDE layer contaroads, 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 somdestination which may be either a static file or another software system. For exathe IGDS writer module exports features to Intergraph Design Files, while the Swriter 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)



ecific

ll

ally

put stem

.

• 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 spdata 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 aFME 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, typicthe 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 inand output systems are given with the rules for transforming them from one syto the other.

See Section 6, FME Mapping File Syntax for a complete discussion of their syntax



Figure 2-1 FME Mapping File Structure

FME Control File Structure

Reader And WriterConfiguration

Feature Factory Pipeline Configuration :

Feature Factory 1

Feature Factory 2

Feature Factory N

Transformation Module Configuration:

Feature Definition Statements

Feature Correlation Rules




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.

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

SourceFeature


DestinationFeature

Tra

nsfo

rmat

ion

Fun

ctio

n (I

nver

se)

Tra

nsfo

rmat

ion

Fun

ctio

nTransferVariable


Safe Software Inc. FME FUNCTIONS

e

d to

g may uses will ation

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 thfunction 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 useproduce a histogram of a particular attribute’s range of values.

@Count(&numberOfLanes)

3.1.4 Attribute Functions

Any attribute function may be used as the value for a parameter, and this nestinbe arbitrarily deep. At run time, the FME invokes the deepest nested function, its result as the argument for the next function, and so on. Only functions whichreturn a value should be nested. All nested functions must be enclosed in quotmarks.

The example below produces a histogram of the feature types encountered:

@Count(“@FeatureType()”)



’s

es.

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 PointsShape dempoint type %pt elevation %zSAIF 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 featuretype to DemPoint, sets its pointType attribute to the value of the %pt transfer variable, which is spotElevation, and sets the destination features coordinatOnce this is done, the destination feature looks like:

Feature Type: dempoint


type spotElevation

elevation 1059.3

Coordinates: (477553.1, 5360181.4)


Safe Software Inc. FME FUNCTIONS

s

nslate en

Now the @ZValue function is invoked in the forward direction, since the SAIF line is the destination. This function takes its argument—the 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 ipassed to the SAIF writer, looks like:

3.3 Inverse Function Example

Consider the situation when the same transformation specification is used to traDEM points from SAIF into Shape. In this case, SAIF is the source line, and whthe 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 feature’s 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


pointType spotElevation

Coordinates: (477553.1, 5360181.4)




Coordinates: (477553.1, 5360181.4, 1059.3)




Coordinates: (477553.1, 5360181.4, 1059.3)



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


type spotElevation

elevation 1059.3

Coordinates: (477553.1, 5360181.4, 1059.3)


4

n

n

time. s are on,

cause d

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 correlatiotable 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 definitiois not activated.

• All feature and attribute value functions on feature factory definitionlines run in the forward direction.

• Feature factories are able to operate on more than one feature at aIn addition, they may output more than one feature. Feature functiononly able to make changes to the single feature they are operating although they may delete it.

Factories enable the FME to perform sophisticated processing tasks. Befactories may be combined with feature and attribute value functions, anchained 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.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.

FeatureProcessing

Unit

InputInterface

OutputInterface

Feature Factory

InputFeatures

OutputFeatures


Safe Software Inc. FME FEATURE FACTORIES

e the lude

ries , or

rface e

ng the

top to

om xit

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 oncinput source has been exhausted. Factories which fall into this category incthe PolygonFactory and the ArcFactory.

• Non-grouping factories operate on the features as they arrive. These factomay split a feature into many smaller features, collect statistics on featuresdelete passed-in features. Examples of non-grouping factories include theSamplingFactory and the PIPComponentsFactory.

4.1.3 Output Interface

The output interface is used to output features from the factory. The output inteis controlled by one or more OUTPUT clauses on a factory definition statement. Thfactory 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 theOUTPUT clauses are to set the feature type and attribute values of features leavifeature 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 frombottom:

• 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 frthe first factory down through the last one. It is impossible for a feature to eone factory and enter a factory defined earlier in the mapping file.



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.

FeatureFactory

FeatureFactory

FeatureFactory



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 factory’s 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.



ified. e

lause n is h of utput

from a the

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 feature’s area1 attribute before the featureis 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 specThe form of these directives varies from factory to factory and is described in thfactory 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 cspecifies the attribute names used to partition the input feature set. One partitiocreated for each unique combination of the values of the named attributes. Eacthese partitions is processed independently of every other partition. Features ofrom 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 emergefactory. OUTPUT clauses may also apply feature and attribute value functions tofeatures as they leave the factory.

Parameter Content

<attribute name> The name of the attribute used to define the group of features.



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.



FACTORY_DEF SAIF ArcFactory \INPUT FEATURE_TYPE Road::TRIM numberOfLanes 1 \END_NODED \OUTPUT LINE FEATURE_TYPE JoinedRoad::TRIM numberOfLanes 1



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.



be

s

ed

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—ForestCoverPIP—is sent on to the last factory. The other features flow on toprocessed 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 takeForestCoverPIP features from the earlier factory and outputs two types of features: tiedpnt and tiedpoly. These two types of features are then processby the rest of the system.




5

file.

ce sists e r to

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 feature’s 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

5.1 Transformation Specification

The transformation specification determines the mapping between sourfeatures and destination features. Each transformation specification conof a pair of lines: one line associated with the source format, and one linassociated with the destination format. The source line is used as a filte

SourceFeature


DestinationFeature


FME TRANSLATION PROCESS Safe Software Inc.

from

ontrol

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 ESRI’s SDE. It illustrates the use of the mapping file in directing the transformation between formats.

# -------------------------------------------------# Handle RoadsIGDS 12 igds_type igds_line igds_color 10 igds_style 3SDE ROAD NUMLANES 2 PAVED false

TIP: Note that these two lines control transformation in both directions – from IGDS to the SDE, as well asthe 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 RoadsIGDS 13 igds_type igds_line igds_color 10 igds_style 3SDE 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 ctransformation 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


Safe Software Inc. FME TRANSLATION PROCESS

n on

re

rce

es.

. They s at a

ched

ture to ute be

ature ft.

to ture he

n line, value

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. Whethe source line, constant values are the only attribute values used to matchfeatures. On the destination line, the constant values are used to set featuattribute values.

• Transfer Variable: A variable used to transfer an attribute value from the souline to the destination line. All transfer variables start with a percent (%) character.

• Attribute Function: A function whose return value is used to set attribute valu

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 wholemay be used to change a feature’s geometry, or operate on groups of attributesingle 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 matagainst 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 feamatch the source line, it must have the same feature type as the source line. Inaddition, the feature’s attribute values must have the same values as any attribconstants listed on the source line. Source lines also identify attribute values totransferred across to the destination line. Finally, the inverse operation of all fefunctions and attribute functions on the source line are executed from right to le

5.1.2 Destination Line

The destination line portion of a transformation specification is the pattern usedcreate an output feature once a match has been made. It is applied when a feamatches a source line and all the transformation variables have been loaded. Tfeature type of the output feature is set to the feature type listed on the destinatioand any constant attribute values are set. Attribute values may also be set to theof transfer variables loaded on the source line. Finally, all feature or attribute



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 3SAIF 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


numberOfLanes 2 paved false# -------------------------------------------------# Handle Four Lane Roads


numberOfLanes 4 paved false# -------------------------------------------------# Handle Single Lane Roads

IGDS 12 igds_type igds_line igds_color 4SAIF 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 feature’s level and for SAIF is the feature’s 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



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

SourceFeature


DestinationFeature

TransferVariable



te,

ich it same

rce

f the

nique ).

ords,

r ue is riable

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 feature’s attribute it is paired with. If the feature had no value for the attributhen 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 whis associated, is assigned the variable’s value. If the variable’s value was the 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 valuefunctions.

The net effect of the transfer variable is to move an attribute value from the soufeature to the destination feature. For example:

# -------------------------------------------------# Handle BridgesIGDS 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 obridges 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 uwithin 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 wthere is a default value for an attribute which will not be explicitly stored in the format. To accommodate transformations supporting such formats, the transfevariable syntax provides a means of specifying a default value. The default vallisted immediately after the transfer variable name, and is separated from the vaname by a colon (:). For example:



# -------------------------------------------------# Handle BridgesSAIF 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.




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 files1 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 changedto be consistent with Open Geodata Interoperability Specification (OGIS) terminology.


FME MAPPING FILE SYNTAX Safe Software Inc.

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.


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 8IGDS 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.



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.csnSAIF_CSN $(FME_CF_DIR)/trim32.csn



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.



ther ent

th

les, s lf.

the

e t was

h ich

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 user’s environment, rathan requiring them to be specified each time a mapping file is run. An environmvariable expansion is requested by enclosing the environment variable name wi${ 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 variabwhich will be expanded recursively when the outermost environment variable isubstituted. An environment variable may not, directly or indirectly, refer to itse

The FME flags any reference to an undefined environment variable, and stopstranslation if one is encountered.

6.11 Static Function Evaluation

In certain situations, it is convenient to execute an FME attribute function as thmapping file is parsed. The value returned from the function is then used as if ipart 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 wit$[ and ]. The function may take any type of arguments, including macros, whare 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”)]



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.




7

s

E.

s are:

rds. two

riter:

7 FME CONFIGURATION

Previous sections—1 through 6—have described the syntax and capabilitieof the FME processing facilities. Sections 10 through 25 describe the operation of the individual reader and writer modules available to the FMIn 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 keyword

READER_TYPE <readerType>WRITER_TYPE <writerType>

Any valid reader or writer module may be named following these keywoWhen the FME session is started, the mapping file is scanned for thesekeywords and the appropriate reader and writer are created.

The mapping file fragment below creates a SAIF reader and a Shape w

READER_TYPE SAIFWRITER_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 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 SAIFWRITER_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 IGDSWRITER_TYPE IGDSWRITER_KEYWORD I_OUT


Safe Software Inc. FME CONFIGURATION

# Name the input IGDS file. Note that since no# <ReaderKeyword> was specified, the default of IGDS# is usedIGDS_DATASET original.dgn

# Provide the name for the output IGDS fileI_OUT_DATASET newone.dgn

# Identify the seed file for the output IGDS fileI_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 %sI_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 file’s name:

LOG_FILENAME /tmp/fme.log



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.


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.




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.

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.


Safe Software Inc. COORDINATE SYSTEM SUPPORT

8.3 Coordinate System DefinitionThe 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 system—see 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



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.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



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.


<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



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



hich tion

e Y north.

8.5.1 AE: Albers Equal Area

8.5.2 AZMED: Lambert Azimuthal Equidistant Projection

There are two modes—point and azimuth. The modes differ in the manner in wthe relationship of the Y axis to true north is defined. In the point mode, the direcof the Y axis is defined by a point, given in latitude and longitude on the positivaxis. In the azimuth mode, the azimuth of the Y axis is given in degrees east of

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



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:


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:


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.


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



hich tion e Y

8.5.3 AZMEA: Lambert Azimuthal Equal Area Projection

There are two modes—point and azimuth. The modes differ in the manner in wthe relationship of the Y axis to true north is defined. In the point mode, the direcof the Y axis is defined by a point, given in latitude and longitude, on the positivaxis.

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.




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.



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.





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.


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.


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.



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]



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]


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.



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.




PARM1 Latitude, in degrees, of the reference parallel.






8.5.8 ECKERT4: Eckert 4 Projection

8.5.9 ECKERT6: Eckert 6 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. This is the X coordinate of the coordinate system origin.



ORG_LNG The longitude, in degrees, of the origin of the projection (central meridian).












8.5.10 GNOMONIC: Gnomonic Projection

8.5.11 GOODE: Goode Homolosine Projection


PARM1 Latitude, in degrees, of the reference parallel.







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.







8.5.12 LM: Lambert Conformal Conic Projection

8.5.13 LMTAN: Lambert Tangential Projection


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 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.


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.



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


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.5.15 MILLER: Miller Cylindrical Projection

8.5.16 MODPC: Modified Polyconic Projection


PARM1 Latitude, in degrees, of the central meridian of the coordinate system (or map).





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.






8.5.17 MOLLWEID: Mollweide Projection

8.5.18 MRCAT: Traditional Mercator Projection






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.


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.






8.5.19 MSTERO: Modified Stereographic Projection

8.5.20 NEACYL: Normal Authalic Cylindrical Projection


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.



SCL_RED This element must be set to 1.0.





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.






8.5.21 NZEALAND: New Zealand National Grid System

8.5.22 ORTHO: Orthographic Projection

8.5.23 PLYCN: American Polyconic Projection




SCL_RED This element must be set to 1.0.















8.5.24 ROBINSON: Robinson Projection

8.5.25 SINUS: Sinusoidal Projection








Y_OFF The false northing to be applied to all Y coordinates.This is the Y coordinate of the coordinate system origin.


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.





hich tion e Y

8.5.26 STERO: Stereographic Projection

There are two modes—point and azimuth. The modes differ in the manner in wthe relationship of the Y axis to true north is defined. In the point mode, the direcof the Y axis is defined by a point, given in latitude and longitude, on the positivaxis.

In the point mode, the following parameters must be set:


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.




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.



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.




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.


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.




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.





SCL_RED The scale reduction factor to be applied. This is also referred to as the scale of the central meridian.





8.5.28 TM: Transverse Mercator

.

8.5.29 VDGRNTN: Van Der Grinten 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.This is the Y coordinate of the coordinate system origin.




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



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




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)




NHRWN-S Nahrwan, Saudi Arabia

NHRWN-U Nahrwan, United Arab Emirates

NAPARIMA Naparima, BWI; Trinidad & Tobago

NTF Nouvelle Triangulation Française, France

NTF-PM Nouvelle Triangulation Française, 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




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


YACARE Yacare, Uruguay

ZANDERIJ Surinam


<datumName> any string The name of the datum being defined.

No

<descriptive name>

any string A descriptive name for the datum.

Yes




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-DENSKYBURSAMULREGNAD27NAD83WGS84WGS72HPGNLCLGRF

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




ain a

y it

will

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 obtcopy of the data file. Contact:

Information Services, Geodetic Survey Division, Geomatics Canada, 615 Booth Street, Ottawa, Ontario, K1A 0E9

(613) 995-4410, [email protected]://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. Ifyou are in Canada and doing NAD Shifts, you should obtain thentv2.gsb from Geomatics Canada.

• To use version 1 of the national transformation, obtain the grid file and copinto 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 FMEuse version 2. If neither are present, the FME will issue a warning and use an approximation of the transformation.



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




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



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




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


WGS66 World Geodetic System of 1966 / NWL 8D

WGS67 World Geodetic System of 1967, Lucerne




<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




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




9

e s a

his

The or

and ,

the

9 FME INTERFACES

9.1 Command Line Interface

While the FME’s graphical user interface is well suited for most uses, thFME also has a flexible command line interface enabling it to be used acomponent of a batch processing environment.

Although a graphical user interface may be wrapped around the FME tosimplify its operational use, at its core the FME is a command line utility. Tmakes 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 parameterspertaining to the translation session are extracted from the mapping file.optional additional arguments on the command line are used to overridesupplement 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 commline simply by listing the keyword which is optionally preceded by a dashfollowed by its new value. Any values for the keyword that are already inmapping file will be overridden by the new value. There is no limit on the


FME INTERFACES Safe Software Inc.

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.


Safe Software Inc. FME INTERFACES

d line er:

lar

d the er

ng pping E

ser be nal

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 file’s definitionoverrides 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 commaninterface. To generate a mapping file, the FME is invoked in the following mann

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 particutranslation. 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 translateall 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, anconfiguration of the FME itself. This subsection describes the configurable usinterface that ships with the FME.

There are two types of FME users. One type prepares FME mapping files, tunithem for the data model of the organization. The other uses pre-made FME mafiles, supplying a few parameters, such as a filename or directory, to perform atranslation. This second type of user is able to harness the full power of the FMwithout understanding its detailed workings.

To accommodate this second type of user, a mapping file may specify that the uprompted for some missing parameters when the mapping file is run. The origi



nd to

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 box1 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 adefine the macro named by <macroName>. All occurrences of the macro in the mapping file are replaced by the user’s 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.



d.

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 displaye

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” thataccepts 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:



nly

nly

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 ointegers. 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 ofloating 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.



only

d with

cters.

es to

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 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 requestea 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 charaAs each character is entered, the PASSWORD field displays an * to keep the contentsof 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 interfacbe easily constructed. This greatly simplifies the task of using the FME for operational data translation.




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.

yer

n

ed

the

on

bles

ual or,

and

nded

orld s they

es ing ntly

2. TABLES: This contains a variety of tables including the following.

• Layers: Each layer entry contains layer definition information such as lacolor, layer name, and layer line type.

• Linetypes: Each linetype entry contains the linetype definition informatiosuch as name, and alignment. The AutoCAD writer enables line type definitions to be copied from an existing AutoCAD file and then referencby name during the data translation.

• Shape Files: Each shape file entry identifies a shape file referenced by 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 applicatireferenced within the AutoCAD file.

3. BLOCKS: These are used to define symbols and other drawing file objectswhich are used repeatedly throughout a drawing. The AutoCAD writer enablock 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 actfeature entities. Each entity contains standard information, such as its collayer, thickness, linestyle, and geometry, as well as a number of attributesspecific to its entity type. For example, a text entity has fields for font, size,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 exteentity 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 wcoordinates. As such there is no need to scale or otherwise alter coordinates aare being read from or written to a drawing file.

The AutoCAD reader and writer use symbolic names for the different entity typstored within a drawing file. This simplifies feature type specification. The followtable gives a brief description of each of the different AutoCAD entity types curresupported by the reader and writer. The entities are described in detail in the subsequent sections.


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.



ion.

in e

le the

in the

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 definit

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 combinedsubsequent processing. Arbitrarily deep block nesting is permitted, however thautocad_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 filines. These line types can then be referenced by features being written toAutoCAD 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 withfeature.

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



.

ation

ing

m

ot

resent

• Copy Block Definitions: Often users have existing AutoCAD drawing files which contain block definitions which they want the translated data to carrySpecifying 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 destinfile. Specifying the TEMPLATEFILE keyword in the mapping file results in the pre-defined line types being copied from the template file to the output drawfile. 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 frothe file specified by the TEMPLATEFILE directive.

• Automatic Block Creation: When a feature is passed to the writer which cannbe written as a single autocad entity (such as a donut polygon) the writer automatically defines an autocad block and insert entities necessary to repthe 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.



in

is

tten

n in

.

able ich

n the

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 writtenthe DWG format.

• Otherwise if the filename contains “.dxf” or “.DXF” then the output dataset written in DXF format.

• Otherwise if the specified writer type is DWG then the output dataset is wriin the DWG format.

• Otherwise if the specified writer type is DXF then the output dataset is writtethe 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 FMEmapping file to be used to create both DXF and DWG output files. Users areto specify which they want simply by changing the suffix of the output file whis being produced.

10.3.1 Writer Keywords

The AutoCAD writer processes several keywords in the mapping file, as shown ifollowing 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.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




e

ths)

gths)

as

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 thlinetype 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 leng

• positive value — pen down length (used to make dashes of varying len

• zero — used to create a dot.

The following example creates a line type called dash-dot which looks appears“ __ . __ . __ . ” 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



ich

d lid

o

r. If t with ing

n ess ll be

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 whis used throughout the remainder of the FME mapping files.

• <default color>: The color number which is used for all features storewithin the layer unless explicitly overridden on the correlation lines below. Vavalues are between 0 and 256.

• <default line type>: The name of the line type to use for the layer if nline type is specified on the correlation line. The line type specified must beeither:

• 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 layeno attributes are defined then all feature attributes (except those which starautocad_ are stored. The storing of attributes can be turned off by specifya 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 drawusing color 13 (unless otherwise specified), and a linetype called dash-dot (unlotherwise specified). The feature also has several attributes specified which wiwritten to the extended entity data of each feature within the layer.

1. Layers can also be defined through the use of a TEMPLATEFILE.



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 layer2 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. Thisenables the layer name to be extracted without the need to use the�@FeatureType�function.

Attribute Name Content

autocad_layer The name of the feature’s layer. This is the same value as the feature’s 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 entity’s layer; otherwise, the number specified determines the color of the entity.

Range: 0...256Default: 256

autocad_linetype The name of the feature’s linetype.

Range: char[33]Default: BYLAYER

autocad_thickness The thickness of the entity’s lines.

Range: 64 bit RealDefault: 0



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-1Default: 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





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: 1001Example: application_name:ACAD

autocad_layer The name of the layer the extended data is associated.AutoCAD Code: 1003Example: autocad_layer:Water

string A character string value from 0 to 255 characters in length.AutoCAD Code: 1000Example: string:Thompson

three_reals Three 64 bit real numbers separated by commas.AutoCAD Code: 1010,1020,1030Example: 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, 1031Example: 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, 1032Example: 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,1033Example: world_direction: 30.0, -12.4, 10

real A 64 bit real number.AutoCAD Code: 1040Example: real:3.1415926

distance A 64 bit real number which represents a distance.AutoCAD Code: 1041Example: distance:4.56

scale A 64 bit real number which represents a scaling factor.AutoCAD Code: 1042Example: scale:34.5

16Bit_integer A 16 bit integer value.AutoCAD Code: 1070Example: 16Bit_integer:245

32Bit_integer A 32 bit integer value.AutoCAD Code: 1071Example: 32Bit_integer:12983



For example, if the following data was stored in extended entity data:

1001 C_NODE1000 CONNOBJ_1=43F41000 COUNT=31000 CONNOBJ_2=43F31000 CONNOBJ_3=43F21010 45.41020 -123.51030 01001 DPRINT1000 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{5} three_reals:45.4,-123.5,0

extended_data_list{6} application_name:DPRINT

extended_data_list{7} string:postscript



For example, given the following extended entity data:

1001 C_NODE1000 CONNOBJ_1=43F41000 COUNT=31000 CONNOBJ_2=43F31000 CONNOBJ_3=43F21010 45.41020 -123.51030 01001 DPRINT1000 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{#}.real1three_reals{#}.real2three_reals{#}.real3

Three real numbers.AutoCAD Code: 1010,1020,1030

world_position{#}.xworld_position{#}.yworld_position{#}.z

Three values represent the x, y, and z components of a world_position value.AutoCAD Code: 1011, 1021, 1031

world_displacement{#}.xworld_displacement{#}.yworld_displacement{#}.z

Three values which represent a world displacement value.AutoCAD Code: 1012, 1022, 1032

world_direction{#}.xworld_direction{#}.yworld_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



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.


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


CONNOBJ_1 43F4

COUNT 3

CONNOBJ_2 43F3

CONNOBJ_3 43F2



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.


Number ofCoordinates

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.


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.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.


autocad_primary_axis The length of the semi-major axis in ground units.Range: Any real number > 0Default: No default

autocad_secondary_axis The length of the semi-minor axis in ground units.Range: Any real number > 0Default: 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



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 > 0Default: 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 > 0Default: 0

autocad_oblique The oblique angle of the shape.

Range: -360.0 ..360.0Default: 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 numberDefault: 0

autocad_shape_height The height of the shape.


autocad_shape_width The width of the shape.




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.


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.


autocad_edge_1 The visibility of the first edge of the Face.

Range: visible|invisibleDefault: visible

autocad_edge_2 The visibility of the second edge of the Face.


autocad_edge_3 The visibility of the third edge of the Face.


autocad_edge_4 The visibility of the final edge of the Face.





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.


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.


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 doesn’t support rotation of arcs at this time.

Range: 0 Default: 0

SecondaryAxis

Rotation = 0

StartAngle= 135

SweepAngle= 135

PrimaryAxis

rotation



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.


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.


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.


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.


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



a. AutoCAD shape files should not be confused with ESRI Shape files. The former hold fontand symbol definitions; the latter hold spatial features.

autocad_text_size The text height.


autocad_oblique The oblique angle of the shape.

Range: -360.0 ..360.0Default: 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 fonta definition.

Range: char[65];Default: txt

autocad_shape_rotation The angle for the text as defined in shape file.


autocad_shape_height The height of the text as defined in shape file.


autocad_shape_width The width of the text as defined in shape file.


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




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.


autocad_xscale The scale factor for the inserted block in the x direction.


autocad_yscale The scale factor for the inserted block in the y direction.


autocad_zscale The scale factor for the inserted block in the z direction.


autocad_rotation The rotation of the inserted block, counterclockwise from horizontal.

Range: -360.0 ..360.0Default: 0

auotocad_number_columns The column count for the insert.

Range: 0..65536Default: 1

autocad_number_rows The row count for the insert.

Range: 0..65536Default: 1

autocad_column_distance The column spacing for the insert.


autocad_row_distance The row spacing for the insert.


autocad_block_name The name of the block entity which is to be inserted.

Range: char[33]Default: No Default

rotation



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 | falseDefault: true

autocad_attribute_display Indicates if the attribute values are to be visible or invisible.

Range: visible | invisibleDefault:invisible

autocad_<attr_name>_xautocad_<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 valueDefault: x and y value of insert coordinate




GUI FILENAME autocadFileDXF_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 entitiesDWG * 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 ellipseDWG * 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 ShapesDWG * 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) \



FILENAME char(65) \ROTATION number(14,6) \HEIGHT number(14,6) \WIDTH number(14,6)

#---------------------------------------------------------------# autocad TextDWG * 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 arcsDWG * autocad_entity autocad_arc \

$(StandardAutocadAttrs) \autocad_primary_axis %primary \autocad_secondary_axis %secondary \autocad_rotation %rotation \autocad_start_angle %startangle \autocad_sweep_angle %sweepangle



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 entitiesDWG * autocad_entity autocad_trace \


SHAPE trace \$(autocadinShapeAttrs)

SHAPE_DEF trace SHAPE_GEOMETRY shape_polygon \$(autocadinShapeAttrDefs)

# ---------------------------------------------------------------# autocad Solid entitiesDWG * autocad_entity autocad_solid \


SHAPE solid \$(autocadinShapeAttrs)

SHAPE_DEF solid SHAPE_GEOMETRY shape_polygon \$(autocadinShapeAttrDefs)

#---------------------------------------------------------------# autocad Insert EntitiesDWG * 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



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 polygonDWG * 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 FaceDWG * 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 entitiesDWG * autocad_entity autocad_ray \


SHAPE ray \$(autocadinShapeAttrs)

SHAPE_DEF ray SHAPE_GEOMETRY shape_arc \$(autocadinShapeAttrDefs)



#---------------------------------------------------------------# autocad XLINE entitiesDWG * autocad_entity autocad_xline \


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 SHAPEWRITER_TYPE DWG

# Specify the version of DWG file which is to be written. # Either “Release11”,“Release12”, or “Release13” are currently# supported.DWG_VERSION Release12



#===============================================================# 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 \



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)



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




11

I

by ch is he with nal c

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 feature’s properties. MOEP files can store only integer coordinates.

The MOEP reader and writer modules provide the Feature ManipulationEngine (FME) with the capability to read and write files in binary MOEPformat, with either 16-bit or 32-bit integer coordinates. Support for ASCIMOEP 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 followeda sequence of geometric features. The header contains information whiglobal to the MOEP file, including a file type, a name for the content of tfile (such as a mapsheet ID), and whether the coordinates are specified16-bit or 32-bit integers. Each feature has a feature code, a single optioattribute, a geometric type (point, line, text, etc.), and some type-specifiinformation (coordinates, rotation, text size, etc.).


B.C. MINISTRY OF ENVIRONMENT AND PARKS (MOEP) READER/WRITER Safe Software Inc.

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.


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:


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


Safe Software Inc. B.C. MINISTRY OF ENVIRONMENT AND PARKS (MOEP) READER/WRITER

to fill

M tes:

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 file’s header. The writer uses the global attributes 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 DEdata with 16-bit coordinates, and one containing contours, with 32-bit coordina

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 attribute’s value.)

MOEP_FILE_TYPE An integer in the range 0..9 denoting the type of data this filecontains.

MOEP_NAME An ASCII string (0 to 11 characters in length) providing a logical name for the file. This is stored in the file’s 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 withinthe month (01-31).

MOEP_OFFSET_MINIMUM The MOEP writer module uses this value to determine theorigin 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 on32-bit coordinates, which are always measured from (0,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


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.




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:


moep_type The type of the geometry for the feature. This attribute will contain one of:

moep_linemoep_contour_linemoep_pointmoep_textmoep_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.)



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.


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.)


moep_contour_elevation The elevation of the contour line.


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.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.


moep_sweep_direction The direction in which the arc is drawn. Legal values are clockwise and counter-clockwise. (The default is clockwise.)


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



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 SourceDatasetMOEP_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.#



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 \



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)



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 SHAPEWRITER_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.



#

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



#===============================================================

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) \



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
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 referto the ISFF format.


DESIGN FILE READER/WRITER Safe Software Inc.

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


Safe Software Inc. DESIGN FILE READER/WRITER


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.


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.



rsion ternal ile.

lt to file.

port r the

in rary

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>.


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 file’s header information to the destination file, and then extracts the conveparameters required to translate coordinates from feature coordinate units to inIGDS Units of Resolution (UORs)2. It also determines the dimension of the seed f

Because seed files with a sufficient ground range and resolution may be difficuobtain, the IGDS writer allows seed parameters to be overridden in the mappingWhen a seed file with insufficient range available is used, the IGDS writer will rethat features were outside of the bounds of the seed file, and suggest values foglobal origin and UOR/subunit/master unit ratios to use.

A cell library file may optionally be used by the IGDS writer. Cell libraries contanamed symbol definitions which can be used to depict point features. If a cell lib

2. Since coordinates in design files are ultimately stored as integer UORs, it is possible for precision tobe lost or overflow to occur when they are output. Care must be taken to ensure that the conversionparameters in the seed file preserve the data precision and range.


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



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.


The IGDS writer processes several keywords in the mapping file, as shown in the following table. These are all prefixed by the current <WriterKeyword>.


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 file’s 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



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.dgnIGDS_SEED_FILE /usr/data/dgn/2dseed.dgnIGDS_CELL_LIBRARY /usr/data/dgn/cartog.cel


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


igds_color The element’s color setting.Range: 0..255Default: 0

igds_class The element’s class.Range: 0..15Default: 0

igds_graphic_group The element’s graphic group number. Range: 0..65535Default: 0




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 element’s line style. Range: 0..7Default: 0

igds_type The FME name for the type of element this feature represents.Range: See Table in OverviewDefault: No default

igds_weight The element’s line weight. Range: 0..31Default: 0

Linkage Parameter Contents

type The type of linkage.Range: user|dbase|

oracle|informix|risDefault: No default

class Linkage Class.Range: 0..15Default: 0

ibit Linkage ibit value.Range: 0|1Default: 0

mbit Linkage mbit value.Range: 0|1Default: 0

rbit Linkage rbit value.Range: 0|1Default: 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|1Default: 1


userId The user -ID of the linkage. This is application specific.Range: 0..65535Default: 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 integerDefault: 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..65535Default: 0


entity_number The entity number of the linkage. Range: 0..65535Default: 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 integerDefault: No default




s e ents cell

uence p

d oint

MACRO fillUserId 65MACRO fillMagic 67586IGDS 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 cell’sdefinition. Instead, FME features representing IGDS cells contain only the cell’name, as well as rotation and scaling parameters. The IGDS reader skips all thelements which define the cell (extracting only the text strings from any text elemin the cell), and the IGDS writer will extract the cell description from the supplied 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 seqnumber in the igds_cell_sequence. This number can be used to later regrouthe cell with its components if that is required.

Both graphic and point cells are supported. Graphic cells use the level, color, anstyle information from the cell library, and must always have a feature type of 0. Pcells use the level, color, and style information provided in the mapping file.


igds_cell_name The name of the cell. Corresponds to the name of the cell in a cell library.Range: Character StringDefault: No default

igds_cell_x_scaleigds_cell_y_scaleigds_cell_z_scale

The scaling factors to apply to the cell.Range: Any real number > 0Default: 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: 0rotation



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 element3 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 theFME.

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.





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:


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.


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.


IGDS Element

Type

Description



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.


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..255Default: 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/Top1 is Left Margin/Center2 is Left Margin/Bottom3 is Left/Top4 is Left/Center5 is Left /Bottom6 is Center/Top7 is Center/Center8 is Center/Bottom9 is Right/Top10 is Right/Center11 is Right/Bottom12 is Right Margin/Top13 is Right Margin/Center14 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.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.


igds_curve_slope{0}.xigds_curve_slope{0}.yigds_curve_slope{0}.zigds_curve_slope{1}.xigds_curve_slope{1}.yigds_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}.xigds_curve_slope{2}.yigds_curve_slope{2}.zigds_curve_slope{3}.xigds_curve_slope{3}.yigds_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.



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.


igds_primary_axis The length of the semi-major axis in ground units.Range: Any real number > 0Default: No default

igds_secondary_axis The length of the semi-minor axis in ground units.Range: Any real number > 0Default: 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




igds_primary_axis The length of the semi-major axis in ground units.Range: Any real number > 0Default: No default

igds_secondary_axis The length of the semi-minor axis in ground units.Range: Any real number > 0Default: 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.0Default: 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 > 0Default: 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

SecondaryAxis

Rotation = 90

StartAngle= 45

SweepAngle= 135

PrimaryAxis

rotation



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.


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..255Default: 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



.

tes of

, then

ion ent.

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 list’s 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 coordinaits own, the text node is created with the coordinates of the first text string. Thecoordinates for each of the text strings are stored in the FME feature using thefollowing 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 specifiedthe corresponding settings will be borrowed from the text node.

For example, the FME feature specified by the below partial transfer specificatwould create a text node, followed by two text strings, as a single complex elem

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 \


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



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



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_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}.z 20


igds_text_elements{1}.igds_font 33



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}.z 20

Coordinates: (477553,5360181,20)


igds_fill_color The color used to fill the solid.Range: 0..255Default: 0

Feature Type: 32




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 IGDSREADER_TYPE SHAPE

# Stuff the IGDS Writer needs to know about. IGDS_DATASET tracts.dgnIGDS_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 65MACRO fillMagic 67586

#---------------------------------------------------------------# Color macros -- nice names for an IGDS Color Map

MACRO white 0MACRO blue 1MACRO green 2MACRO red 3MACRO yellow 4MACRO magenta 5MACRO orange 6MACRO turq 7MACRO black 8MACRO grey 9MACRO darkGreen 114MACRO cyan 121MACRO purple 125MACRO indianRed 83MACRO baise 84MACRO medPurple 85MACRO darkGray 144MACRO seventies 164MACRO brown 126MACRO desktop 159MACRO nt 95MACRO bisque 217



#---------------------------------------------------------------# 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



# ---------------------------------------------------------------# 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.


f both

nal

ay e

or

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 othese ways: standard, optional, and graphics formats. The FME supportsthe standard and the optional DLG distribution formats. However, the graphics format is not supported. Most DLG data is distributed in the optioformat.

13.1 Overview

DLG data files consist of ASCII fixed field records. The records may or mnot be stored with embedded carriage returns or end of line markers. Thintelligently determines the end of each record, and interprets files with without explicit end of record markers.


DIGITAL LINE GRAPH READER Safe Software Inc.

e any

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.


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 doesn’t havrequirement 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.


Safe Software Inc. DIGITAL LINE GRAPH READER


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.1 Dataset

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.


DATASET Contains the filename of the input DLG dataset. Required


dlg_type The DLG geometric type of this entity.Range: dlg_point|

dlg_line|dlg_area

Default: No default

dlg_element_number The element’s 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 ElementL = Line ElementA = 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



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




al f

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 lines—lines containing two identicpoints—the DLG reader converts these into standard points with a single set ocoordinates.

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)”




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


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.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.


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


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



he

d

l

hich

category abbreviations as outlined in the DLG standards—see the next table. Tgeometry of each feature is appropriate to the dlg_type: dlg_point features have a single coordinate pair, dlg_line features contain multiple coordinates, andlg_area features define closed polygons with holes where appropriate.

Table 13-1 DLG Categories

All features share several attributes however, the feature will contain additionafeature coding specific to the feature type. These are described in subsequent sections. All features tagged with major and minor codes of zero, indicating anoutside area, are deleted.

13.3.2 DLG Attributes

The following table lists the different DLG attributes attached to every feature whas 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, andMiscellaneous Transportation Features

MT

Man-made Features MS

U.S. Public Land Survey System PL


dlg_element_number The element’s internal identification number. The numbers are unique, positive, and sequential within each element type.Range: 1 - 32000



13.3.3 Hypsography

FEATURE_TYPE: HP

This category of data consists of information on topographic relief—primarily contour data—and 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 feature’s 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




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.


elevation The elevation of the feature. The description attribute indicates whether the units are feet or meters.Range: -99999999.9 - +99999999.


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.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.


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.



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


There are several attributes specific to Railroads features.


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”


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.


numberOfTracks The number of tracks the railroad has.




13.3.11 Pipelines, Transmission Lines, and Miscellaneous Transportation Features

FEATURE_TYPE: MT


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.




featureWidth Width in mils of feature to scale.




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. #


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



# 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:



# =========================================================================# 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)



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



## 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 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.

iles s the

bfiles files ated

utes


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.


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 subfand certain info files. The reader itself does not form these relations, but provideattributes on the features allowing the mapping file to form the relations. Automatically generated mapping files form the necessary joins between the suand the info files, and are a good starting point when creating custom mappingto read E00 data. A description of the features output from automatically genermapping files is given in subsection14.5 titled Generated Mapping Files.

The following table summarizes the geometry types and lists the additional attribrequired to fully define the geometry, as is the case for text features.


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_stringe00_rotatione00_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



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.




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>


*_pointattr None E00_FEAT_ROLE = “e00_point_attr”

AREA = 0.0

PERIMETER = 0.0

*_ID = <id of point>

*# = <coverage # of point>


*.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>




an res

T at

long ight

FME e are e line s the

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 haveattribute named e00_type, whose value is the geometry type. For example, featufrom 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 TXsubfiles of the E00 coverage. This geometry consists of a text string, a locationwhich to draw the text, and optionally a string of points that form a curved line awhich to place the characters. Additionally, text features from the TX6 subfile mhave arrows associated with them.

When these features are read into the FME, the form changes slightly. Since thedoes not currently support text along a line, the start and end points of the text linused to compute the average rotation of the characters, and the first point in thbecomes the text's position. The text feature's geometry is a point which defineposition, 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 = “.+”





with

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 layer’s name is contained in the feature’s 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 feature’s sequence number, starting at 1, within the layer.

If there are no named annotation layers in the coverage—as is always the caseannotation from the TXT subfile—all 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 feature’s e00_anno_name and e00_anno_id attributes with the attribute feature’s 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.



s

aning tate,

e

f the

ntly zed, are

ed by

e

ature. of the

subfile come from a different info file than those for text from the TX6 subfile—*.XCODE rather than the *.TAT+ info file—but the E00 reader forms the featuregenerated from the two info files identically.

14.3.4 Tolerances

E00 coverages contain a list of ten tolerance values, which have a specific mewithin ArcInfo. Each tolerance has a numerical identifier in the range 1..10, a sand a floating point value.

The E00 reader generates ten features from the TOL subfile. Each feature contains thfollowing 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 oinformation 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 appareunnamed parameters. Any of the named parameters, whose names are recognidefined as standard attributes—datum, projection, units, etc.) on the e00_projection feature. Named parameters, whose names are not recognizthe reader, are placed into the attributes unknown_parameter{}.name and unknown_parameter{}.value. Unnamed parameters are placed into thattribute list param{}.value.

At the present time, the E00 reader does not attempt to interpret the projection feTherefore, the coordinate system of E00 features must be set through the use _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.



the

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 file’s 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 file’s 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 topology—left polygon, right polygon, fromnode, to node—are also defined in the info file, and will appear as attributes onresulting arc features.



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.


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.


e00_type e00_point

<prefix_ID> Numerical identifier for point feature.

<prefix>_ Sequence number of the point feature.

PERIMITER 0.0



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


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 polygon’s centroid.

e00_centroid_y Y coordinate of polygon’s centroid.

PERIMITER Outer perimeter of polygon.

AREA Area of the polygon, measured in square ground units.



xt to

e

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 subfile—as opposed to the TXT subfile—it might have a separate linear portion that acts as an arrow pointing from the teanother 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 thcorresponding <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.


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.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 FileGUI 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 TextMACRO ShapeArrow TextArrow

# =======================================================================# The input will be the “<FileBase>a.e00” file in the specified directory.

READER_TYPE E00READER_KEYWORD E00_INE00_IN_DATASET “$(SourceDataset)/$(FileBase)a.e00”

# ======================================================================# Now define our output

WRITER_TYPE SHAPEWRITER_KEYWORD SHAPE_OUTSHAPE_OUT_DATASET “$(DestDataset)”

# =======================================================================



# 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

# =======================================================================



E00_IN e00_textarrow \e00_type e00_arc \e00_anno_id %anno_id

SHAPE_OUT $(ShapeArrow) \ANNO_ID %anno_id




15

ge.

les in

g file

held cans

For

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 ArcInfo’s TINning packaText Generate Files are defined to accept only two- dimensional (2D) coordinates.

The FME considers a Generate dataset to be a collection of Generate fia 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 mappinbefore 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.


The Generate reader module produces FME features for all feature datain Generate files residing in a given directory. The Generate reader first sthe directory it is given for all Generate files defined in the mapping file.


ESRI ARCINFO GENERATE FILE READER/WRITER Safe Software Inc.

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.


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>”]


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 file’s 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


Safe Software Inc. ESRI ARCINFO GENERATE FILE READER/WRITER

oint

files will

The filename of the Generate file is the basename plus the .gen extension.

The mapping file fragment below defines two Generate files—one containing pfeatures and the other containing linear features:

ARCGEN_DEF nodes ARCGEN_GEOMETRY arcgen_pointARCGEN_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 Generatewill be read. If no IDs are specified, then all defined and available Generate files 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


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.


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.




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,7602,53,21603,19,20END

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



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:

10132,52,133,56,236,59,631,70,3END10252,32,353,56,556,29,161,73,14ENDEND

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 Maves102,52,32,90,30,Barnie MavesEND

The attributes used by the generate reader and writer are described in the table below.


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.



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 filesARCGEN_DATASET /usr/data/generate/92i080# ---------------------------------------------# Define the type of each of the Generate filesARCGEN_DEF nodes ARCGEN_GEOMETRY arcgen_point

# ---------------------------------------------# This second file uses a space as the delimiterARCGEN_DEF boundaries ARCGEN_GEOMETRY arcgen_line \

ARCGEN_DELIMITER “ “

# ---------------------------------------------# Now define the location of the Shape files# which will be createdSHAPE_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 specificationsARCGEN nodes arcgen_id %nodeNumSHAPE markers MARK_ID %nodeNumARCGEN boundaries arcgen_id %boundNumSHAPE 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:



then the FME features shown below would be created by the Generate reader.

nodes.gen boundaries.gen

601,7,7602,53,21603,19,20END

10132 52 133 56 236 59 631 70 3END10252 32 353 56 556 29 161 73 14ENDEND

Feature Type: nodes


arcgen_id 601

Coordinates: 37,7

Feature Type: nodes


arcgen_id 602

Coordinates: 53,21

Feature Type: nodes


arcgen_id 603

Coordinates: 19,20



These features would then be transformed by the FME and output to their destination Shape files by the Shape writer.

Feature Type: boundaries


arcgen_id 101

Coordinates: (32,52,1),(33,56,2),(36,59,6),(31,70,3)

Feature Type: boundaries


arcgen_id 102

Coordinates: (52,32,3),(53,56,5),(56,29,1),(61,73,14)


16

e s for fo ssing

al ns:

three

16 ESRI SHAPE FILE READER/WRITER

The ESRI Shape File reader and writer modules provide the Feature Manipulation Engine (FME) with access to ESRI’s Shape file format. ThShape file format is the native format of ESRI’s ArcView product and habeen made public by ESRI. Recent releases of ArcInfo contain support direct and very fast import, and for export of Shape files. Users of ArcInmay use Shape files to provide a bridge between the formats and procecapabilities supported by the FME and ArcInfo coverages.

16.1 Overview

Shape files store both geometry and attributes for features. No topologicinformation however is carried in a shape file. A single logical shape fileconsists of three physical files, that have one of three file name extensio

These extensions are added to the basename of the shape file creatingseparate 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.

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.


Safe Software Inc. ESRI SHAPE FILE READER/WRITER


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.


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



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.


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 file’s 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



file th. The

ear

ead. yntax

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 file’s attributes is logged to the log file. All Shapeattribute names must be uppercase and must not exceed 10 characters in lengfollowing table shows the attribute types that are supported.

The following mapping file fragment defines two Shape files—one containing polygonal features possibly disjoint and with holes, and the other containing linfeatures:

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 rIf no IDs are specified, then all defined and available Shape files are read. The sof 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.



<ReaderKeyword>_IDs <baseName1> \ <baseName1> … \ <baseNameN>


The example below selects only the roads Shape file for input during a translation:

SHAPE_IDs roads


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.


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.


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.


SHAPE_GEOMETRY The type of the geometry read from the shape file. This attribute will contain one of:shape_pointshape_multipointshape_arcshape_polygonshape_null



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 filesSHAPE_DATASET /usr/data/shape/92i080

# ---------------------------------------------# Define the attributes and type of the Shape# file to be createdSHAPE_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 readIGDS_DATASET /usr/data/dgn/92i080.dgn

# ---------------------------------------------# Now define transfer specificationsIGDS 17 igds_color 7 igds_class 3 \

igds_type igds_lineSHAPE 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




17

) by

both

17 ESRI SDE READER/WRITER

ESRI’s Spatial Database Engine (SDE) brings Geographical InformationSystems (GIS) into the realm of Management Information Systems (MISproviding a spatial interface to industry standard Relational DataBase Management Systems (RDBMS).

The SDE enables a Relational DataBase Management System to store spatial and non-spatial data.

Spatial Database Engine(SDE)

RDBMS InterfaceLayer

RDBMS(ORACLE, ODBC, ...)

Spatial Database Engine


ESRI SDE READER/WRITER Safe Software Inc.

ature o-

red. rows

ixed

atures l efore

to the

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 types1 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 fetype. The spatial index for each layer consists of between one and three twdimensional (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 stoThere is a 1 to 1 mapping between the features in the feature type and thein the relational table.

• All features in a feature type must be either 2D or three-dimensional (3D). Mdimensionality 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 Engine’s (FME) SDE reader and writer modules takeadvantage of the unique capabilities of the SDE. The reader module retrieves fefrom the SDE by constructing queries consisting of both spatial and non-spatiacomponents. An SDE database may have a very large number of features therthe query building capability is critical to ensure that the FME reader module iscapable of satisfying highly focused data requests. The writer module takes advantage of the SDE’s transaction model to ease the task of importing data inSDE.

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.


Safe Software Inc. ESRI SDE READER/WRITER

set up

e

nce

ified

n of

ture

ta

ta

. For gine FME

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 ESRI’s SDE, and greatly reduce the time required to 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 attributtables. 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 performaof the non-spatial component of searches.

• Programmatic Layer and Attribute Verification: When loading data into anexisting spatial database, the FME verifies that the feature definitions specin 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 duplicatiodata.

• 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 feaidentifiers it writes to an SDE log file.

• Attribute Query Support: SQL where clauses can be specified to limit the dabeing exported.

• Spatial Query Support: Simple spatial query support can be used to limit dabeing 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 productsexample, a user with a sophisticated Graphical User Interface (GUI) search encan easily identify all features satisfying a complicated query and then use the with the SDE reader module to process these features.




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 KeywordSuffix

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.




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 KeywordSuffix

Description



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.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.



es

e

E

r

and

he

ches

e

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 testdsetSDE_SERVER tuvokSDE_WHERE where NUMLANES=2SDE_SEARCH_ENVELOPE 601190 5437839 611110 5447549SDE_IDs roads


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 easthe data loading process. Occasionally, a data load operation terminates prematurely due to data difficulties. The transaction support provided by thSDE 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 FMmapping file to automatically create SDE dataset layers as needed.

• Layer Validation: When data is loaded into an existing layer, the FME writemodule performs validation operations between the layer definition in the mapping file and that within the SDE. Any discrepancies found are logged the data load operation is halted.

• Attribute Creation: Attribute tables are also created using information from tFME mapping file.

• Attribute Index Creation: The SDE writer module can also define attribute indices. Attribute indices are specified to increase the performance of searhaving a non-spatial component.

• Feature Logging Support: The SDE writer module can be directed to write thfeature identifiers (IDs) to an SDE log file. Feature logging enables other



ded.

itten

applications or utilities to perform subsequent operation on newly loaded features.


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 doesn’t exist then it is created, otherwise the existing log file is exten

Example:

The statement below instructs the SDE writer to write the IDs of all features wrto the log file written.log

SDE_LOGFILE written.log


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.



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.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)



his

s are

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 layer’s spatial index. Tis specified in system units as described in the SDE documentation.

Assuming the number of system units to logical units is 100 and the logical unitin meters, the following example defines a grid size of 200 meters.

SDE_GRID{0} 20000

TIP: Initially don’t 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.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 User’s 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.



a

rent

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. Ifnew geometric entity type is to be added to an existing layer, it must be done using the SDEAdministration Utility supplied by ESRI.For the FME to operate correctly, the SDE_GEOMETRY list must be consistent with the curstate of the associated layer.



DE.

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 obeythe following rules:

• Attribute Names must be in uppercase.• Attribute Names must obey all length and character restrictions of the S

• 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. Supportfor generic binary objects is planned. When the SDE is on the Oracle DBMS, asingle blob is permitted for each SDE feature type.

b. The current FME implementation doesn’t support the date type. Support for thisis planned. Currently, all dates are stored by the FME as integers in the formYYYYMMDD. This has less accuracy than the SDE date but is sufficientlyaccurate 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]

bloba SE_BLOB void *

dateb SE_DATE struct tm

varchar2c SE_STRING char *



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 CadastralMACRO 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




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



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.logWRITER_TYPE SDEREADER_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



# Stuff the SDE needs to know about.SDE_DATASET testdsetSDE_SERVER tuvokSDE_USERID dcmSDE_PASSWORD testSDE_TRANSACTION 0SDE_LOGFILE mergtest# A few macros to simplify the rest of the tables.MACRO BaseName MIFTestMACRO BaseLayer 1050

#---------------------------------------------------------------# Color macros -- nice names for the 24 bit integers which are 8 bits of RGB MACRO red 16711680MACRO yellow 16776960MACRO green 65280MACRO blue 255MACRO black 0MACRO magenta 16711935MACRO cyan 65535MACRO grey 12632256 MACRO purple 8388736MACRO white 16777215

#---------------------------------------------------------------# Pen pattern macros -- give names to some common line typesMACRO forwardArrow 59MACRO railLine 69MACRO thickRoad 74MACRO thinRoad 77 MACRO solidPen 2MACRO dotted 3MACRO dashed 5 MACRO wideDashed 7 MACRO widestDashed 8

#---------------------------------------------------------------# Pen thickness macros -- give names to some thicknessesMACRO thick 1MACRO thin 0

#---------------------------------------------------------------# Symbol macros -- give names to some symbolsMACRO solidStar 35MACRO solidCircle 34MACRO solidSquare 32MACRO solidDiamond 33MACRO clearStar 41MACRO clearCircle 40MACRO clearSquare 38MACRO clearDiamond 39MACRO plus 49MACRO asterisk 51MACRO tower 63MACRO building 60



MACRO plane 52MACRO dock 58MACRO monument 66MACRO landmark 67MACRO ex 50# 10 meter symbolsMACRO symbolSize 10

#---------------------------------------------------------------# Brush patternsMACRO smallCheckers 47MACRO bigGravel 48MACRO speckles 49MACRO rightDiag 32MACRO leftDiag 37MACRO solid 2MACRO clear 1MACRO darkMesh 45MACRO heavy 15MACRO horizontal 23MACRO vertical 28# The file used for inputMIF_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 \



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 SDEWRITER_TYPE SDE

READER_KEYWORD SDE_INPUTWRITER_KEYWORD SDE_OUTPUT

# A few macros to simplify the rest of the tables.MACRO OutputBaseName GeneralizedMACRO InputBaseName TownShipMACRO BaseLayer 4000

## First the global stuff.# # This section specifies the SDE global information

Both reader and writer types are the same!

SDE_DATASET testdsetSDE_IDs Township::$(InputBaseName)SDE_SERVER tuvok



SDE_USERID dcmSDE_PASSWORD xSDE_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

o — is is r

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 dthen allow the background to appear through the transparent pixels. Thoften used to create attractive world wide web displays, since most webbrowsers understand the transparent color directive. The FME GIF write


GIF IMAGE WRITER Safe Software Inc.

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.


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.


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


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 data’s 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



und sted.

ghest ts be

e. units either e ption

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 backgroimage’s colors — it assigns a color value as close as possible to the one reque

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 (hiintensity), and if they are not specified, then 0 is assumed. The color componenspecified in any order.

The mapping file fragment below defines two GIF colors:

GIF_DEF white GIF_RED 255 GIF_GREEN 255 GIF_BLUE 255GIF_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 sizHowever, it ensures that all pixels remain square in terms of the original groundof the features. This results in a blank band of background being present acrossthe bottom or the right-hand side of the produced image if the aspect ratio of thimage did not match the aspect ratio of the input source data. In the future, an oto clip off this blank band will be introduced in to the software.



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.



n the

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.


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 feature’s 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 i



re’s ault, is

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 featuattributes. The color for the line is taken from the feature’s feature type. By defif none of the attributes listed below are specified, a single pixel-width solid linedrawn.


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 nameOptional: 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 fileOptional: Yes.


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 > 1Optional: Yes



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 fileOptional: 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 > 0Optional: 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 > 0Optional: Yes.


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 point’s location. This attribute must not be present if the gif_symbol_image is set.Range: Integer > 1Optional: Yes




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 fileOptional: 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: 1Optional: 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: 1Optional: Yes (only allowed when

gif_symbol_image is set)


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.




tures

18.5 Example

The example below shows an FME mapping file used to render the “Road” feain a SAIF dataset into a GIF.

# -----------------------------------------------------------------------# Set up for SAIF to GIF translationREADER_TYPE SAIFWRITER_TYPE GIF

# -----------------------------------------------------------------------# Define the input and output filesSAIF_DATASET h:/saifdata/92c090/92c090.zipGIF_DATASET c:/tmp/roads.gif # -----------------------------------------------------------------------# Only extract the roads from the SAIF fileSAIF_IDs Roads # -----------------------------------------------------------------------# Keep a log of the activityLOG_FILENAME c:/tmp/gif.log # -----------------------------------------------------------------------# Define some GIF colorsGIF_DEF white GIF_RED 255 GIF_BLUE 255 GIF_GREEN 255GIF_DEF green GIF_RED 0 GIF_BLUE 0 GIF_GREEN 255GIF_DEF black GIF_RED 0 GIF_BLUE 0 GIF_GREEN 0 # -----------------------------------------------------------------------# Set the background color of the GIFGIF_BACKGROUND_COLOR white # -----------------------------------------------------------------------# Make a square GIF, 400 pixels by 400 pixelsGIF_WIDTH 400GIF_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 roughGIF black gif_type gif_line gif_dash_on 2 gif_dash_off 2 gif_brush_width 4 # -----------------------------------------------------------------------# For loose roads, we’ll 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_largegif_font_giant




SAIF Road::TRIM surfaceType loose numberOfLanes %numLanesGIF black gif_type gif_line gif_brush_width %numLanes # -----------------------------------------------------------------------# For paved roads, we’ll draw a dashed green line whose width, (and# dash interval) will be the number of lanes SAIF Road::TRIM surfaceType paved numberOfLanes %numLanesGIF green gif_type gif_line gif_brush_width %numLanes \ gif_dash_on %numLanes \ gif_dash_off %numLanes




19

.

ures

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 featcan 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.

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,12Brush 3,2,10

Pen 1,1,12Brush 4,3,9

Pen 2,1,13Brush 3,2,10

DEPTH LAKE_NAME

10

15

25

Smokey Lake

Beaver Hill Lake

Swan Lake


Safe Software Inc. MAPINFO DATA INTERCHANGE FORMAT READER/WRITER


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.


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>]+


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 file’s 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



no

s

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 file’s attributes gets logged to the log file. There arerestrictions 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 filemay 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 \


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.


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.



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:



The example below selects only the roads MIF file for input during a translation:

MIF_IDs roads


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.


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.


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.



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 3rd party add-ons to MapInfo rotate symbolsbased on a user-defined rotation attribute.


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


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: 0…2^24 - 1Default: 0 (black)

mif_symbol_shape The number of the symbol. See the MapInfo Reference Manual for a list of the available symbols.Range: 31...67Default: 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 > 0Default: 10



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.


mif_symbol_color The color of the symbol calculated according to the formula:(red*65536) + (green*256) + blue

Range: 0…2^24 - 1Default: 0 (black)

mif_symbol_shape The number of the shape within the TrueType font to be used as the symbol.Range: IntegerDefault: No default

mif_symbol_size The point size of the symbol.Range: IntegerDefault: 12

mif_symbol_font The name of the TrueType font to be used for the symbol.Range: StringDefault: No default

mif_symbol_angle The rotation angle for the symbol, measured in degrees counter-clockwise from horizontal.Range: -360.0..360.0Default: 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



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 line2. 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.


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: 0…2^24 - 1Default: 0 (black)

mif_symbol_file_name The name of the bitmap file found in the MapInfo CustSymb directory.Range: StringDefault: No default

mif_symbol_size The point size of the symbol.Range: IntegerDefault: 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



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.


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: 0…2^24 - 1Default: 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: 1…77Default: 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..7Default: 0

mif_smooth Controls whether or not the polyline will be smoothed when rendered.Range: true|falseDefault: false


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: 1…71Default: 2 (solid)



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: 0…2^24 - 1Default: 0 (black)

mif_brush_background The background color used when the region is filled. Range: 0…2^24 - 1Default: 0 (black)

mif_pen_color The color of the boundary of the region. Range: 0…2^24 - 1Default: 0 (black)

mif_pen_pattern The pattern used to draw the region’s boundary. See the MapInfo Reference Manual for a list of the available patterns.Range: 1…77Default: 2

mif_pen_width The width of the line rendered for the region’s boundary. This is measured as a thickness in pixels. 0 defines the thinnest line possible.Range: 0..7Default: 0


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: 0…2^24 - 1Default: 255 (blue)




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: 0…2^24 - 1Default: 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 fontDefault: 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: 0…7Default: 0 (regular text)

mif_text_height The height of the text in ground units. Range: Any real number >= 0Default: 10

mif_text_justification The justification of the text.Range: left|center|rightDefault: 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.0Default: 1.0

mif_text_string The text to be displayed.Range: Any character stringDefault: No default

mif_text_width The width of each text character in ground units. Range: Any real number >= 0Default: 10




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


mif_primary_axis The length of the semi-major axis in ground units.Range: Any real number > 0Default: No default

mif_secondary_axis The length of the semi-minor axis in ground units.Range: Any real number > 0Default: 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

PrimaryAxis

SecondaryAxis

Rotation = 0

rotation



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.


mif_primary_axis The length of the semi-major axis in ground units.Range: Any real number > 0Default: No default

mif_secondary_axis The length of the semi-minor axis in ground units.Range: Any real number > 0Default: 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

SecondaryAxis

Rotation = 90

StartAngle= 45

SweepAngle= 135

PrimaryAxis

rotation



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.


mif_rounding Contains the diameter in ground unit, of the circle used to produce the rounded corners.Range: Any real number > 0Default: No default

Rounding

Diameter



# ----------------------------------------------------------# 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 createdMIF_DEF roads \ numberOfLanes smallint \ roadType char(5) \ underConstruction logical \ divided logical \ travelDirection char(6) # ----------------------------------------------------------# Now define the location of the SAIF file# to be readSAIF_DATASET /usr/data/saif/92i080.zip# ----------------------------------------------------------# Color macros -- nice names for the 24 bit integers # which are 8 bits of RGBMACRO red 16711680MACRO yellow 16776960MACRO green 65280MACRO blue 255MACRO black 0MACRO magenta 16711935MACRO cyan 65535MACRO grey 12632256MACRO purple 8388736MACRO white 16777215 # ----------------------------------------------------------# Pen pattern macros -- give names to some common line typesMACRO forwardArrow 59MACRO railLine 69MACRO thickRoad 74MACRO thinRoad 77MACRO solidPen 2MACRO dotted 3MACRO dashed 5MACRO wideDashed 7MACRO widestDashed 8 # ----------------------------------------------------------# Pen thickness macros -- give names to some thicknessesMACRO thick 1MACRO thin 0

# ----------------------------------------------------------# Symbol macros -- give names to some symbolsMACRO solidStar 35MACRO solidCircle 34MACRO solidSquare 32MACRO solidDiamond 33

TIP: Using macros for the MIF colors, symbols, linestyles, and fill patterns makes mapping file maintenance and authoring much simpler.



MACRO clearStar 41MACRO clearCircle 40MACRO clearSquare 38MACRO clearDiamond 39MACRO plus 49MACRO asterisk 51MACRO tower 63MACRO building 60MACRO plane 52MACRO dock 58MACRO monument 66MACRO landmark 67MACRO ex 50# ----------------------------------------------------------# Brush patternsMACRO smallCheckers 47MACRO bigGravel 48MACRO speckles 49MACRO rightDiag 32MACRO leftDiag 37MACRO solid 2MACRO clear 1MACRO darkMesh 45MACRO heavy 15MACRO horizontal 23MACRO vertical 28# ----------------------------------------------------------# Now define transfer specificationsSAIF 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
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.

the

pInfo

nd

f type of

user. eated.

f two

files

These extensions are added to the basename of the specified Mapinfo file. Throughout the remainder of this section, references to “file” are references to 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 Maformat also stores features with no geometry. Features having no geometry arereferred to as having a geometry of none.

Each geometric entity present in MapInfo has display properties, such as pen abrush 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 ogeometry however, the associated attributes must have the same number and fields for each entity in the file.

The number and type of attributes associated with each entity is specified by theThere must be at least one attribute field defined before a MapInfo file can be cr

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 odisjoint 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 relatedin 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 MapInfo’s 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


Safe Software Inc. MAPINFO NATIVE FORMAT READER/WRITER


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.


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.


DATASET Contains the directory name of the input MapInfo files. Required

Geometry Info Associated Attributes

Pen 1,1,12Brush 3,2,10

Pen 1,1,12Brush 4,3,9

Pen 2,1,13Brush 3,2,10

DEPTH LAKE_NAME

10

15

25

Smokey Lake

Beaver Hill Lake

Swan Lake



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 file’s 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


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.




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:



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.





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.


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.


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.


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



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 3rd party add-ons to MapInfo will rotate symbolsbased on a user-defined rotation attribute.


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: 0…2^24 - 1Default: 0 (black)

mapinfo_symbol_shape The number of the symbol. See the MapInfo Reference Manual for a list of the available symbols.Range: 31...67Default: 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 > 0Default: 10


mapinfo_symbol_color The color of the symbol calculated according to the formula:(red*65536) + (green*256) + blue

Range: 0…2^24 - 1Default: 0 (black)



style

nfo

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, andmay be specified.

The table below lists the special FME attribute names used to control the MapIcustom point settings:

mapinfo_symbol_shape The number of the shape within the TrueType font to us as the symbol.Range: IntegerDefault: No default

mapinfo_symbol_size The point size of the symbol.Range: IntegerDefault: 12

mapinfo_symbol_font The name of the TrueType font to be used for the symbol.Range: StringDefault: No default

mapinfo_symbol_angle The rotation angle for the symbol, measured in degrees counterclockwise from horizontal.Range: -360.0..360.0Default: 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


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: 0…2^24 - 1Default: 0 (black)

mapinfo_symbol_file_name The name of the bitmap file found in the MapInfo CustSymb directory.Range: StringDefault: No default




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 line2, 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: IntegerDefault: 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




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.


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: 0…2^24 - 1Default: 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: 1…77Default: 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..7Default: 0

mapinfo_smooth Controls whether or not the polyline will be smoothed when rendered.Range: true|falseDefault: false


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: 1…71Default: 2 (solid)



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: 0…2^24 - 1Default: 0 (black)

mapinfo_brush_background

The background color used when the region is filled. Range: 0…2^24 - 1Default: 0 (black)

mapinfo_pen_color The color of the boundary of the region. Range: 0…2^24 - 1Default: 0 (black)

mapinfo_pen_pattern The pattern used to draw the region’s boundary. See the MapInfo Reference Manual for a list of the available patterns.Range: 1…77Default: 2

mapinfo_pen_width The width of the line rendered for the region’s boundary. This is measured as a thickness in pixels. 0 defines the thinnest line possible.Range: 0..7Default: 0


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: 0…2^24 - 1Default: 255 (blue)




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: 0…2^24 - 1Default: 0 (black)

mapinfo_text_fontname The name of the font used to draw the text. Thefont named must be available on the destination computer system.Range: Any valid system fontDefault: Helve

mapinfo_text_height The height of the text in ground units. Range: Any real number >= 0Default: 10

mapinfo_text_justification The justification of the text.Range: left|center|rightDefault: left

mapinfo_text_spacing The spacing between lines of multiline text. The measure is expressed as a multiple of thetext height.Range: 1.0|1.5|2.0Default: 1.0

mapinfo_text_linetype The spacing between lines of multiline text. The measure is expressed as a multiple of thetext height.Range: 1.0|1.5|2.0Default: 1.0

mapinfo_text_fontstyle_bold Indicates if the text is bold or not.Range: true | falseDefault: false

mapinfo_text_fontstyle_italic Indicates if the text is in italicsRange: true | falseDefault: false

mapinfo_text_fontstyle_underline Indicates if the text is underlined.Range: true | falseDefault: false

mapinfo_text_fontstyle_strikeout Indicates if the text has a line through the middle of it.Range: true | falseDefault: false

mapinfo_text_fontstyle_outline Indicates if the text is outlinedRange: true | falseDefault: false




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 | falseDefault: false

mapinfo_text_fontstyle_inverse Indicates if the text is shown in inverse.Range: true | falseDefault: false

mapinfo_text_fontstyle_blink Indicates if the text is blinking.Range: true | falseDefault: false

mapinfo_text_fontstyle_opaque Indicates if the text is opaque.Range: true | falseDefault: false

mapinfo_text_string The text to be displayed.Range: Any character stringDefault: No default

mapinfo_text_width The width of each text character in ground units. Range: Any real number >= 0Default: 10


rotation

PrimaryAxis

SecondaryAxis

Rotation = 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.


mapinfo_primary_axis The length of the semi-major axis in ground units.Range: Any real number > 0Default: No default

mapinfo_secondary_axis The length of the semi-minor axis in ground units.Range: Any real number > 0Default: 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

SecondaryAxis

Rotation = 90

StartAngle= 45

SweepAngle= 135

PrimaryAxis

rotation



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


mapinfo_primary_axis The length of the semi-major axis in ground units.Range: Any real number > 0Default: No default

mapinfo_secondary_axis The length of the semi-minor axis in ground units.Range: Any real number > 0Default: 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.0Default: 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 createdMAPINFO_DEF roads \ numberOfLanes smallint \ roadType char(5) \ underConstruction logical \ divided logical \ travelDirection char(6) # ----------------------------------------------------------# Now define the location of the SAIF file# to be readSAIF_DATASET /usr/data/saif/92i080.zip


mapinfo_rounding_width Contains the width, in ground units, of the ellipse used to produce the rounded corners.Range: Any real number > 0Default: No default

mapinfo_rounding_height Contains the height, in ground units, of the ellipse used to produce the rounded corners.Range: Any real number > 0Default: value of mapinfo_rounding_width

Rounding

RoundingHeight

Width



# ----------------------------------------------------------# Color macros -- nice names for the 24 bit integers # which are 8 bits of RGBMACRO red 16711680MACRO yellow 16776960MACRO green 65280MACRO blue 255MACRO black 0MACRO magenta 16711935MACRO cyan 65535MACRO grey 12632256MACRO purple 8388736MACRO white 16777215 # ----------------------------------------------------------# Pen pattern macros -- give names to some common line typesMACRO forwardArrow 59MACRO railLine 69MACRO thickRoad 74MACRO thinRoad 77MACRO solidPen 2MACRO dotted 3MACRO dashed 5MACRO wideDashed 7MACRO widestDashed 8

# ----------------------------------------------------------# Pen thickness macros -- give names to some thicknessesMACRO thick 1MACRO thin 0

# ----------------------------------------------------------# Symbol macros -- give names to some symbolsMACRO solidStar 35MACRO solidCircle 34MACRO solidSquare 32MACRO solidDiamond 33MACRO clearStar 41MACRO clearCircle 40MACRO clearSquare 38MACRO clearDiamond 39MACRO plus 49MACRO asterisk 51MACRO tower 63MACRO building 60MACRO plane 52MACRO dock 58MACRO monument 66MACRO landmark 67MACRO ex 50# ----------------------------------------------------------

NOTE:Using macros for the MAPINFO colors, symbols, linestyles, and fill patterns makes mapping file maintenance and authoring much simpler.



# Brush patternsMACRO smallCheckers 47MACRO bigGravel 48MACRO speckles 49MACRO rightDiag 32MACRO leftDiag 37MACRO solid 2MACRO clear 1MACRO darkMesh 45MACRO heavy 15MACRO horizontal 23MACRO 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

der FME.

re

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 ESRI’s Spatial Database Engine (SDE).

21.1 Overview

The Multi-Reader is completely configured in the mapping file. Each reait uses is identified and configured. At run time, the Multi-Reader cyclesthrough each reader it is given, and sends features on to the rest of the 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. Figu21-1 illustrates this concept.


MULTI-READER Safe Software Inc.

Figure 21-1 Multi-Reader Process

21.2 Keywords

The Multi-Reader processes several keywords in the mapping file, as shown here.


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.


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

outputdataset

input dataset

1

input dataset

2

input dataset

N


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 reader’s 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 datasetSAIF{0}_IDs Roads # Now do the same thing for the second SAIF dataset# to be read.MULTI_READER_TYPE{1} SAIFMULTI_READER_KEYWORD{1} SAIF{1} SAIF{1}_DATASET c:\saifdata\92c090.zipSAIF{1}_IDs Roads

# -----------------------------------------------# Now define the writerWRITER_TYPE SHAPE # Set the destination directory for the Shape fileSHAPE_DATASET roadset

# And set up the definition of the output Shape fileSHAPE_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.

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 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.


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 doesn’t 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.


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


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.


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


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.


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.


phocus_object_state The state of the object. Valid values are:0 = non-existent1 = deleted before timemark2 = deleted after timemark3 = new before timemark4 = new after timemark5 = edited before timemark6 = 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.



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 = point3 = line4 = area5 = 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-existent1 = deleted before timemark2 = deleted after timemark3 = new before timemark4 = new after timemark5 = edited before timemark6 = edited after timemark

phocus_subitem_type The subitem type. Valid values are:1 = area2 = cut-out3 = upper edge4 = lower edge5 = text

phocus_subitem_number Unique number which identifies the subitem.




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.


22.4.3 Areas

phocus_type: phocus_area

PHOCUS area features represent polygonal features and may be either 2D or 3D.


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.


phocus_justification The justification code for the text.Range: 0..23

0 is Left Margin/Very Top1 is Left Margin/Top2 is Left Margin/Cap3 is Left Margin/Center4 is Left Margin/Base5 is Left Margin/Bottom6 is Left/Very Top7 is Left/Top8 is Left/Cap9 is Left/Center10 is Left/Base11 is Left/Bottom



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 don’t 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 Top13 is Center/Top14 is Center/Cap15 is Center/Center16 is Center/Base17 is Center/Bottom18 is Right/Very Top19 is Right/Top20 is Right/Cap21 is Right/Center22 is Right/Base23 is Right/Bottom

phocus_text_string The text to be displayed.Range: Any character stringDefault:� No default




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




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 @Relatecommand 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.

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.


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.


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.


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


Safe Software Inc. RELATIONAL TABLE READER/WRITER

low

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 it’s 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 bedescribes 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 record’s logical type.

CSV Comma Separated Value (CSV) files are ASCII files with the record fields separated by commas. Each line in a CSVfile corresponds to one record. The default separator, a comma, can be overridden on the file’s definition line.

DBF DBase Format (DBF) files are formatted according to the DBase specification.



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


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.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.


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.



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.


<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


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.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.


[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.





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.


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.


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 TABLEWRITER_TYPE TABLE

WRITER_KEYWORD T_OUT

TABLE_DATASET .

T_OUT_DATASET .



# -----------------------------------------------------------# 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




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 datamodel which describes the data.


SPATIAL ARCHIVE AND INTERCHANGE FORMAT (SAIF) READER/WRITER Safe Software Inc.

ce both ot

or any ribe

er

ssable ith

t

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 referencomponent objects. For example, if the geometry of a linear feature definesa river bank and a lot boundary, then SAIF enables both the river and the lboundary to reference the same linear feature.

• Direct Support for Multimedia Datatypes: SAIF enables multimedia datatypes such as JPEG, Graphic Interchange Format (GIF), Sound Files, other type of file to be stored directly within a dataset. Attributes which descthe embedded information are also stored in the file.

• Object Linking: SAIF enables objects within a SAIF dataset to refer to othobjects 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 addreobject is identified with a unique identifier stored in the SAIF directory, along wthe object’s class information and the object’s location within the dataset.

Unlike other file-based data storage formats, SAIF uses the directory to supporrandom retrieval of data. For example, if a SAIF dataset contains Roads,

SAIF Directory

SAIF Schema(CSN)

SAIFObject

Definitions(OSN)

SAIF Dataset Structure


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 Programmer’s Reference Manual Release 1.1.




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.


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.


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



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


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.


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.


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



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




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



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



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.csnSAIF_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



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


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 andthe attribute path syntax used by SAIF.



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 doesn’t 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.csnSAIF_CSN trim32.csn

SAIF_XCOORD_TYPE STK_INT32SAIF_YCOORD_TYPE STK_INT32SAIF_ZCOORD_TYPE STK_INT32SAIF_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.#



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_pointSAIF 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 1igds_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.



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_lineSAIF 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 40011SAIF Island::TRIM position.geometry.Class Point




25

cified

table

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.


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 spelist of IDs and, if it was, reads all features for that feature class.


The following table lists the keywords processed by the VPF reader. The 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.

ex — VPF

the

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 complof the feature class, and the names and types of all attributes. The syntax of a 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


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


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.


char(<width>) All text fields are handled as variable-width strings; the <width> parameter defines a maximum length of the field’s 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.



g r

t

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, providinevery element of the string up to that point is given. (Foexample, a value of “1996” represents the year 1996; “19960812” represents August 12, 1996; “19960812080000.” represents 8:00:00 AM on August12, 1996, in the local time zone; and “19960812150000.Z” represents 5:00:00 PM on Augus12, 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 UniversalTime, or “[+-]hhmm” to represent a positive or negativetime zone differential from Greenwich.




re can

that

<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.


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 featucontain 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 inquestion 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. Notethese 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



ee-

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 234RCLASS MR001component{0}.vpf_type vpf_linecomponent{1}.vpf_type vpf_textcomponent{1}.vpf_text_string “23rd Street”component{1}.rotation 14.012component{1}.vpf_text_font 12component{1}.vpf_text_color 3component{1}.vpf_text_style 5component{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 thrdimensional (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



ing to

and

ibute, above. ately

• Any integer or text attribute in a VPF table may be associated with a valuedescriptor table, giving a more verbose textual description of the attribute.

• Feature classes in VPF are defined by joining various tables together, leada 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,are defined on FME features as <attrName>{<n>}.x, <attrName>{<n>}.y, and <attrName>{<n>}.z, where <attrName> is the name of the attribute thatis 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}.xCOORDS{0}.yCOORDS{0}.zCOORDS{1}.xCOORDS{1}.yCOORDS{1}.zCOORDS{2}.xCOORDS{2}.yCOORDS{2}.zCOORDS{3}.xCOORDS{3}.yCOORDS{3}.zCOORDS{4}.xCOORDS{4}.yCOORDS{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 attrits value is read for each feature, and defined on the FME feature as described If you had a fixed-length coordinate array, you could define each attribute separin the VPF_DEF line:



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.



n,

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 columOCCUPANT.RAT_ID, that links into the OCCUPANT.RAT table.

The schema for the street feature class is something like:

Class name: STREETLGeometry type: vpf_lineFeature 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



font

rder,

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: STREETLGeometry: Aggregate containing one lineAttributes on feature:

ID 12STRADDR.RAT_ID 5EDG_ID 19STRCODE 5STRCODEdesc “29th Avenue”STRADDR_RAT{0}.ID 5STRADDR_RAT{0}.ADDRESS 1234STRADDR_RAT{0}.HYDRANT “Yes”STRADDR_RAT{0}.OCCUPANT 23STRADDR_RAT{0}.OCCUPANT{0}.ID 1STRADDR_RAT{0}.OCCUPANT{0}.FAM_NAME “Smith”STRADDR_RAT{0}.OCCUPANT{0}.NUM_RES 4STRADDR_RAT{0}.OCCUPANT{0}.CLUST_ID 23STRADDR_RAT{0}.OCCUPANT{1}.ID 2STRADDR_RAT{0}.OCCUPANT{1}.FAM_NAME “Jones”STRADDR_RAT{0}.OCCUPANT{1}.NUM_RES 2STRADDR_RAT{0}.OCCUPANT{1}.CLUST_ID 23STRADDR_RAT{0}.ID 6STRADDR_RAT{0}.ADDRESS 2345STRADDR_RAT{0}.HYDRANT “No”STRADDR_RAT{0}.OCCUPANT 14STRADDR_RAT{1}.OCCUPANT{0}.ID 3STRADDR_RAT{1}.OCCUPANT{0}.FAM_NAME “Murray”STRADDR_RAT{1}.OCCUPANT{0}.NUM_RES 2STRADDR_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— 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 oand the first value found is taken as the value.



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




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.


<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

A-1FME Reference Manual — Version 2.0

@Abort FME FUNCTION REFERENCE

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-2 FME Reference Manual — Version 2.0

FME FUNCTION REFERENCE @AddVertices

A.2 @AddVertices

@AddVertices((x|y|xy),<interval>)


ARGUMENTS:

A.2.1 Configuration


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>.


<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 feature’s ground units.

No


@AddVertices FME FUNCTION REFERENCE

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)


FME FUNCTION REFERENCE @Affine

of in the

s but a

A.3 @Affine

@Affine(<A>,<B>,<C>,<D>,<E>,<F>)


ARGUMENTS:

A.3.1 Configuration


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 formscaling simply scales distances in the x direction by one amount and distancesy direction by another amount.

A reflection is a transformation that preserves lengths and magnitudes of anglechanges their sign. The effect is equivalent to viewing the original geometry in mirror, or through a flipped over sheet of transparent paper.


<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 + Cy’ = Dx + Ey + F

No


@Affine FME FUNCTION REFERENCE

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.


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)


FME FUNCTION REFERENCE @Arc

A.4 @Arc

@Arc(<semi-primary axis>,<semi-secondary axis> / [, <numberOfEdges>, <rotation>, <startAngle>, / <sweepAngle>, <centerX>, <centerY>])


ARGUMENTS:


<semi-primaryaxis>

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

Figure A-1 Sample Arc

A.4.1 Configuration


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.

SecondaryAxis

Rotation = 90

StartAngle= 45

SweepAngle= 135

PrimaryAxis


FME FUNCTION REFERENCE @Arc


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.5 @Area

@Area( [<multiplier>] )

FUNCTION TYPE: ATTRIBUTE

ARGUMENTS:

A.5.1 Configuration


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.


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


<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


FME FUNCTION REFERENCE @Bounds

A.6 @Bounds

@Bounds(<xMinAttr>,<xMaxAttr>,<yMinAttr>,<yMaxAttr> /[,<zMinAttr>,<zMaxAttr>]>


ARGUMENTS:

A.6.1 Configuration


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.


<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.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


FME FUNCTION REFERENCE @Circularity

A.7 @Circularity

@Circularity()


ARGUMENTS: NONE

A.7.1 Configuration


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)


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 lakesMIF lakes circularity @Circularity()


@Close FME FUNCTION REFERENCE

A.8 @Close

@Close()


ARGUMENTS: NONE

A.8.1 Configuration


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 caution—in 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.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


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.9 @Concatenate

@Concatenate([<string>]+)


ARGUMENTS:

A.9.1 Configuration


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.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


<string> any string All strings passed in will be joined together to form a single, composite string, which is returned.

No


FME FUNCTION REFERENCE @ConvertBase

D ported.

. An igits

A.10 @ConvertBase

@ConvertBase(<value>,<originalBase>,<destBase> \[,<outputWidth>])


ARGUMENTS:

A.10.1 Configuration


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 UNSIGNEinteger numbers are supported. Any base from base 2 (binary) to base 36 is supDigits are chosen from the set:

0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ

Any lower case digits are converted to upper case by the function automaticallyoptional output width may also be specified. If the converted value has fewer dthan 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 set0123456789 ABCDEFGHIJKLMNOPQRSTUVWXYZ


<value> stringa 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

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 stringsFACTORY_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# equivalentFACTORY_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.


FME FUNCTION REFERENCE @ConvertToArc

not us, t that is

l be n 3

A.11 @ConvertToArc

@ConvertToArc (<primaryRadiusAttrName>, \<secondaryRadiusAttrName>, \<startAngleAttrName>, \<sweepAngleAttrName>)


ARGUMENTS:



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,the geometrically middle point). It sets attributes on the feature to hold the radistart, and sweep angle, and sets the geometry of the feature to be a single pointhe 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 wilguaranteed to pass through all of them. If it is called on a feature with more tha

a. In the current version of the FME, only circular arcs are generated and therefore theprimary and secondary radii will always be the same.


<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

, this tion for

s as

ly arc

into

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 directionfunction will convert a point feature into a linestring which approximates an arcdefined by the values of the parameter names passed to it. See the documenta@Arc, Section A.2, for details.

A.11.4 Example 1

Given a feature containing these points:

2,11,20,

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 30sweepAng 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 featurearcs, even after they have been reprojected.

The below sampling factory provides the solution for such a case. It accepts onfeatures read in from an input design (IGDS) file.

As each feature enters the factory, it is first reprojected. This will turn the featurea 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

55


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

d from e

A.12 @ConvertToLine

@ConvertToLine(<tolerance>)


ARGUMENTS:



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.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 convertepolygons to lines. All other RoadAllowance features are untouched. Note the usof 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 \


<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


FME FUNCTION REFERENCE @ConvertToLine

OUTPUT PASSED FEATURE_TYPE RoadLine \@ConvertToLine(10) \

OUTPUT FAILED FEATURE_TYPE RoadAllowance


@ConvertToPoint FME FUNCTION REFERENCE

A.13 @ConvertToPoint

@ConvertToPoint()


ARGUMENTS: NONE.



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.


This function when combined with the TestFactory enables the FME to perform area generalization operations.


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


FME FUNCTION REFERENCE @Coordinate

A.14 @Coordinate

@Coordinate((x|y|z),<index>)


ARGUMENTS:


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


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.


<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 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


FME FUNCTION REFERENCE @CoordSys

e eated ame

may esult

ay be

ribute

A.15 @CoordSys

@CoordSys()


ARGUMENTS: NONE



A.15.2 Description

This function returns the name of the coordinate system in which this feature’scoordinates are measured. If it returns a blank, then it means that no coordinatsystem has been set for the feature data. If a coordinate system definition is crautomatically by the FME from parameters read from an input data source, its nwill begin with an _.

The FME may define coordinate systems automatically. It is possible that therebe two different names for exactly the same coordinate system definition. The rreturned by @CoordSys should not be used in a comparison with a hardcoded coordinate system name, since coordinate system names may be different but mstructurally equivalent.


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 attnamed coordSys.

SHAPE lake MIF lake coordSys @CoordSys()


@Count FME FUNCTION REFERENCE

A.16 @Count

@Count( [<domain>[,<startVal>[,<modulo>]]] )

FUNCTION TYPE: ATTRIBUTE OR FEATURE

ARGUMENTS:



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.


<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.


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.


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 it’s LINENUM attribute. At the end of therun, 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.17 @Dimension

@Dimension()


ARGUMENTS: NONE



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.4 Example

In the example below the feature dimension is stored within the attribute named dimension.

SHAPE lake MIF lake dimension @Dimension()


FME FUNCTION REFERENCE @Evaluate

A.18 @Evaluate

@Evaluate(<expression>)


ARGUMENTS:



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


<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

t .1,

eft as

will

for

e:

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 mosinstallations). For example, all of the following are valid floating-point numbers: 23., 6e4, 7.91e+16. If no numeric interpretation is possible, then an operand is la 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 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 formsoperands, 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 precedenc

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.



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

that

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” sothey will not look like integer values. For example,

@Evaluate(20.0/5.0)

UHWXUQV�´4.0µ��QRW�´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.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.19 @FeatureType

@FeatureType( [<newType>] )


ARGUMENTS:



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.


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.


<newType> string A new feature type for the feature. Yes


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 %styleIGDS * igds_type igds_line igds_color %color \ igds_style %style \ @FeatureType(%level)


@Force2D FME FUNCTION REFERENCE

A.20 @Force2D

@Force2D()


ARGUMENTS: NONE



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.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


FME FUNCTION REFERENCE @Generalize

ts.

s

e

A.21 @Generalize

@Generalize(Deveau,<tolerance>,<numWedges>,<angle>)@Generalize(Douglas,<tolerance>)


ARGUMENTS:



A.21.2 Description

The @Generalize function modifies a feature’s geometry by removing its poin

Two algorithms are available for the point thinning. The Douglas algorithm takeonly a <tolerance> parameter to the amount of point thinning performed. TheDouglas algorithm removes points from the original line, but does not adjust thlocation of the remaining points.


<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

ints

tuned u ing

ed

a

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 powhich 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 befor particular applications to produce aesthetically pleasing results. The Deveaalgorithm is fully described in the AutoCarto VII proceedings in the paper “Reducthe Number of Points in a Plane Curve Representation” by Terry J. Deveau.

The @Generalize functions logs statistics about the number of points it removto the logfile.


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 toShape 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)


FME FUNCTION REFERENCE @GeneratePoint

e then

ature.

re s and

hape aset.

A.22 @GeneratePoint

@GeneratePoint()


ARGUMENTS: NONE



A.22.2 Description

This function generates a point inside a polygon or donut polygon feature. The generated point is added to the feature’s in-memory representation. The featurbecomes 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 fe

This function can be used when translating data from model where polygons adirectly attached to a model where polygonal areas are implied by boundary linethe attribution for each area is attached to a point within that area.



A.22.4 Example

In the example below, polygonal data with attached attribution is read from a Sfile, but the attribution is to be attached to point features output to an IGDS datTo 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

II time, form

) PST,

A.23 @GOID

@GOID()@GOID(VERIFY,<goid>)


ARGUMENTS:



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 ASCString. The first 16 characters correspond to the position, the next 10 to thethe next 4 to the sequence number, and the final 2 to the checksum. This operates as an attribute function, in that it returns a string.

For example, when @GOID was called on a point feature at position (-127,49as measured in latitude and longitude on January 23, 1997 at 10:39:26 AMit returned the value:


<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)


FME FUNCTION REFERENCE @GOID

) out,

rt

ude the gned,

ost ght, de,

fined

from

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 digitsis valid. The verification is done by ensuring that checksum of the GOID iscorrect, according the specification below. 1 is returned if the GOID checks0 otherwise.

A.23.3 Inverse

This function has no inverse and does nothing if invoked on the source line of atransfer specification.

A.23.4 Formal Specification

The GOID is composed of four parts and are described below, with the first pa(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 latitand longitude values. They are first expressed as double-precision floats. Nextlatitude and longitude are each multiplied by 107. Each is then converted to a sifour-byte (32-bit) integer. Negative values are handled by two $s complement encoding. The interleaving proceeds, from left to right, beginning with the left-mbit of the latitude, and then the left-most bit of the longitude. Thus, from left to rithe odd-numbered bits of Part A of the GOID are from the binary form of the latituand 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 areapproximately 1.1 cm and better than 0.4 cm, respectively, for a given point deas:

(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 object’s geometric description. In the case of an area feature, the two points come



Time

of two e

; that it. he last tation n of

y and

cimal

shall er, ts n * s.

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 computer’s clock. The time is measured with respect to Universal Coordinated (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 objects at the same place being defined in the same hundredth of a second. Thsequence 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 119is, the first (i.e., left-most) hexadecimal digit becomes the 30th hexadecimal digThe 128 bits are then treated as 16 consecutive, one-byte unsigned integers. Tinteger is adjusted such that the sum of the 16 integers is 0, modulo 256. This roof the first hex digit minimizes the chance that a four, 32-bit integer representatiothe GOID could have the position of the integers altered or reversed in some waremain undetected.

A.23.5 Encoding

There are two representations of the GOID: as a character string of 32 hexadedigits, 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 proceed from left to right. (The left-most 8 characters define the first integetc. Also, the left-most character (in each group of 8 characters) represen167, the next represents m * 166, and so forth for the remaining character


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.



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”)


FME FUNCTION REFERENCE @KeepAttributes

A.24 @KeepAttributes

@KeepAttributes(<attrName>[,<attrName>]*)


ARGUMENTS:



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.


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) \


<attrName> String The name of the attribute which is to be remain in the feature.

No


@KeepAttributes FME FUNCTION REFERENCE

GROUP_BY mif_type mif_pen_width LIST_NAME dummyList{} OUTPUT POLYGON FEATURE_TYPE *


FME FUNCTION REFERENCE @Length

A.25 @Length

@Length( [<dimension> [, <multiplier>] ] )


ARGUMENTS:



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.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


<dimension> 2|3 Specifies whether the 3rd 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.26 @Log

@Log([<message>[,<maxCoords>]])


ARGUMENTS:



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.


<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


FME FUNCTION REFERENCE @Log

output

GDS

ed , the

he


The inverse is the same as the forward operation — in both cases, the feature isto the log file.

A.26.4 Example

In the below example, the feature will be logged both as a SAIF feature and an Ifeature:

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 loggbefore and after the generalization function is applied. When IGDS is the source@Generalize function does nothing and the feature is logged twice, looking tsame 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.27 @Lookup

@Lookup( <lut name>, <value> )


ARGUMENTS:


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.


<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


<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


FME FUNCTION REFERENCE @Lookup

e ure

ange utput 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.


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 feature’s parkType attribute. When a match is found, it sets th%pk transfer variable to the left-hand side lut value. For example, if a SAIF feathad 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 tagLookup parkTypeLut HP historicPark \ NE naturalEnvironmentPark \ NP nationalPark \ PA protectedArea

SHAPE parks pkType %pkSAIF 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 rof source values to pass through without causing the translation to abort. The odata can then be analyzed to see what source values were not handled by the


@Lookup FME FUNCTION REFERENCE

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 %codeMIF mifparcel ownership @Lookup(ownershipCodeLut,%code)


FME FUNCTION REFERENCE @NumCoords

etry.

A.28 @NumCoords

@NumCoords()


ARGUMENTS: NONE



A.28.2 Description

This function returns the number of coordinates which define the feature’s geom



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.29 @NumElements

@NumElements( [<listName>] )


ARGUMENTS:



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.4 Example

Given the below feature:


<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


stand{0}.species birch

stand{0}.age 30

stand{1}.species birch

stand{1}.age 30


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



@NumHoles FME FUNCTION REFERENCE

A.30 @NumHoles

@NumHoles()


ARGUMENTS: NONE



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


FME FUNCTION REFERENCE @Offset

A.31 @Offset

@Offset(<offset>)@Offset(<xOffset>, <yOffset>)@Offset(<xOffset>, <yOffset>, <zOffset>)


ARGUMENTS:



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.


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)


<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

owed

the ertices ise

kwise

st e with

A.32 @Orient

@Orient (<orientation>)


ARGUMENTS:



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 parameter—the orientation to set for the feature. The values allare: 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 asobserver traverses the boundary. For the outer boundary, this means that the vare in a clockwise direction, and for holes, their vertices are in a counterclockwdirection.

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 boundary’s vertices are in a counterclockwise order, and the holes have a clocordering.

When REVERSE is specified, the feature’s coordinates are flipped so that the fircoordinate becomes the last one, and vice-versa. This option is intended for usfeatures 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.


<orientation> RIGHT_HAND_RULE|LEFT_HAND_RULEREVERSE

This parameter controls what orientation the feature will have when the function has completed.

No


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

sing

ame, n is

A.33 @Relate

@Relate( <relationId>, (DestReadSrcWrite|DestWriteSrcRead) )


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 uthe 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 nand is independent of the actual physical structure of the table. The relatiodefined using the RELATION_DEF configuration option.


<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


FME FUNCTION REFERENCE @Relate

f the

ard

e the e ey

y

nal

ll be at 0.

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 oTRANSFER clause is the source of attribute values. Any attribute functions onthis side will be executed in the forward direction. The value transferred to thefeature 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 tablevalues. 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 forwexecution of the function.

• The JOIN clause works in the opposite way when a relate is executed in thforward direction. This is because the JOIN will look in the table for the valuesspecified by the feature. In this case, then, the right hand (feature) side of JOIN clause is the source of the key values. Any attribute functions on this sidwill be executed in the inverse direction. The resulting value is passed as the kvalue to the table side of the clause.

• The left (table) side of the JOIN clause is the destination of the key values. Anattribute 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 relatiotable. The TRANSFER clauses and feature functions of the relation will be executed for each row. Any attribute list field names on the feature side wiexpanded to include the row number in their {}. Rows are numbered starting



re)

ys

. The ted side ting n


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 (featuside 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 beexecuted in the forward direction, since functions on the destination side alwaexecuted 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 tableJOIN and TRANSFER clauses and feature functions of the relation will be execuin the inverse direction for each row. Any attribute list field names on the featurewill be expanded to include the row number in their {}. Rows are numbered starat 0. When no data for a row can be found in the feature, then the relate functioterminates.




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.


<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 table’s 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 TABLE_LOCATION <tableId> <pathname>

Relate TABLE_DEF <tableId> <tableType>\[<fieldName> <fieldType>]+

a. Any feature function can be called, including other @Relate functions. This allowsrelations to cascade across several tables.

<featFunc> any valida 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


<tableId> character string The logical name of the table whose location is being set. The table’s 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


<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 ASCIICAT: 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




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


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 DDWhen 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.




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


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.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


<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


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.




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 element’s 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) \



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,MACBLO1002,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



full

01

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 company’s 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 10and 1002, and the original forestTable CSV file contained:

1001,fir,MACBLO1002,spruce,CANFOR

and the original company DBF file contained:



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

M1

11



<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/forestDataMACRO MAPSHEETID 92b034

Relate TABLE_LOCATION polygon $(baseDir)/polygon.csvRelate TABLE_LOCATION history $(baseDir)/history.csvRelate TABLE_LOCATION layer $(baseDir)/layer.csvRelate TABLE_LOCATION result $(baseDir)/result.csv



# ---------------------------------------------------------------- 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 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.



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

mapsheetId

polygonId

layerNum

rank tree1Code

tree1Percent

tree2Code

tree2Percent

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 activityYear1

activityYear2

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



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_history{0}.saif_ actYear1 1990


saif_layerStuff{0}.saif_history{0}.saif_ activityCode HARVEST



saif_layerStuff{0}.saif_history{1}.saif_ activityCode GROOM






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_history{1}.saif_ activityCode GROOM

Coordinates: 602322,5930211,40

Feature Type: ForestStand::SAFE

Attribute Value


@Reproject FME FUNCTION REFERENCE

’s

A.34 @Reproject

@Reproject( <sourceCS>, <destCS> [,<xFieldName>, <yFieldName>] )


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 featuregeometry 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.


<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


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.


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_lineShape 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 %yShape lake insideX %x insideY %y \ @Reproject(UTM27-10, LL83) \ @Reproject(UTM27-10, LL83, insideX, insideY)


@Rotate2D FME FUNCTION REFERENCE

A.35 @Rotate2D

@Rotate2D(<degrees> [,<rotateX>, <rotateY>])


ARGUMENTS:



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.


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)


<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


FME FUNCTION REFERENCE @RoundOffCoords

A.36 @RoundOffCoords

@RoundOffCoords((x|y|z),<axis>)


ARGUMENTS:


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.


<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.36.3 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.3010299956639812MACRO MinusLog10_5 -0.69897000433601886

FACTORY_DEF SAIF SamplingFactory \INPUT FEATURE_TYPE * \

@RoundOffCoords(x, $(Log10_2) ) \@RoundOffCoords(y, $(MinusLog10_5) ) \@RoundOffCoords(z, 0)


FME FUNCTION REFERENCE @SAIFAngle

A.37 @SAIFAngle

@SAIFAngle( <angle> )


ARGUMENTS:



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.


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.


<angle> Real Number

Angle to convert from a counterclockwise angle oriented from the horizontal to an angle oriented clockwise from vertical (SAIF style).

No

ccwangle

SAIFangle


@SAIFAngle FME FUNCTION REFERENCE

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)


FME FUNCTION REFERENCE @Scale

A.38 @Scale

@Scale(<factor>)@Scale(<xFactor>, <yFactor>)@Scale(<xFactor>, <yFactor>, <zFactor>)


ARGUMENTS:



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.


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)


<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.39 @Split

@Split( <splitStr>, (<delimiter>|<formatSpec>), <attrName1>, <attrName2> [, <attrNameN>]* )


ARGUMENTS:



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)


<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


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.


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 feature’s JUST attribute. The @Split command on the SAIF line, which is the destination portion of the transfer


@Split FME FUNCTION REFERENCE

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 2SAIF 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.


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.40 @SupplyAttributes

@SupplyAttributes(<attrName>,<attrValue> [,<attrName>,<attrValue>]*)


ARGUMENTS:



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.


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)


<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


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.41 @Timestamp

@Timestamp( <formatString> )

FUNCTION TYPE: ATTRIBUTE ARGUMENTS:



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:


<formatString> string Specifies how the current time will be formatted when it is output.

No

Character Replacement

â The abbreviated weekday name according to the current locale.

Â 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).

Î 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.


FME FUNCTION REFERENCE @Timestamp

e

h the

For example,

@Timestamp("^Y^m^d")

will return “19960913”, if it was invoked on September 13, 1996. Similarly, on thsame day,

@Timestamp(“The date is: ^c”)

would return “The date is: Fri Sep 13 16:32:48 PDT 1996" (without the quotes).


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 througsystem:

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.

Û 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

ature

tract fer

A.42 @XValue

@XValue( [<x-value>] [, Reset ] )


ARGUMENTS:



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 feature’s geometry, either extending a line if the fewas 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. Thisvalue is then stored in the attribute.


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 exthe value of the first x coordinate in the feature and assign this value to the transvariable passed to it.


<x-value> real number The value of the x coordinate to store in the feature.

Yes


FME FUNCTION REFERENCE @XValue

te

curate.

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 ElementFactory’s OUTPUT ELEMENT line to set each output feature’s coordinates from its attribuvalues.

The SAIF attribute names in this example have been shortened and are not ac

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


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

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



textOrSymbol.Class TextFromMulti

x 5001

y 40001

z 101

text Hello

Coordinates: None



textOrSymbol.Class TextFromMulti

x 5001

y 40001

z 101

text Hello

Coordinates: 5001,40001,101


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:



textOrSymbol.Class TextLine

text Hello

Coordinates: 5001,40001



textOrSymbol.Class TextLine

x 5001

y 40001

text Hello

Coordinates: 5001,40001


@YValue FME FUNCTION REFERENCE

A.43 @YValue

@YValue( [<y-value>] )


ARGUMENTS:



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.


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.


<y-value> real number The value of the y coordinate to store in the passed in feature.

Yes


FME FUNCTION REFERENCE @ZValue

A.44 @ZValue

@ZValue( z-value )


ARGUMENTS:



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.


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 %heightSAIF Roads::TRIM @ZValue(%height)


<z-value> real number The value of the z coordinate stored in the feature.

No


@ZValue FME FUNCTION REFERENCE


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.‘

B-1FME Reference Manual — Version 2.0

AggregateFactory FACTORY REFERENCE

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 feature’s 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 isn’t 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-2 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


position.geometry.qualifier definite

position.geometry.value 20

Coordinates: (477553,5360181,20) (477554,5360182,20)



position.geometry.qualifier indefinite


Coordinates: (377553,4360181,20) (377554,4360182,20)

Feature Type: ContourAggregate




Coordinates: Line 1: (477553,5360181,20) (477554,5360182,20)Line 2: (377553,4360181,20) (377554,4360182,20)


ArcFactory FACTORY REFERENCE

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.


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.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> \


]*

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


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 SHAPEWRITER_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

# ------------------------------------------------------------# 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)


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

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()


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.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.


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.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.


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

ures:

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 feat

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


FACTORY REFERENCE DeaggregateFactory

r of list

same

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 feature’s attributes.

The optional LIST_NAME clause is used to associate attributes with each membethe aggregate. When the aggregate is broken up, any elements of the attributecorresponding to the geometry will be added to the feature that is output, in the 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, orfeatures 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.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




Coordinates: Line 1: (477553,5360181,20) (477554,5360182,20)Line 2: (377553,4360181,20) (377554,4360182,20)


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.





featNum 0

Coordinates: (477553,5360181,20) (477554,5360182,20)





featNum 1

Coordinates: (377553,4360181,20) (377554,4360182,20)


DonutFactory FACTORY REFERENCE

g to tory

.

the

nto a

in 1 . At

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 accordinthe OUTPUT LINE clause. Once all the input features have been collected, the facproduces 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 andpolygons 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 isingle hole.

Step 4: If points are also input into the factory, the DonutFactory then matches points to the polygon and donut polygons determinedabove. Points are matched to the polygons which enclose themmost 1 point will be matched to any polygon.


FACTORY REFERENCE DonutFactory

es

are

one

.

hin.

Step 5: Any polygons found to contain a point have the point’s attributand 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 matchedoutput 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 inpolygon, 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 featuresThe 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 wit

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 point’s attributes are merged with the polygon’s.

POINT All point features which weren’t found to be in any polygon.

POLYGON All polygon features which contained neither any holes nor an inside point.


DonutFactory FACTORY REFERENCE

nd.

und.

• 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 fouHowever, no internal points were found for these.

• POINT: These are the point features for which no enclosing polygon was fo

• 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


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.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


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> \


]*

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.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








Coordinates: (477553,5360181,20)


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



igds_text Hello

x 477556

y 5360183







Coordinates: no coordinates

Feature Type: 35

Attribute Value


igds_text World

x 477556

y 5359177









ListFactory FACTORY REFERENCE

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.


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 isn’t 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


TEXTSTRING Hello

TEXTGROUP 12

Coordinates: (477553,5360181,20)


ListFactory FACTORY REFERENCE

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


TEXTSTRING World

TEXTGROUP 12

Coordinates: (477553,5450181,20)

Feature Type: text_multi


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



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.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} SAIFMULTI_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: NoneExample: 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 AttributesExample: 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 AttributesExample: 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: NoneExample: 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


FACTORY REFERENCE MatchingFactory

SAIF{0}_DATASET c:\saifdata\original.zip

SAIF{0}_IDs RiverStreamsMULTI_READER_TYPE{1} SAIFMULTI_READER_KEYWORD{1} SAIF{1}SAIF{1}_DATASET c:\saifdata\updated.zipSAIF{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 %typeSHAPE 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 %typeSHAPE newRivers RIVERTYPE %type


MatchingFactory FACTORY REFERENCE

#-----------------------------------------------------------------# 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 %typeSHAPE deletedRivers RIVERTYPE %type


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.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 feature’s 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.


FACTORY REFERENCE PolygonFactory

B.14 PolygonFactory

B.14.1 Syntax

FACTORY_DEF <ReaderKeyword> PolygonFactory \[INPUT FEATURE_TYPE <feature Type> \


]* \[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.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.


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> \


]* 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.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.


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

he

ME

s the

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 don’t have any of the attributes identified by tREFERENCEE_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 Flogfile. The number of features output for each output tag value is reported.

The figure below illustrates the processing of the factory. The example illustrateprocessing 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.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

ReferenceFactory

REFERENCEE

REFERENCED

REFERENCEE

REFERENCED

COMPLETE


ReferenceFactory FACTORY REFERENCE

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.



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.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


FACTORY REFERENCE SDEQueryFactory

e. It ables

query iately

eries

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 ESRI’s Spatial Database Enginperforms an SDE spatial query for each feature which it retrieves. The factory enSDE queries to be performed as part of the FME processing stream. The SDEQueryFactory2 is driven by input features which contain the specifics of thequery to be performed. For example, a simple user interface could create suchfeatures. These query features could then be run through the FME either immedor 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 quto 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 avoidconsuming large amounts of system resources with erroneous searches.


SDEQueryFactory FACTORY REFERENCE

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 ESRI’s SDE installed and running and has purchased the FME modules for the SDE.

SDEQueryFactoryInput Feature

SDEDatabase

Result Features

QueryFeature

DownstreamFactory or

Writer Module

UpstreamFactory or

Reader Module

Query Result Features



B.18.5 Clauses

The following clauses are used to configure the SDEQueryFactory for a retrieval operation:


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



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.




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 doesn’t 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.




# ==============================================# SDEQueryFactory example.# ==============================================

# --------------------------------------------------------------# Global SDE information. MACRO SDE_DATASET_NAME sampleMACRO 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 ARCGENWRITER_TYPE SHAPE

# The arcgen dataset is the current directory. Could be specified # on the command line.ARCGEN_DATASET.

# ARCGEN definitionsARCGEN_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.



## 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 \



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 FME’s liberal interpretation of the# ARCGEN format specification.1008|SDE_CP_OR_LC|10538000,5595000545000,5600000ENDEND


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.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)


FACTORY REFERENCE TeeFactory

type f utput

e any

the does

ters.

s, and

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> \


]+ \

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 feature’sor otherwise alter the feature as it goes through. If the INPUT clause is not specifiedthen every feature is input into the factory. This factory is useful when copies ofeatures need to be generated for further processing by other factories, or for oto 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 havoutput 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 first OUTPUT clause, and flows through the pipeline unchanged since this clausenothing 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 meThe 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 wedgea 100 degree blunting angle.


TeeFactory FACTORY REFERENCE

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)


FACTORY REFERENCE TestFactory

on the meric

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 dependingtype of the operands. If both arguments may be converted to numbers, then nucomparisons are used, otherwise string comparisons are.

B.21.3 Assumptions

None.


TestFactory FACTORY REFERENCE

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
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 Disk—Read 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

C-1FME Reference Manual — Version 2.0

ACRONYMS Safe Software Inc.

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-2 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

C-3FME Reference Manual — Version 2.0

ACRONYMS Safe Software Inc.

C-4 FME Reference Manual — Version 2.0

Date post:	23-May-2017
Category:	Documents
Upload:	jjrelucio3748
View:	226 times
Download:	7 times

refman

Documents