|
|
Home | Docs | Issue Tracker | FAQ | Download |
|
|
| Author: | Frank Warmerdam |
|---|---|
| Contact: | warmerdam at pobox.com |
| Last Updated: | 2011-11-15 |
Table of Contents
OGR output support was added to MapServer 6.0. It provides an output driver to produce feature style output suitable as a return result from WMS GetFeatureInfo or WFS GetFeature requests. OGR feature output depends on MapServer being built against the GDAL/OGR library. The OGR output driver should be enabled in MapServer 6.0 or newer when INPUT=OGR appears in the version string.
Details of OGR output formats allowed are controlled by an OUTPUTFORMAT declaration. The declarations define the OGR format driver to be used, creation options specific to that driver, and more general instructions to MapServer on how to package multi-file results and whether to try and build the result on disk or in memory.
Examples:
OUTPUTFORMAT
NAME "CSV"
DRIVER "OGR/CSV"
MIMETYPE "text/csv"
FORMATOPTION "LCO:GEOMETRY=AS_WKT"
FORMATOPTION "STORAGE=memory"
FORMATOPTION "FORM=simple"
FORMATOPTION "FILENAME=result.csv"
END
OUTPUTFORMAT
NAME "OGRGML"
DRIVER "OGR/GML"
FORMATOPTION "STORAGE=filesystem"
FORMATOPTION "FORM=multipart"
FORMATOPTION "FILENAME=result.gml"
END
OUTPUTFORMAT
NAME "SHAPEZIP"
DRIVER "OGR/ESRI Shapefile"
FORMATOPTION "STORAGE=memory"
FORMATOPTION "FORM=zip"
FORMATOPTION "FILENAME=result.zip"
END
The OGR format driver to be used is determined by the name appearing after “OGR/” in the DRIVER argument. This name should match one of the formats listed as supported for the “-f” argument to ogr2ogr in the ogr2ogr usage message.
The IMAGEMODE for OGR output is FEATURE, but this is implicit and does not need to be explicitly stated for OGR output driver declarations.
The OGR renderer will support the following FORMATOPTION declarations:
Indicates where the datasource should be stored while being written. “file” is the default.
If “memory” then it will be created in /vsimem/ - but this is only suitable for drivers supporting VSI*L which we can’t easily determine automatically.
If “filesystem”, then a directory for temporary files (specified using WEB TEMPPATH or MS_TEMPPATH) will be used for writing and reading back the file(s) to stream to the client.
If “stream” then the datasource will be created with a name “/vsistdout” as an attempt to write directly to stdout. Only a few OGR drivers will work properly in this mode (ie. CSV, perhaps kml, gml).
The OGR output driver utilizes several items from the LAYER level METADATA object. Some of these were originally intended for GML output or are primarily intended to support WFS.
(Optional) A comma delimited list of formats supported for WFS GetFeature responses. The OUTPUTFORMAT NAME values should be listed.
"wfs_getfeature_formatlist" "OGRGML,SHAPEZIP,CSV"
(Optional) A comma delimited list of items to include, or keyword “all”. You can enable full exposure by using the keyword “all”.
"gml_include_items" "all"
You can specify a list of attributes (fields) for partial exposure, such as:
"gml_include_items" "Name,ID"
The new default behaviour is to expose no attributes at all.
(Optional) An alias for an attribute’s name. The resulting file will refer to this attribute by the alias. Here is an example:
"gml_province_alias" "prov"
(Optional) If this field is “auto” then some input feature drivers (ie. OGR, and native shapefiles) will automatically populate the type, width and precision metadata for the layer based on the source file.
"gml_types" "auto"
(Optional) Set the geometry type of OGR layers created from this MapServer LAYER. One of “Point”, “LineString”, “Polygon”, “MultiPoint”, “MultiLineString”, “MultiPolygon”, “GeometryCollection”, “Geometry”, or “None”. Most are fairly obvious, but “Geometry” can be used to represent a mix of geometry types, and “None” is sometimes suitable for layers without geometry. Note that layers which are a mix of polygon and multipolygon would normally have to be described as “Geometry”. To produce 2.5D output append “25D” to the geometry type (ie. “Polygon25D”). Note that Z values are only carried by MapServer if built with USE_POINT_Z_M support.
"ows_geomtype" "Polygon"
In order for WMS GetFeatureInfo to allow selection of OGR output formats, the mime type associated with the OUTPUTFORMAT must be listed in this metadata item.
"wms_feature_info_mime_type" "text/csv"
In MapServer we have POINT, LINE and POLYGON layers which also allow for features with multiple points, lines or polygons. However, in the OGC Simple Feature geometry model used by OGR a point and multipoint layer are quite distinct. Likewise for a LineString and MultiLineString and Polygon an MultiPolygon layer type.
To work around the mismatches between the MapServer and OGR geometry models, there is a mechanism to specify the geometry type to be used when exporting through OGR. This is the “wfs/ows_geomtype” metadata item on the layer. It may be one of one of “Point”, “LineString”, “Polygon”, “MultiPoint”, “MultiLineString”, “MultiPolygon”, “GeometryCollection”, “Geometry”, or “None”.
If this item is not specified, then “Point”, “LineString” or “Polygon” will be used depending on the TYPE of the LAYER. In cases of mixed geometry types (ie. polygons and multipolygons) the geometry type should be set to “Geometry” which means any geometry type.
"ows_geomtype" "Geometry"
For OGR output it is highly desirable to be able to create the output fields with the appropriate datatype, width and precision to reflect the source feature definition.
It is possible to set the gml_[item]_type, gml_[item]_width and gml_[item]_precision metadata on the layer to provide detailed field definitions:
METADATA
"gml_ID_type" "Integer"
"gml_ID_width" "8"
"gml_AREA_type" "Real"
"gml_AREA_width" "15"
"gml_AREA_precision" "6"
"gml_NAME_type" "Character"
"gml_NAME_width" "64"
...
However, doing this manually is tedious and error prone. For that reason some feature sources (at least OGR, Shapefiles, POSTGIS and ORACLESPATIAL) support a mechanism to automatically populate this information from the source datastore. To accomplish this specify:
"gml_types" "auto"
If no effort is made to set type, width and precision information for attribute fields, they will all be treated as variable length character fields when writing through OGR.
One of the challenges returning generalized feature formats is that many such formats consists of multiple files which must be returned in the result. There are three approaches taken to this based on the FORM FORMATOPTION in the OUTPUTFORMAT declaration.
One caveat with “zip” results is that this option is only available if the GDAL/OGR version is 1.8 or newer (or a 1.8 development later than approximately Oct 15, 2010). Earlier versions of GDAL/OGR lacked the zipping capability needed.
The MSAutoTest test suite contains a test case for use of OGR Output from WFS. The mapfile is at:
The comments at the start of the file have a variety of sample requests that can be run against the map, as long as [MAPFILE] is replaced with the mapfile name. They requests should be run against mapserv sitting in the msautotest/wxs directory.