While geo-spatial data is often supplied in the form of vector-format files such as Shapefiles, there are situations where Shapefiles are unsuitable or inefficient. One such situation is where you need to take geo-spatial data from one library and use it in a different library. For example, imagine that you have read a set of geometries out of a Shapefile and want to store them in a database, or work with them using the Shapely library. Because the different Python libraries all use their own private classes to represent geo-spatial data, you can't just take an OGR Geometry object and pass it to Shapely, or use a GDAL SpatialReference object to define the datum and projection to use for data stored in a database.
In these situations, you need to have an independent format for representing and storing geo-spatial data that isn't limited to just one particular Python library. This format, the lingua franca for vector-format geo-spatial data, is called Well-Known Text or WKT.
WKT is a compact text-based description of a geo-spatial object such as a point, a line, or a polygon. For example, here is a geometry defining the boundary of the Vatican City in the World Borders Dataset, converted into a WKT string:
POLYGON ((12.445090330888604 41.90311752178485, 12.451653339580503 41.907989033391232, 12.456660170953796 41.901426024699163, 12.445090330888604 41.90311752178485))
As you can see, the WKT string contains a straightforward text description of a geometry—in this case, a polygon consisting of four x,y coordinates. Obviously, WKT text strings can be far more complex than this, containing many thousands of points and storing multipolygons and collections of different geometries. No matter how complex the geometry is, it can still be represented as a simple text string.
Note
There is an equivalent binary format called Well-Known Binary (WKB) that stores the same information as binary data. WKB is often used to store geo-spatial data into a database.
WKT strings can also be used to represent a spatial reference encompassing a projection, a datum, and/or a coordinate system. For example, here is an osgeo.osr.SpatialReference object representing a geographic coordinate system using the WGS84 datum, converted into a WKT string:
GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563,AUTHORITY["EPSG","7030"]],TOWGS84[0,0,0,0,0,0,0],AUTHORITY["EPSG","6326"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9108"]],AUTHORITY["EPSG","4326"]]
As with geometry representations, spatial references in WKT format can be used to pass a spatial reference from one Python library to another.
In this recipe, we will make use of the World Borders Dataset to obtain polygons defining the borders of Thailand and Myanmar. We will then transfer these polygons into Shapely, and use Shapely's capabilities to calculate the common border between these two countries.
If you haven't already done so, download the World Borders Dataset from the Thematic Mapping website:
http://thematicmapping.org/downloads/world_borders.php
The World Borders Dataset conveniently includes ISO 3166 two-character country codes for each feature, so we can identify the features corresponding to Thailand and Myanmar as we read through the Shapefile:
import osgeo.ogr
shapefile = osgeo.ogr.Open("TM_WORLD_BORDERS-0.3.shp")
layer = shapefile.GetLayer(0)
for i in range(layer.GetFeatureCount()):
feature = layer.GetFeature(i)
if feature.GetField("ISO2") == "TH":
...
elif feature.GetField("ISO2") == "MM":
...
Tip
This code assumes that you have placed the TM_WORLD_BORDERS-0.3.shp Shapefile in the same directory as the Python script. If you've placed it into a different directory, you'll need to adjust the osgeo.ogr.Open() statement to match.
Once we have identified the features we want, it is easy to extract the features' geometries as WKT strings:
geometry = feature.GetGeometryRef() wkt = geometry.ExportToWkt()
We can then convert these to Shapely geometry objects using the shapely.wkt module:
import shapely.wkt ... border = shapely.wkt.loads(wkt)
Now that we have the objects in Shapely, we can use Shapely's computational geometry capabilities to calculate the common border between these two countries:
commonBorder = thailandBorder.intersection(myanmarBorder)
The result will be a LineString (or a MultiLineString if the border is broken up into more than one part). If we wanted to, we could then convert this Shapely object back into an OGR geometry, and save it into a Shapefile again:
wkt = shapely.wkt.dumps(commonBorder) feature = osgeo.ogr.Feature(dstLayer.GetLayerDefn()) feature.SetGeometry(osgeo.ogr.CreateGeometryFromWkt(wkt)) dstLayer.CreateFeature(feature) feature.Destroy()
With the common border saved into a Shapefile, we can display the results as a map:
The contents of the common-border/border.shp Shapefile is represented by the heavy line along the countries' common borders.
Here is the entire program used to calculate this common border:
# calcCommonBorders.py
import os,os.path,shutil
import osgeo.ogr
import shapely.wkt
# Load the thai and myanmar polygons from the world borders
# dataset.
shapefile = osgeo.ogr.Open("TM_WORLD_BORDERS-0.3.shp")
layer = shapefile.GetLayer(0)
thailand = None
myanmar = None
for i in range(layer.GetFeatureCount()):
feature = layer.GetFeature(i)
if feature.GetField("ISO2") == "TH":
geometry = feature.GetGeometryRef()
thailand = shapely.wkt.loads(geometry.ExportToWkt())
elif feature.GetField("ISO2") == "MM":
geometry = feature.GetGeometryRef()
myanmar = shapely.wkt.loads(geometry.ExportToWkt())
# Calculate the common border.
commonBorder = thailand.intersection(myanmar)
# Save the common border into a new shapefile.
if os.path.exists("common-border"):
shutil.rmtree("common-border")
os.mkdir("common-border")
spatialReference = osgeo.osr.SpatialReference()
spatialReference.SetWellKnownGeogCS('WGS84')
driver = osgeo.ogr.GetDriverByName("ESRI Shapefile")
dstPath = os.path.join("common-border", "border.shp")
dstFile = driver.CreateDataSource(dstPath)
dstLayer = dstFile.CreateLayer("layer", spatialReference)
wkt = shapely.wkt.dumps(commonBorder)
feature = osgeo.ogr.Feature(dstLayer.GetLayerDefn())
feature.SetGeometry(osgeo.ogr.CreateGeometryFromWkt(wkt))
dstLayer.CreateFeature(feature)
feature.Destroy()
dstFile.Destroy()
Tip
If you've placed your TM_WORLD_BORDERS-0.3.shp Shapefile into a different directory, change the osgeo.ogr.Open() statement to include a suitable directory path.
We will use this Shapefile later in this chapter to calculate the length of the Thai-Myanmar border, so make sure you generate and keep a copy of the common-borders/border.shp Shapefile.
WKT is not only useful for transferring geometries from one Python library to another. It can also be a useful way of storing geo-spatial data without having to deal with the complexity and constraints imposed by using Shapefiles.
In this example, we will read a set of polygons from the World Borders Dataset, convert them to WKT format, and save them as text files:
# saveAsText.py
import os,os.path,shutil
import osgeo.ogr
if os.path.exists("country-wkt-files"):
shutil.rmtree("country-wkt-files")
os.mkdir("country-wkt-files")
shapefile = osgeo.ogr.Open("TM_WORLD_BORDERS-0.3.shp")
layer = shapefile.GetLayer(0)
for i in range(layer.GetFeatureCount()):
feature = layer.GetFeature(i)
name = feature.GetField("NAME")
geometry = feature.GetGeometryRef()
f = file(os.path.join("country-wkt-files",
name + ".txt"), "w")
f.write(geometry.ExportToWkt())
f.close()
Tip
As usual, you'll need to change the osgeo.ogr.Open() statement to include a directory path if you've stored the Shapefile in a different directory.
You might be wondering why you want to do this, rather than creating a Shapefile to store your geo-spatial data. Well, Shapefiles are limited in that all the features in a single Shapefile must have the same geometry type. Also, the complexity of setting up metadata and saving geometries can be overkill for some applications. Sometimes, dealing with plain text is just easier.