Menu Home

Transforming Geospatial Coordinates from the Command-Line

If you have a need for converting coordinates between two different Coordinate Reference Systems (CRS) quickly, then this post is for you. In this post I will introduce a Geospatial Library called PROJ that was created to project, transform, and convert geographic coordinates.

Example Case

You are a consultant managing client land and you receive survey plats of proposed oil and gas locations that need to be inspected before construction. It is your job to find these locations on the client’s property, and do a timber assessment of the areas impacted.

The survey plats you receive come from various surveying firms, hired by the oil and gas entities. Some plats include annotations showing Lat/Long coordinates for the project location, but others provide coordinates in the State Plane projection system. As the contractor, you need a simple way to transform the State Plane coordinates to WGS 84, so you can easily locate these sites on a map. This is where PROJ can help.

PROJ

PROJ is software provided by the Open Source Geospatial Foundation (OSGeo). PROJ provides applications in the form of command-line utilities, as well as an API that allows developers to incorporate PROJ into their custom software. PROJ is a very diverse library, but I want to focus only on just two of the command-line utilities I use most often, proj and cs2cs.

  • proj – this utility will convert geographic coordinates to projected coordinates within the same datum. An example would be going from WGS84 lat/long to a projected system like Mercator (e.g., Web Mercator such as used by Google Maps, MapBox and OpenStreetMap)
  • cs2cs – this utility will perform transformations from one CRS to another (e.g., from WGS84 to UTM).

PROJ defines three different coordinate operations, projections, conversions, and transformations. These topics can get overly technical, but if you are interested in learning more I recommend you read the PROJ documentation for yourself. Simply put, a projection is an operation that maps a 3D sphere (i.e., the earth’s surface) onto a 2D plane (i.e., paper map, computer screens, etc.), conversion is an operation on the same datum (e.g., changing units, swapping out an axis, etc), and transformation is an operation on reference systems with different datums. If you need a refresher on what a datum is see this datum wiki page.

Examples of How to Use PROJ

Before using PROJ, it must be installed. PROJ is supported on Windows, Linux and Mac OS X operating systems. PROJ can be downloaded here.

Once installed, you can use the command-line utilities proj and cs2cs. PROJ uses custom “proj-strings” to define coordinate transformations. An example proj-string is shown:

+proj=merc +lat_ts=56.5 +ellps=GRS80

The proj-string shown above will convert geographic coordinates to the Mercator projection, with a latitude of true scale at 56.5 degrees (NOTE: the scale of a Mercator map changes as you get further from the Equator, thus why the lat_ts parameter is needed here), using the GRS80 ellipsoid.

I’m using a Mac and my command line interface uses the UNIX zsh shell, but you can use a Windows command prompt as well. PROJ supports an interactive mode. If you enter the above string, the command line will prompt you to input the geographic coordinates on the next line. PROJ also works as a UNIX filter, which means you can pipe the input data using the echo command. UNIX pipes and filters allow the output of one command to be used as the input to another command, in a chained fashion. The pipe operator is ” | ” or (Shift + \ on most keyboards) For example, here is how I would run this example using the echo command with proj to convert coordinates (-94.52039, 31.67682) to the Mercator projection:

$ echo -94.52039 31.67682 | proj +proj=merc +lat_ts=56.5 +ellps=GRS80

The output would be -10521962.13 3698526.67. Note that these are projected coordinates with units in meters, and the output matches the input in X (easting, Longitude), Y (northing, Latitude) format.

Let’s see another example using cs2cs, transforming coordinates to UTM NAD 83 Zone 15. Here we use the cs2cs utility since we are transforming between two different datums, GRS80 datum used by WGS84, and NAD83.

$ echo -94.52039 31.67682 | cs2cs +init=epsg:4326 +to +init=epsg:26915

Note here that we used the shorthand EPSG codes for WGS84 (4326) and UTM NAD 83 Zone 15 (26915). EPSG codes are well-documented standards that represent coordinate systems worldwide. You can lookup EPSG codes for many coordinate reference systems at SpatialReference.org.

Let’s go back to our example case outlined above, and convert the survey plat coordinates we received from Texas North-Central Zone using the NAD 27 datum to WGS84. I’ll use cs2cs again because we are transforming between two datums.

$ echo 3055478.930 165433.208 | cs2cs +init=epsg:32038 +to +init=epsg:4326 +to_meter=0.30480069601219

The output from the command above is 94d5’31.879″W 32d4’27.582″N 0.000. Again, the output format is X, Y, but notice we have Z=0.000. Z refers to the vertical plane (i.e. elevation), which is not relevant for this transformation. Also, note that we need to use the +to_meter keyword because the input coordinates for the Texas North Central Zone NAD 27 projection were provided in US survey feet, instead of meters. It’s important to know what the input units are for the coordinate reference system.

Another very useful feature of PROJ is that you can convert coordinates stored in a file by providing the path to the file to proj or cs2cs. Note, if you run the utility in the same directory where the file is located, you only need to supply the filename, otherwise a relative path is needed.

As an example, let’s say you have a file with hundreds of WGS84 coordinates that you exported from a GIS database. This file is in a text format – saved with a .txt extension. Below is a small sample of this file.

Text file with WGS84 coordinates

What if you had to convert all of the coordinates in this file? Entering hundreds of these as separate command would take way too long. If the file is in your present working directory, then here’s how you can do this efficiently using cs2cs.

cs2cs +init=epsg:4326 +to +init=epsg:26915 coords.txt

You could even redirect the output to a separate file using the redirect operator (>), like so

cs2cs +init=epsg:4326 +to +init=epsg:26915 coords.txt > utm_coords.txt

This is much, much, more efficient than entering them manually. With just one line of input you can convert many coordinates at once.

This is just a small sample of what PROJ can do. PROJ is a useful conversion utility that I use frequently, and it has saved me much time and effort when converting geographic and projected coordinates. If you would like to learn more about the PROJ library, then I’d highly recommend visiting the website at PROJ.org.


References:

PROJ contributors (2020). PROJ coordinate transformation software library. Open Source Geospatial Foundation. URL https://proj.org/.

Featured Image: Photo by Elena Mozhvilo on Unsplash

Categories: Geospatial

Tagged as:

JwL

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: