Public Member Functions | Properties
OgrLayer Class Reference

Represents a single layer in GDAL/OGR datasource or result of SQL query against such datasource. More...

List of all members.

Public Member Functions

bool ClearStyles ()
 Clears all the styles stored for current layer in datasource.
void Close ()
 Closes current layer and releases resources associated with it.
bool Deserialize (string newVal)
 Restores the state of layer from string generated with OgrLayer.Serialize method.
bool GenerateCategories (string Fieldname, tkClassificationType ClassificationType, int numClasses, tkMapColor colorStart, tkMapColor colorEnd, tkColorSchemeType schemeType)
 Generates visualization categories for OGR layer.
string get_ErrorMsg (int ErrorCode)
 Gets the description of the specific error code.
bool get_Extents (out Extents layerExtents, bool forceLoading=false)
 Gets extents of the layer.
int get_FeatureCount (bool forceLoading=false)
 Returns number of features in the layer.
string get_StyleName (int styleIndex)
 Gets name of the style with particular index.
bool get_SupportsEditing (tkOgrSaveType editingType)
 Gets a value indicating whether the layer supports editing.
string get_UpdateSourceErrorMsg (int errorIndex)
 Gets a specified error message from the log registered during OgrLayer.SaveChanges call.
int get_UpdateSourceErrorShapeIndex (int errorIndex)
 Gets shape index associated with specified error message from the log registered during OgrLayer.SaveChanges call.
Shapefile GetBuffer ()
 Gets layer data represented as in-memory shapefile.
string GetConnectionString ()
 Returns connection string which was used to open this layer.
int GetNumStyles ()
 Gets number of styles stored for the layer in datasource.
string GetSourceQuery ()
 Gets layer name or SQL query which was used to open this layer.
bool OpenFromDatabase (string connectionString, string layerName, bool forUpdate)
 Opens layer with specified name from the OGR datasource.
bool OpenFromFile (string Filename, bool forUpdate)
 Opens OGR layer from specified file. If the datasource holds several layers only the first one will be opened.
bool OpenFromQuery (string connectionString, string sql)
 Runs SQL query against datasource and returns results as a temporary layer.
bool RedefineQuery (string newSql)
 Runs a new query against the datasource.
bool ReloadFromSource ()
 Discards all the local changes and reloads layer from the source.
bool RemoveStyle (string StyleName)
 Removes style with particular name from the datasource.
tkOgrSaveResult SaveChanges (out int savedCount, tkOgrSaveType saveType=tkOgrSaveType.ostSaveAll, bool validateShapes=true)
 Saves local changes to the datasource.
string Serialize ()
 Serializes the state of layer to a string, which can be later restored with OgrLayer.Deserialize.
bool TestCapability (tkOgrLayerCapability capability)
 Test whether current layer supports certain functionality.

Properties

ShpfileType ActiveShapeType [get, set]
 Gets or sets the type of the active shape type for the layer (is used in OgrLayer.GetBuffer for example).
object AvailableShapeTypes [get, set]
 Gets the array of available shape types inside OGR layer (should be cast to ShpfileType[]).
bool DataIsReprojected [get]
 Gets a value indicating whether underlying data ( OgrLayer.GetBuffer ) was reprojected.
string DriverName [get]
 Gets name of the driver which is used to access layer datasource.
bool DynamicLoading [get, set]
 Gets or sets a value indicating whether features for large layers are to be loaded dynamically when moving to the new portions of map.
string FIDColumnName [get]
 Gets name of feature ID column.
string GdalLastErrorMsg [get]
 Extracts the last error message reported by GDAL library.
string GeometryColumnName [get]
 Gets the name of geometry column which was used to fetch geometry for current layer.
GeoProjection GeoProjection [get]
 Gets GeoProjection associated with current layer.
ICallback GlobalCallback [get, set]
 Gets or sets a Callback object which handles progress and error messages.
string Key [get, set]
 A text string associated with object. Any value can be stored by developer in this property.
string LabelExpression [get, set]
 Gets or sets an expression for label generation for the layer.
tkLineLabelOrientation LabelOrientation [get, set]
 Gets or sets label orientation for polyline layers.
tkLabelPositioning LabelPosition [get, set]
 Gets or sets position of labels relative to their parent features.
int LastErrorCode [get]
 Gets code of the last error which took place inside this object.
int MaxFeatureCount [get, set]
 Gets or sets maximum number of features to be loaded in the memory.
string Name [get]
 Gets name of the layer.
ShpfileType ShapeType [get]
 Gets shape type of the current layer.
ShpfileType ShapeType2D [get]
 Gets "flattened" type of the current layer, i.e. Z and M components will be ignored.
tkOgrSourceType SourceType [get]
 Gets source type of the layer.
bool SupportsStyles [get]
 Checks whether the layers supports saving of styles to the datasource.
int UpdateSourceErrorCount [get]
 Gets the number of errors registered in the log during OgrLayer.SaveChanges call.

Detailed Description

Represents a single layer in GDAL/OGR datasource or result of SQL query against such datasource.

dot_inline_dotgraph_53.png

A. How to open.

There are 2 main ways to open a layer from OGR datasource:

SQL query provides more flexibility, while opening layer as a whole may support editing if forUpdate argument was passed and such capability is supported by driver.

Here is a summary of various ways to open a layer:

 private static string CONNECTION_STRING = "PG:host=localhost dbname=london user=postgres password=1234";
 
 var layer = new OgrLayer();
 string layerName = "waterways";

1) open one of exiting layers:

 if (!layer.OpenFromDatabase(CONNECTION_STRING, layerName))
     Debug.Print("Failed to open layer: " + layer.get_ErrorMsg(layer.LastErrorCode));

2) return temporary layer by a query:

 if (!layer.OpenFromQuery(CONNECTION_STRING, "SELECT * FROM " + layerName))
     Debug.Print("Failed to run a query: " + layer.get_ErrorMsg(layer.LastErrorCode));

3) the same using datasource:

 var ds = new OgrDatasource();
 if (!ds.Open(CONNECTION_STRING))
 {    
     Debug.Print("Failed to open datasource: " + ds.GdalLastErrorMsg);
 }
 else
 {
     layer = ds.GetLayerByName(layerName);
     if (layer == null)
     {
         Debug.Print("Failed to open layer: " + ds.get_ErrorMsg(ds.LastErrorCode));
     }
     
     // or run a query
     layer = ds.RunQuery("SELECT * FROM " + layerName);
     if (layer == null)
     {
         Debug.Print("Failed to run a query: " + ds.get_ErrorMsg(ds.LastErrorCode));
     }
 }

4) using FileManager class:

 var fm = new FileManager();
 layer = fm.OpenFromDatabase(CONNECTION_STRING, layerName);   // layer name or query can be passed here
 if (layer = null)
 {
     Debug.WriteLine("Failed to open layer: " + fm.get_ErrorMsg(fm.LastErrorCode));
 
     // let's check GDAL error as well
     var gs = new GlobalSettings();
     Debug.WriteLine("GDAL error message: " + gs.GdalLastErrorMsg);
 }

For spatial databases layer name corresponds to the name of underlying table with some driver specifics, like including name of database schema as a prefix or the name of the geometry column. Use OgrDatasource class to get the names of available layers.

B. How to add to the map.

Instances of OgrLayer class can be added to the map directly using AxMap.AddLayer method or opened internally using AxMap.OpenFromDatabase method. In each case OgrLayer.GetBuffer method will be called automatically which triggers the loading of data from datasource. Afterwards underlying in-memory shapefile will be used for all rendering purposes.

OgrLayer added to the map can be accessed using AxMap.get_OgrLayer property.

 var layer = new OgrLayer();
 if (!layer.OpenFromDatabase(CONNECTION_STRING, layerName))
 {
     Debug.Print("Failed to open layer: " + layer.get_ErrorMsg(layer.LastErrorCode));
     Debug.Print("GDAL last error: " + layer.GdalLastErrorMsg);
 }
 else
 {
     map.RemoveAllLayers();
     // either a) set layer projection to the map
     map.GrabProjectionFromData = true;
 
     // or b) set map projection and reproject layer if needed
     map.Projection = tkMapProjection.PROJECTION_GOOGLE_MERCATOR;
     new GlobalSettings() {ReprojectLayersOnAdding = true};
 
     int layerHandle = map.AddLayer(layer, true);
     if (layerHandle == -1)
     {
         Debug.Print("Failed to add layer to the map");
     }
     else
     {
         map.Redraw();
 
         // get the reference back from map
         var sameLayerFromMap = map.get_OgrLayer(layerHandle);
     }
 }

AxMap.AddLayerFromDatabase provides a short-cut for both 2 operations: opening a layer and adding it to the map.

OGR layers support built reprojection of layers (GlobalSettings.ReprojectLayersOnAdding) and AxMap.GrabProjectionFromData properties. Depending on their values underlying shapefile data may be reprojected on adding it to the map. Use OgrLayer.DataIsReprojected property to test whether it happened.

OGR layers support map state serialization with AxMap.SerializeMapState. Their data will be reloaded after AxMap.DeserializeMapState is called.

C. How to access the data.

OgrLayer uses in-memory shapefile to provide its data to clients.

This shapefile is populated on the first call to OgrLayer.GetBuffer method. On subsequent calls cached values will be used (lazy loading pattern).

 var layer = new OgrLayer();
 if (layer.OpenFromDatabase(CONNECTION_STRING, layerName))
 {
     // let's first try to extract some info without loading the data locally
     Extents ext = null;
     if (layer.get_Extents(out ext))
     {
         Debug.WriteLine("Extents w/o loading the data: " + ext.ToDebugString());
     }
     Debug.WriteLine("Feature count: " + layer.FeatureCount);
 
     // now load the data locally and display the same info
     var shapefile = layer.GetBuffer();
     if (shapefile != null)
     {
         Debug.WriteLine("Extents from the loaded data: " + shapefile.Extents.ToDebugString());
         Debug.WriteLine("Shape count: " + shapefile.NumShapes);
 
         Debug.WriteLine("Layer fields: ");
         for (int i = 0; i < shapefile.NumFields; i++)
         {
             Debug.WriteLine(shapefile.get_Field(i).Name);
         }
     }
 }

OgrLayer.GetBuffer method maps:

OgrLayer may support database tables without geometry column. For example, all tables in PostGreSQL database will be listed as layers if no PostGIS support was added to the database. In such case table records will be converted to rows of attribute table, while shapefile will contain empty shapes with Shape.ShapeType = SHP_NULLSHAPE.

AxMap.get_GetObject and AxMap.get_Shapefile will return underlying in-memory shapefile. This allows to use unified code for processing both regular shapefile layers and OGR layers and ensures compatibility of OGR layers with previously written client code.

OgrLayer encapsulates an instance of GDAL's OGRLayer C++ class. Check its documentation to better understand what's going on under the hood.

Note:
Starting from version 4.9.3 OgrLayer will use dynamic loading for large layers. See details in OgrLayer.DynamicLoading property.

D. How to edit the data.

Note:
See description of editing in this section.


Here is a diagram for the OgrLayer class.

dot_inline_dotgraph_54.png

Graph description

New API 4.9.3:
Added in version 4.9.3

Member Function Documentation

Clears all the styles stored for current layer in datasource.

Returns:
True on success.
void OgrLayer.Close ( )

Closes current layer and releases resources associated with it.

It's recommended to call this method as soon as the layer is no longer needed.

bool OgrLayer.Deserialize ( string  newVal)

Restores the state of layer from string generated with OgrLayer.Serialize method.

Deserialization includes:
a) reconnection to the datasource;
b) grabbing data from it;
c) restoring of visualization options set for underlying shapefile.

Particular set of actions depends on the state of the object before serialization.

Any data currently stored in this instance will be discarded.

Parameters:
newValString generated with OgrLayer.Serialize method.
Returns:
True on success.
bool OgrLayer.GenerateCategories ( string  Fieldname,
tkClassificationType  ClassificationType,
int  numClasses,
tkMapColor  colorStart,
tkMapColor  colorEnd,
tkColorSchemeType  schemeType 
)

Generates visualization categories for OGR layer.

Parameters:
FieldnameField name to use as a base for classification.
ClassificationTypeType of classification.
numClassesNumber of classes (is not used with unique values classification type).
colorStartStarting color for the color scheme.
colorEndEnd color for the color scheme.
schemeTypeType of color scheme.
Returns:
True on success.

The whole set of features will be used during classification, not only those currently loaded into memory. Therefore the method has definite advantage over calling OgrLayer.GetBuffer.Categories.Generate directly for large layers.

Categories will be added to underlying shapefile (OgrLayer.GetBuffer). This method will trigger the population of this shapefile if it's not yet in memory.

The following code opens "buildings" layer, generates categories based on "population" field and then saves them as a "new_style" to the datasource.

 var layer = new OgrLayer();
 if (!layer.OpenFromDatabase(CONNECTION_STRING, "buildings"))
 {
     Debug.WriteLine("Failed to open the layer: " + layer.GdalLastErrorMsg);
 }
 else
 {
     layer.LabelExpression = "[Name]";
     layer.LabelPosition = tkLabelPositioning.lpCenter;
     layer.GlobalCallback = this;
 
     if (!layer.GenerateCategories("population", tkClassificationType.ctEqualIntervals,
         10, tkMapColor.Blue, tkMapColor.Yellow, tkColorSchemeType.ctSchemeGraduated))
     {
         Debug.WriteLine("Failed to generated categories: " + layer.get_ErrorMsg(layer.LastErrorCode));
     }
     else
     {
         var sf = layer.GetBuffer();
         Debug.WriteLine("Number of generated categories: " + sf.Categories.Count);
 
         // save it as a new style
         if (!layer.SaveStyle("new_style"))
         {
             Debug.WriteLine("Failed to save style: " + layer.GdalLastErrorMsg);
         }
         else
         {
             Debug.WriteLine("The new style has been saved.");
         }
     }
     layer.Close();
 }
string OgrLayer.get_ErrorMsg ( int  ErrorCode)

Gets the description of the specific error code.

Parameters:
ErrorCodeThe error code returned by LastErrorCode property.
Returns:
String with the description.
bool OgrLayer.get_Extents ( out Extents  layerExtents,
bool  forceLoading = false 
)

Gets extents of the layer.

Depending on driver implementation this method may retrieve this information directly from underlying datasource without loading the data, which provides performance benefits.

Parameters:
layerExtentsRetrieved extents.
forceLoadingTrue to instruct driver to load the data locally if information can't be retrieved from underlying datasource otherwise.
Returns:
True on success.
int OgrLayer.get_FeatureCount ( bool  forceLoading = false)

Returns number of features in the layer.

Depending on driver implementation this method may retrieve this information directly from underlying datasource without loading the data, which provides performance benefits.

Parameters:
forceLoadingTrue to instruct driver to load the data locally if information can't be retrieved from underlying datasource otherwise.
Returns:
Number of features in the layer.
string OgrLayer.get_StyleName ( int  styleIndex)

Gets name of the style with particular index.

Parameters:
styleIndexIndex of style.
Returns:
Name of the style.

Gets layer data represented as in-memory shapefile.

Implements lazy loading pattern, i.e. data will be grabbed from underlying datasource on the first call and will be used for all subsequent calls. To force re-read of the data from datasource use OgrLayer.ReloadFromSource.

This method will automatically be called after adding the layer to the map via AxMap.AddLayer or AxMap.AddLayerFromDatabase.

Returns:
Instance of shapefile with layer data or null on failure or for uninitialized layer.

Returns connection string which was used to open this layer.

Attention:
Password in connection string is stored as plain text. Consider measures to ensure its security.

Gets number of styles stored for the layer in datasource.

MapWinGIS provides its own functionality to store visualization styles for OGR layers. Each style hold serialized state of underlying shapefile and is stored in mw_styles table of database. The table will be created on the first call of OgrLayer.SaveStyle or on the first call of OgrDatasource.ImportShapefile when GlobalSettings.UseOgrStyles is set to true.

The default style has empty string name (""). When GlobalSettings.UseOgrStyles is set to true, this style will be automatically created during shapefile import and then will be applied for the layer on further loadings. Alternative styles can be saved and applied with OgrLayer.SaveStyle and OgrLayer.ApplyStyle respectively.

The style table has following definition for PostGIS datasource:

 CREATE Table mw_styles (
    StyleId serial primary key, 
    LayerName varchar(128), 
    StyleName varchar(128), 
    Style text, 
    CONSTRAINT layer_style_unique UNIQUE (LayerName,StyleName)
 );
Returns:
Number of styles.

Gets layer name or SQL query which was used to open this layer.

bool OgrLayer.OpenFromDatabase ( string  connectionString,
string  layerName,
bool  forUpdate 
)

Opens layer with specified name from the OGR datasource.

This method is called internally by OgrDatasource.GetLayerByName.

Parameters:
connectionStringConnection string or filename.
layerNameLayer name.
forUpdateIndicates whether the returned layer will support saving of changes back to source (the functionality should be supported by particular driver).
Returns:
True on success.
bool OgrLayer.OpenFromFile ( string  Filename,
bool  forUpdate 
)

Opens OGR layer from specified file. If the datasource holds several layers only the first one will be opened.

Parameters:
FilenameFilename of the datasource to open.
forUpdateIndicates whether the returned layer will support saving of changes back to source (the functionality should be supported by particular driver).
Returns:
True on success.
bool OgrLayer.OpenFromQuery ( string  connectionString,
string  sql 
)

Runs SQL query against datasource and returns results as a temporary layer.

This method is called internally by OgrDatasource.RunQuery.

Parameters:
connectionStringConnection string or filename.
sqlSQL query.
Returns:
True on success.
bool OgrLayer.RedefineQuery ( string  newSql)

Runs a new query against the datasource.

The layer must be opened with OgrLayer.OpenFromQuery or OgrDatasource.RunQuery (OgrLayer.SourceType = ogrQuery) in order for this method to work.

Parameters:
newSqlNew SQL command.
Returns:
True on success.

Discards all the local changes and reloads layer from the source.

Returns:
True on success.
bool OgrLayer.RemoveStyle ( string  StyleName)

Removes style with particular name from the datasource.

Parameters:
StyleNameThe name of the style.
Returns:
True on success.
string OgrLayer.Serialize ( )

Serializes the state of layer to a string, which can be later restored with OgrLayer.Deserialize.

State information includes connection string, layer name (or query string) and visualization options for underlying shapefile (in case it is already populated when the method was called.)

Attention:
Serialized string holds connection password as a plain text. Consider measures to ensure its security.
Returns:
String with state information.

Test whether current layer supports certain functionality.

In most cases no actual attempts to perform requested operation is made.

Parameters:
capabilityA capability to test.
Returns:
True in case the capability is supported by the layer.

The following code opens a layer from datasource and display which capabilities are supported for it.

 var layer = new OgrLayer();
 if (!layer.OpenFromDatabase(CONNECTION_STRING, "waterways", true))
 {
     Debug.Print("Failed to open layer: " + layer.get_ErrorMsg(layer.LastErrorCode));
 }
 else
 {
     var values = Enum.GetValues(typeof(MapWinGIS.tkOgrLayerCapability));
     foreach (tkOgrLayerCapability value in values)
     {
         Debug.Print(value.ToString() + ": " + layer.TestCapability(value).ToString());
     }
 }

