Esri Geodatabase (File Geodatabase API) Reader/Writer

Transcription

1 FME Readers and Writers 2013 SP1 Esri Geodatabase (File Geodatabase API) Reader/Writer The Esri Geodatabase (File Geodatabase API) reader and writer modules allow FME to store data in and retrieve data from Esri s File Geodatabase, based on the File Geodatabase API. In contrast to corresponding ArcObjects-based Readers/Writers, no additional software is required to use this format, but less functionality is available. Format Notes The File Geodatabase API reader/writer provides Geodatabase support without an installed Esri product on Windows and Linux; however, it is a limited set of geometry and works only with 10.0 File Geodatabases or higher. For example, annotation is unsupported. For more information: FME and ESRI Versions and Compatibility Comparison of FME Readers/Writers for SDE and Geodatabase Overview The Geodatabase reader and writer translates several different types of features: reading and writing of point, line, polygon, and multipoint feature classes partial reading of some of the other File Geodatabase types (e.g., dimensions, parcel fabrics) exposed using the basic geometric types listed above reading and writing of non-spatial tables The File Geodatabase modules also provide the following capabilities: Programmatic Table Creation: Feature classes and tables need not be created before a data import operation. All table creation details are handled by FME. When FME creates a feature class, it consults the first feature destined for the corresponding feature type to determine if Z and/or measure values should be included. Index Creation: Attribute fields can be flagged as indexed. When the associated feature class or table is created, attribute indices are created as well. Table Selection: A subset of tables and feature classes to read can be selected from a list. Feature classes within a feature dataset are listed together for easy selection. Attribute Query Support: SQL where clauses can be specified to limit the data being exported. Spatial Query Support: A bounding box can be specified to limit the data being exported. This can be configured in the reader settings or accessed via the FeatureReader transformer

2 Esri Geodatabase (File Geodatabase API) Reader/Writer Enhanced Geometry Model: Curved segments within lines and polygons are maintained as arcs and not stroked. Fully Automatic Import and Export: FME supports fully automated import and export of data through its graphical interfaces, e.g. FME Quick Translator. This is ideal for quick data imports and exports. Unicode Support: Geodatabase text columns are stored in the UTF-16 encoding on Windows platforms, and in UTF-32 encoding on Linux platforms. FME can read and write this data. Feature Datasets: Feature datasets are read and written. On read, they are included in FME s feature type names. On write, they are created as necessary. Domains and Subtypes: Coded domain and subtype fields are read and written using their decoded values (i.e., the descriptions and not coded values are used). In the current release, FME does not support creating tables or feature classes with subtypes or domain restrictions, and does not include this metadata on the schema. Coordinate Systems: Features are tagged with their spatial reference (coordinate system) on read. Feature classes are created with the spatial reference associated with incoming features. Note that the File Geodatabase API supports a fixed list of coordinate systems. Data in other coordinate systems cannot be read or written. Measures: In addition to reading and writing X, Y, and optional Z ordinates, measure values are supported as well. Esri Geodatabase (File Geodatabase API) Quick Facts About Quick Facts Tables Format Type Identifier Reader/Writer Licensing Level Dependencies Dataset Type Feature Type Typical File Extensions Automated Translation Support User-Defined Attributes Coordinate System Support Generic Color Support Spatial Index FILEGDB Both Professional See Format Notes. File Geodatabase (*.gdb directory) Feature dataset/feature class feature class table.gdb Yes Yes Yes No Always

3 FME Readers and Writers 2013 SP1 Schema Required Transaction Support Enhanced Geometry Geometry Type Yes No Yes filegdb_type Geometry Support Geometry Supported? Geometry Supported? aggregate yes point yes circles yes polygon yes circular arc yes raster no donut polygon yes solid no elliptical arc yes surface no ellipses yes text no line yes z values yes none yes Reader Overview The reader extracts data from the selected File Geodatabase using the File Geodatabase API. ArcGIS feature classes and tables become FME feature types, and ArcGIS features and rows become FME features. For feature classes within a feature dataset, the FME feature type name is formed as follows: <feature dataset name>/<feature class name>. As with other database readers in FME, the IDs and DEF directives are used to determine which feature classes and tables to read. This is covered in more detail in subsequent sections. WHERE clauses and bounding box constraints can be used to further limit the data read. Esri Geodatabase (File Geodatabase API) Reader Parameters Schema Attributes Additional Attributes to Expose This parameter exposes Format Attributes in Workbench when you create a workspace: In a dynamic scenario, it means these attributes can be passed to the output dataset at runtime

4 Esri Geodatabase (File Geodatabase API) Reader/Writer In a non-dynamic scenario where you have multiple feature types, it is convenient to expose additional attributes from one parameter. For example, if you have ten feature types and want to expose the same attribute in each one, it is easier to define it once than it is to set each feature type individually in the workspace. Search Envelope Use Search Envelope Using the minimum and maximum x and y parameters, define a bounding box that will be used to filter the input features. Only features that interact with the bounding box are returned. If all four coordinates of the search envelope are specified as 0, the search envelope will be disabled. Clip to Search Envelope Check this box if you want to remove any portions of exported features outside the area of interest. Writer Overview The writer exports data to a new or existing File Geodatabase using the File Geodatabase API. Esri Geodatabase (File Geodatabase API) Writer Parameters Overwrite Geodatabase Setting this parameter to Yes deletes the existing database. The default is No. Attribute Definitions The supported attribute types are listed in the following table. FME Attribute Type smallint int single double date objectid globalid guid blob

5 FME Readers and Writers 2013 SP1 FME Attribute Type xml text smallint This type is used to represent 16-bit integer values. int This type is used to represent 32-bit integer values. single This type is used to represent 32-bit float values. double This type is used to represent 64-bit float values. date This is used to store and retrieve date information within the Geodatabase. When a date field is read by the Geodatabase, it is placed in the FME feature with the form HHMMSS, YYYYMMDD, or YYYYMMDDHHMMSS. The time portion is specified using the 24-hour clock. When writing, the date attribute must also be in one of these three forms. These forms are compatible with all other FME dates. objectid This type is used to represent object IDs. There is (at most) one per row. This field type is read only; values will be automatically assigned on write. globalid This type is used to represent global IDs. There is one per row. This field type is read only. guid This type is used to represent GUIDs. blob This type is used to represent arbitrary length binary data. xml This type is used to represent XML data

6 Esri Geodatabase (File Geodatabase API) Reader/Writer text(n) This type is used to represent character values with a length not exceeding n characters. FME will read from and write to geodatabases using the UTF-16 (on Windows platforms) or UTF-32 (on Linux platforms) encodings. Tips for Using the File Geodatabase Writer When reading or writing, NULL values are represented by missing attributes. When inserting data, if an attribute is missing, NULL will be written in its place. When reading, NULL values will result in the corresponding attribute being omitted on the feature. Format Mapping File Directives Note: FME translations were originally based entirely on Mapping Files. Mapping files still exist under the surface but the interface has been almost entirely replaced by Workbench's graphical interface. Information on mapping files is included in this manual for technical reference purposes. Mapping Files are ASCII text files that contain a series of rules that specify the FME readers, writers, and transformations (in Workbench, these are represented by transformers). A mapping file (.fme) is a series of commands for FME to perform. Mapping files use functions and factories to transform the data. They also contain the definition and parameters for the readers and writers. A mapping file can be run through the FME Quick Translator. Before FME Workbench was designed and developed (about 2001), this was the only way to configure a translation process. You can create a mapping file either by manually programming it or by using FME Workbench. In Workbench, there is still an Export as.fme tool on the toolbar. The Workbench file format itself (.fmw file) is partially a mapping file with an XML header. When FME runs a workspace it is converted into a mapping file. Since mapping files are written in a plain ASCII format, so you can use any text editor to edit them. To see what a mapping file looks like: select one or more transformers in Workbench, copy them, and then paste them in a text editor. The mapping file equivalent of those transformers will be pasted. Directives and Reader/Writer Keywords Directives are processed by the reader or writer. Directives are prefixed by the current <ReaderKeyword> or <WriterKeyword> in a mapping file. By default, the keywords for formats are the format shortname (viewable in the Formats Gallery, or in the Format Quick Facts tables. Reader Directives This section describes the directives that are recognized by the File Geodatabase reader module

7 FME Readers and Writers 2013 SP1 Each directive is prefixed by the current <ReaderKeyword> when placed in a mapping file. Unless otherwise specified, the <ReaderKeyword> for the File Geodatabase reader is FILEGDB. DATASET This directive specifies the path to the File Geodatabase. Required <ReaderKeyword>_DATASET test.gdb DEF Source File Geodatabase This directive defines the schema of source (reader) feature types along with associated parameters. <ReaderKeyword>_DEF <feature type name> filegdb_type ( geodb_no_geom geodb_point geodb_multipoint geodb_polyline geodb_polygon) [ <attribute name> <attribute type> ]+ [ filegdb_where <where clause> ] Feature Type Properties DEF Line Parameter filegdb_type Contents Specifies the type of the table or feature class. : Allowed Geometries <attribute name> Specifies the name and type of a field in the table or feature class. See Attribute Definitions

8 Esri Geodatabase (File Geodatabase API) Reader/Writer DEF Line Parameter Contents below for a list of valid field types. The spatial (shape) column is not included here. : User Attributes filegb_where Specifies a where clause used to filter data when reading from the table or feature class. Do not include the word WHERE in this setting. : WHERE Clause IDs This directive specifies which feature types (ultimately, feature classes and tables) will be read. If the IDs directive is not specified, but DEF directives are, the DEF directives will determine which feature types will be read. If neither is specified, all feature types are read. <ReaderKeyword>_IDs ( <feature type name> )+ Feature Types to Read SEARCH_ENVELOPE This directive specifies a bounding box used to filter the input features. Only features that interact with the bounding box are returned. If this directive is not specified, then all features are returned.this directive is only honoured by the MITAB-based MapInfo reader in FME. This is the only MapInfo reader available on the UNIX platforms supported by FME, and can optionally be enabled on Windows platforms by renaming the mitab.dll in the FME home directory to mapinfo.dll. <ReaderKeyword>_SEARCH_ENVELOPE <minx> <miny> <maxx> <maxy> Note: If all four coordinates of the search envelope are specified as zero, the search envelope will be disabled

9 FME Readers and Writers 2013 SP1 Minimum X, Minimum Y, Maximum X, Maximum Y SEARCH_ENVELOPE_COORDINATE_SYSTEM This directive specifies the coordinate system of the search envelope if it is different than the coordinate system of the data. The COORDINATE_SYSTEM directive, which specifies the coordinate system associated with the data to be read, must always be set if the SEARCH_ENVELOPE_COORDINATE_ SYSTEM directive is set. If this directive is set, the minimum and maximum points of the search envelope are reprojected from the SEARCH_ENVELOPE_COORDINATE_SYSTEM to the reader COORDINATE_SYSTEM prior to applying the envelope. <ReaderKeyword>_SEARCH_ENVELOPE_COORDINATE_SYSTEM <coordinate system> Search Envelope Coordinate System CLIP_TO_ENVELOPE This directive specifies whether or not FME should clip features to the envelope specified in the SEARCH_ENVELOPE directive. Values YES NO (default) <ReaderKeyword>_CLIP_TO_ENVELOPE [yes no] Clip To Envelope EXPOSED_ATTRS This directive allows the selection of format attributes to be explicitly added to the reader feature type

10 Esri Geodatabase (File Geodatabase API) Reader/Writer This is similar to exposing format attributes on a reader feature type once it has been generated; however, it is even more powerful because it enables schema-driven applications other than Workbench to access and leverage these attributes as if they were explicitly on the schema as user attributes. The result of picking a list of attributes is a comma-separated list of attribute names and types that will be added to the schema features. Currently all reader feature types will receive the same set of additional schema attributes for a given instance of the reader. Not applicable. While it is possible for FME Objects applications to invoke this directive, the required format is not documented. This directive is intended for use in our GUI applications (for example, Workbench) only. Additional Attributes to Expose RETRIEVE_ALL_SCHEMAS This parameter is only applicable when generating a mapping file, generating a workspace or when retrieving schemas in an FME Objects application. When set to yes, schemas for all of the tables and feature classes in the database are returned. When set to no (or missing), and if RETRIEVE_ALL_TABLE_NAMES is similarly set to no (or missing), only schemas requested by the IDs parameter are returned. Values YES NO (default) Not applicable. FME Objects applications would include RETRIEVE_ALL_SCHEMAS followed by YES in the parameters array passed to IFMEUniversalReader::open(). Not applicable

11 FME Readers and Writers 2013 SP1 RETRIEVE_ALL_TABLE_NAMES This parameter is only applicable when generating a mapping file, generating a workspace or when retrieving schemas in an FME Objects application. When set to yes, and if RETRIEVE_ALL_SCHEMAS is set to no (or missing), names for all of the tables and feature classes in the database are returned. When set to no (or missing), and if RETRIEVE_ALL_SCHEMAS is similarly set to no (or missing), the schemas requested by the IDs directive are returned. Values YES NO (default) Not applicable. FME Objects applications would include RETRIEVE_ALL_TABLE_NAMES followed by YES in the parameters array passed to IFMEUniversalReader::open(). Not applicable (used when you browse a Table List) EXPOSED_ATTRS This directive allows the selection of format attributes to be explicitly added to the reader feature type. This is similar to exposing format attributes on a reader feature type once it has been generated; however, it is even more powerful because it enables schema-driven applications other than Workbench to access and leverage these attributes as if they were explicitly on the schema as user attributes. The result of picking a list of attributes is a comma-separated list of attribute names and types that will be added to the schema features. Currently all reader feature types will receive the same set of additional schema attributes for a given instance of the reader. Not applicable. While it is possible for FME Objects applications to invoke this directive, the required format is not documented. This directive is intended for use in our GUI applications (for example, Workbench) only

12 Esri Geodatabase (File Geodatabase API) Reader/Writer Additional Attributes to Expose Writer Directives This section describes the directives that are recognized by the File Geodatabase writer module. Each directive is prefixed by the current <WriterKeyword> when placed in a mapping file. Unless otherwise specified, the <WriterKeyword> for the File Geodatabase writer is FILEGDB. DATASET This directive specifies the path to the File Geodatabase. Required <WriterKeyword>_DATASET test.gdb DEF Destination File Geodatabase This directive defines the schema of destination (writer) feature types along with associated parameters. Required <WriterKeyword>_DEF <feature type name> filegdb_type ( geodb_no_geom geodb_point geodb_multipoint geodb_polyline geodb_polygon) [ <attribute name> <attribute type>[,<index type>] ]* [ filegdb_drop_table ( YES NO ) ] [ filegdb_truncate_table ( YES NO ) ] [ filegdb_object_id_field <object ID field> ] [ filegdb_object_id_alias <object ID alias> ] [ filegdb_shape_field <spatial column field> ] [ filegdb_shape_alias <spatial column alias> ] [ filegdb_config_keyword <configuration keyword> ] [ filegdb_xy_tolerance <xy tolerance> ] [ filegdb_z_tolerance <z tolerance> ]

13 FME Readers and Writers 2013 SP1 Feature Type Properties DEF Line Parameter filegdb_type Contents Specifies the type of the table or feature class. : Allowed Geometries <attribute name> Specifies the name and type of a field in the table or feature class. See Attribute Definitions below for a list of valid field types. The spatial (shape) column is not included here. The valid index types are: INDEXED The specified indices are created along with tables or feature classes; they are never added to existing tables or feature classes. : User Attributes filegb_drop_table Specifies whether or not to drop the existing table or feature class, if it exists. The default value is no. : Drop Existing Table filegb_truncate_table Specifies whether or not to truncate the existing table or feature class, if it exists. The default value is no. : Truncate Existing Table filegb_object_id_field Specifies the name of the column containing object IDs for the current table or feature class. If the value conflicts with a user attribute, then the writer will change the value for this field (by appending a numeric suffix) and log a warning. The default value is OBJECTID. : Object ID Field filegb_object_id_alias Specifies the alias for the object IDs column for the current table or feature class. The alias is used in ArcMap (and possibly in other ArcGIS products) when viewing data; the object ID column will be labeled by its alias. This is only relevant if the table or feature class will

14 Esri Geodatabase (File Geodatabase API) Reader/Writer DEF Line Parameter Contents be created by FME. The default value is OBJECTID. : Object ID Alias filegdb_shape_field Specifies the name of the column containing the shape data for features in the current feature class. This applies only to feature classes. If the value conflicts with a user attribute, then the writer will change the value for this field (by appending a numeric suffix) and log a warning. The default value is SHAPE. : Shape Field filegdb_shape_alias Specifies the alias for the shape data column. This applies only to feature classes. When viewing data in ArcMap (and possibly in other ArcGIS products), the shape data column will be labelled by its alias. The default value is SHAPE. This is only relevant if the table or feature class will be created by FME. : Shape Alias filegdb_config_keyword Specifies the configuration keyword. See ArcGIS documentation for additional details. This is only relevant if the table or feature class will be created by FME. The default value is DEFAULTS. : Configuration Keyword filegdb_xy_tolerance Specifies the xy tolerance for the feature class. By default, the File Geodatabase API determines the value based on the coordinate system. : XY Tolerance filegdb_z_tolerance Specifies the z tolerance for the feature class. This is only relevant if the table or feature class will be created by FME, and the data includes z values. The default value is : Z Tolerance

15 FME Readers and Writers 2013 SP1 OVERWRITE_GEODB If set to YES, deletes the existing database. <WriterKeyword>_OVERWRITE_GEODB ( YES NO ) Overwrite Geodatabase Feature Representation In addition to the generic FME feature attributes that FME Workbench adds to all features (see About Feature Attributes), this format adds the format-specific attributes described in this section. The Geodatabase modules make use of the following special attribute names. Attribute Name filegdb_type Contents The type of geometric entity stored within the feature. The valid values are listed below: geodb_no_geom geodb_point geodb_multipoint geodb_polyline geodb_polygon Features read or written also have an attribute for each column in the database table. Tables filegdb_type: geodb_no_geom Features with this value consist of no coordinates. Points filegdb_type: geodb_point Features with this value are point features

16 Esri Geodatabase (File Geodatabase API) Reader/Writer Multipoints filegdb_type: geodb_multipoint Features with this value are multi-part features consisting of points. Polylines filegdb_type: geodb_polyline Features with this value consist of one or more linear geometries (arcs, lines, or paths consisting of arcs and/or lines). Polygons filegdb_type: geodb_polygon Features with this value consist of one or more area geometries (polygons, ellipses, or donuts)