Property Documentation

Gets or sets the type of the active shape type for the layer (is used in OgrLayer.GetBuffer for example).

New API 4.9.4:
Added in version 4.9.4
object OgrLayer.AvailableShapeTypes [get, set]

Gets the array of available shape types inside OGR layer (should be cast to ShpfileType[]).

New API 4.9.4:
Added in version 4.9.4
string OgrLayer.DriverName [get]

Gets name of the driver which is used to access layer datasource.

bool OgrLayer.DynamicLoading [get, set]

Gets or sets a value indicating whether features for large layers are to be loaded dynamically when moving to the new portions of map.

When set to false only the number of features set by OgrLayer.MaxFeatureCount is loaded into memory. No further attempts to load additional features will be done.

In dynamic loading mode after map extents change a check is made whether features for the requested extents are already in memory. If not the data loading is started in the background thread. When the loading is over all the features currently stored in memory will be discarded. If the amount of features in new map extents exceeds OgrLayer.MaxFeatureCount no background loading will be done.

The mode is chosen automatically when the layer is opened depending on the number of features. But afterwards it's possible possible to change the value.

Extracts the last error message reported by GDAL library.

Gets the name of geometry column which was used to fetch geometry for current layer.

Depending on data format, a layer may support several geometry columns but only one will be used to provide shape data via OgrLayer.GetBuffer(). By default the first column with geometry/geography type will be used. To access other columns temporary layers can be opened via OgrDatasource.RunQuery.

Gets GeoProjection associated with current layer.

Corresponds to SRID set for the layer in underlying datasource. When SRID isn't specified (i.e. equals 0), empty GeoProjection instance will be returned.

Gets or sets a Callback object which handles progress and error messages.

Deprecated:
v4.9.3 Use GlobalSettings.ApplicationCallback instead.
string OgrLayer.Key [get, set]

A text string associated with object. Any value can be stored by developer in this property.

string OgrLayer.LabelExpression [get, set]

Gets or sets an expression for label generation for the layer.

The syntax of expression is the same as for Shapefile.Labels.Generate method. To generate labels based on single field use "[FieldName]" syntax. The property is supported for dynamic loading mode, where labels will be generated on the fly after each zooming operation.

Gets or sets label orientation for polyline layers.

See also:
OgrLayer.LabelExpression

Gets or sets position of labels relative to their parent features.

See also:
OgrLayer.LabelExpression

Gets code of the last error which took place inside this object.

int OgrLayer.MaxFeatureCount [get, set]

Gets or sets maximum number of features to be loaded in the memory.

If total number of features exceeds this number the layer will be rendered in dynamic loading mode (see OgrLayer.DynamicLoading). During dynamic loading if number of features for the new map extents exceeds this number they won't be loaded. The default value of property can be changed with GlobalSettings.OgrLayerMaxFeatureCount.

See also:
OgrLayer.GetBuffer
string OgrLayer.Name [get]

Gets name of the layer.

The name may correspond to table name in underlying database or store some generic string like "sql_statement" for temporary layers opened by OgrDatasource.RunQuery.

Gets shape type of the current layer.

The property automatically maps underlying OGRwkbGeometryType to corresponding shape type.

Gets "flattened" type of the current layer, i.e. Z and M components will be ignored.

Gets source type of the layer.

Any new instance of class starts with ogrUninitialized. Successful call of OgrLayer.OpenFromDatabase method will set it to ogrDbTable, OgrLayer.OpenFromQuery - to ogrQuery.

Returns:
Source type.

Checks whether the layers supports saving of styles to the datasource.

This property will check the presence of mw_styles table in the datasource and then will try to create one if it's missing. If neither succeeds, false will be returned.

 All Classes Files Functions Enumerations Properties Events