Georeferencing hard copy or pdf maps

Written by Krey Price  |  Surface Water Solutions
Copyright © The RAS Solution 2019.  All rights reserved. 

Using RAS Mapper as a GIS tool Part 3:
Georeferencing hard copy or pdf maps

Have you ever received your background data in hard copy or pdf format and wanted to view it in its georeferenced location? For this final topic in our three-part series on using RAS Mapper as a GIS tool, we'll cover the steps required to georeference a map using world files. [For additional background see the previous posts Part 1: Terrain modification and Part 2: Web imagery with world files.] 

Before you begin any georeferencing process, always check that you are using the correct projection (and confirm the desired projection with the client or end user of the data.) If you don't know which projection to use, you may need to check with the provider of your LiDAR data or other geospatial data. If your terrain file has been provided in geotif format, another option is to add the terrain file to RAS Mapper without assigning a projection, then double click on the name of the terrain, select the "Source Files" tab, and click on the "Info" button to view the GDAL metadata. The projection should show up under the "PROJCS" tag:

If you don't have the relevant projection file available, most projections (with the exception of local project grids) are available online for free download. Projections are typically catalogued according to European Petroleum Survey Group (EPSG) codes maintained by the International Association of Oil and Gas Producers. [When you think about it, it makes sense that the oil and gas industry would have a substantial interest in pinpointing global locations for exploratory wells and other critical geospatial data!]
Online repositories for projection files such as spatialreference.org include the EPSG code with each spatial reference system:



Projection files can also be copied from the prj file associated with any shape file that matches the target coordinate system. In any case, once I've got the correct prj files, I like to place it in a separate subfolder named "projection" that I create under my project directory, and then assign it a file name such as "GDA 94 MGA Zone 55 Projection.prj" that clearly distinguishes it is a projection file (as opposed to a HEC-RAS project prj file!) I also like to make sure that the projection folder includes only a single prj file so that anyone who picks up the project in the future knows the intended projection. [RAS Mapper sometimes loses the spatial reference system association and that can avoid confusion when it is re-assigned.]

Once you've confirmed that you are using the correct projection (typically by turning on web imagery and checking that it lines up with your terrain, shape files, or other geospatial data for your project) you can georeference any hard copy, scans, image files, or pdf files within the specified projection.

The georeferencing steps are covered on our new YouTube channel in this video walk-through beginning at 6:37:

Here are the steps covered in the video: 

1. For hard copies, scan your image to a raster format (commonly jpg or tif). For pdf files, use "save as" in Adobe Acrobat and select jpg (resolution can be adjusted under settings). For other file types, you may wish to use the Snipping tool that ships with Windows and save the screenshot as a jpg (best if it's on a high-resolution screen as you'll be stuck with the screen resolution and not the original source file's resolution).

2. Create a new file in Word, Notepad, Wordpad, or other text editor or word processor (or copy an existing world file and skip to Step #5).
3. Enter six lines of numerical text. Use dummy values from "original world file" column in the World File Calculator spreadsheet (available for free downloaded here) or take an initial guess at values based on the assumed coordinates of the upper left pixel.
4. Save file as plain text format (*.txt) using the same file name as the image file (select "default settings" if prompted).
5. Change file extension in Windows Explorer to *.tfw, *.jgw, *.bpw, etc. as appropriate to match your image file format (click yes if prompted with unusable file warning).

6. Under Map Layers in RAS Mapper, right-click and select "Add Existing Layer". Be sure to drag down file types to show all image files. Browse to file and select OK.
7. Using the measure tool in RAS Mapper, measure the distance between two points that are a known distance apart (preferably from a scale bar or coordinate tick marks on the map).
8. Open the World File Calculator spreadsheet (or create your own - there's really not that much to it!) and enter the measured and actual distances under Line #1 (cells D3 and E3) and again in Line #4 (cells D6 and E6).
9. Copy values from "New World File" column, open the world file in a text editor, and paste the updated values over the old values.
10. Right click on the image file and select "remove layer".
11. Re-add the image file and adjust transparency as needed.
12. Using the measure tool in RAS Mapper, click on a known point from the original image (with incorrect location), then double-click on the same known point based on the correct location.
13. Select "Copy coordinates to clipboard".
14. Paste the coordinates into Cell C10 in the spreadsheet (Note: values will be replaced in the cell range C10:F12 but only C10:D11 are used in the spreadsheet).
15. Copy "New World File" column over the previous values in the world file.
15. Remove and re-add the image file under map layers in RAS Mapper.
16. Adjust transparency as needed to confirm common points are now co-located. Measure the scale bar to confirm correct scaling.

Hopefully the first try will get you close enough for your purposes, but the process can be repeated to fine-tune the results as needed. You can also use these steps to convert geospatial data to or from a local project grid for which projection details are unavailable.


Keep in mind that these adjustments only provide a visual approximation and should be treated cautiously if the results are to be used for permitting or construction purposes. In that case, you'd want to get a surveyor on board with the proper tools to apply all of the required warping factors and address any other discrepancies. 

The full set of parameters in a projection file can get quite complex; projecting a curved surface to a flat plane comes with mathematical difficulties that have plagued mapmakers for centuries. Here's a great video explaining why all world maps are wrong.

With these difficulties in mind, it is no surprise that even if you get two points to line up perfectly, a third point can still be shifted, particularly for points located a significant distance away from the alignment points. For manual georeferencing, I suggest using alignment points that are as far apart as possible for your selected zoom extent to avoid major discrepancies.

Note on rotation factors: The above steps assume that north is straight up in your hard copy or pdf map based on the applied projection (or at least close enough to straight up to suit your purposes). If not, rotation terms can be added to the world file, but in my experience this can lead to some confusion, as the pixels shift on the fly at different zoom levels.

Although rotation terms can be added to the world file by measuring the angular difference between lines drawn between two known points, my preference is to make rotation adjustments graphically before diving into any world file adjustments. Raster images can be rotated in a number of programs (Photoshop, Paintshop, Word, PowerPoint, etc.) to achieve a proper north alignment. [The "Z axis rotation" can be used in Microsoft products to apply specific sub-degree rotation factors.] The rotation terms can then remain as zero values in the world file.
We hope you have found this useful for your work. Please let us know if you have any comments or suggestions for improving these processes! Thanks for tuning in, and as always, let us know your recommendations for upcoming blog topics.



Collecting ideas for future posts: One subject we are working on for a future post is hacks for removing flow from HEC-RAS models. Internal boundary conditions are very useful for adding flow anywhere in your model, but removing flow can be a tedious process requiring a bit of creativity. Some new features coming in Version 5.1 may simplify the process, but in the meantime I've seen some clever workarounds being applied that we would like to share with this forum; please contact me if you have done this successfully so we can perhaps feature your method in an upcoming blog post.

And speaking of Version 5.1, right at the top of my wish list for HEC-RAS updates is for project files to be called *.ras files, *.hrp (HEC-RAS Project) files or any unique extension that doesn't happen to coincide with thousands of other files on my computer (in this case, of course the ESRI-format *.prj projection files). I understand the Corps may have been first in this case (calling their project files prj's well before ESRI did) but the rest of the geospatial industry is not about to change their format, so maybe HEC-RAS project files can get a unique identity in the next version - or at least a search tool within RAS that can recognize and distinguish HEC-RAS-format project files. Let us know if you agree and maybe we can turn this into a grass roots, crowd-based request!

Shifting web imagery with world files for HEC-RAS

Written by Krey Price  |  Surface Water Solutions
Copyright © The RAS Solution 2019.  All rights reserved. 

Using RAS Mapper as a GIS tool Part 2:
Shifting Web Imagery with World Files

Have you ever tried pulling web imagery into RAS Mapper only to find that it doesn't line up with your existing shape files, terrain surfaces, or other geospatial data?  In this second of a three-part series on using RAS Mapper as a GIS tool we'll cover the modification of world files for georeferencing.

Photo by Franck V. on Unsplash

In some cases, the misalignment of web imagery may result from an incorrectly applied projection file. If needed, projection files can be downloaded for free from spatialreference.org and other online data sources. You can check the projection of your terrain file by double-clicking on it in RAS Mapper, then select the "Source Files" tab and view the metadata using the Info column. 

If you have confirmed that the correct projection file is being used and you are still having issues, there are a few additional workarounds you may wish to try. One option is to select the "Alternate HEC-RAS Raster Warping Method" under "Tools | Options" in RAS Mapper. This method applies the gDAL OGR vector reprojection. I have found this method useful for resolving discrepancies in European data sets in particular.

In some cases, the alternate method doesn't do the trick either. RAS Mapper uses the ESRI projection file format, which as I understand it does not recognize TOWGS84 parameters and in some cases improperly applies the proj.4 projection parameters. In any case, you may find yourself stuck with misaligned web imagery.

One workaround is to save static images of your web imagery and then shift the image to the correct location by making adjustments to the world file (Wikipedia has a good summary of the six lines of code comprising a world file here).

Here's a video walk-through of the process:

The "World File Calculator" spreadsheet referenced in the video can be downloaded here:

Here are the steps covered in the video:

1. Adjust transparency as needed so that you can see a known point in both the web imagery and in the survey or LiDAR data.
2. Using the measure tool in RAS Mapper, click on a known point from the web imagery (with incorrect location), then double-click on the the same known point based on the correct location.
3. Select "Copy coordinates to clipboard".
4. Zoom to preferred extents for results and save view (click here for further details on saved views and static imagery).

5. Right-click on web imagery and select "export layer". Note: RAS Mapper currently has two export options: tif and jpg. The tif format will embed the metadata and georeferencing information into the encoded text of a geotif file without generating a separate world file. A tfw file can still be created to override the embedded georeferencing, but I suggest using the jpg format so that the world file is automatically generated. Save the image (I suggest creating an "aerial imagery" subfolder within the current project's directory structure to store static images).

6. Open the world file calculator spreadsheet.

7. Paste the coordinates from RAS Mapper into the blue cell.

8. Open the newly created jgw file (jpg format world file) in a text editor and copy the values.

9. Paste the values into the "Original World File" column of the spreadsheet.

10. Copy the "New World File" values over the original values in the jgw file, save, and close.  

11. Under Map Layers in RAS Mapper, right-click and select "Add Existing Layer". Be sure to drag down file types to show all image files and browse to the newly created file.
12. Adjust transparency as needed to confirm common points are now co-located.

The process can be repeated to fine-tune the positioning. Because a static image won't be pyramided like web imagery, you will unfortunately need to complete these steps at every desired zoom level and view extent, the but the process of saving static images allows you to control the appearance of your figures without having to worry about losing your internet connection while presenting or viewing results.

Note that these steps assume the units and north alignment are the same (or close enough) between the data sets and that the static image can be simply shifted without scaling or rotation factors, which we'll cover in more detail in our next post.
Please let us know any feedback or suggestions for improvements or additional efficiencies in adjusting web imagery.

The Projection File

Written by Christopher Goodell, P.E., D.WRE
Copyright © The RAS Solution 2015.  All rights reserved.

RAS Mapper is a window in HEC-RAS that allows you to preprocess 2D areas, map results, and manage background images.  In future versions of HEC-RAS, RAS Mapper will become more and more prevalent in our HEC-RAS modeling experience.  As I understand it, eventually RAS Mapper and the geometry editor window may merge to form the front-end interface for HEC-RAS, replacing the iconic “Main RAS Window”.



But that’s speculation.  What is not speculation is that if you want to use HEC-RAS 5.0 for anything more than a very basic model, there is really no getting around using RAS Mapper, and by extension…The Projection File!  The projection file defines a specific geographic coordinate system and projection and is somewhat of a new thing for us HEC-RAS modelers (it has actually been a part of RAS Mapper since it’s inception, but now with 2D modeling and web-imagery in Version 5.0, RAS Mapper is becoming an integral part of HEC-RAS modeling). The projection file requires us to know something about geospatial mapping (i.e. GIS), which we really haven’t had to know too much of before as RAS users.  But if you wish to use RAS Mapper, and you will, you need to understand what the projection file is and how to get one.  Without it, RAS Mapper is pretty much useless.  Adding a projection file to our RAS project establishes the project’s geospatial reference.  Projection files have the extension *.prj.  Be careful not to confuse this with the HEC-RAS project file, also with an extension *.prj.  They both reside in your HEC-RAS project directory, but only a properly formatted projection file will work in RAS Mapper for setting your projection.

The projection file is really just a simple text file with keywords in a specific format.  In fact, it is a single string written in “Well-Known Text” format, or WKT.  It’s simple, easy to read and was created by the Open GIS Consortium.  Here’s what a projection file looks like on the inside.  Notice that there are some keywords, identified by all CAPS, followed by some data related to the key-word, contained in brackets [  ].  I've color-coded it to make it easier to see what goes with what.  The purple color denotes the highest order in the hierarchy, followed by blue, then green, then red.  In other words, a red keyword is a “child” to a green keyword, green is a child to blue, and blue is a child to purple. 



Each keyword and the bracketed data that follows is called a “clause”.  The first and primary clause, PROJCS, stands for Projected Coordinate System.  The projected coordinate system is made up of the following sub-clauses:

1.  Geographic Coordinate System (GEOGCS), which is based on degrees latitude and longitude and contains the horizontal reference datum (DATUM), and the reference meridian for longitude measurements (PRIMEM).  DATUM also contains a description of the shape of the earth (SPHEROID), which in the example above is the Clarke Ellipsoid of 1866.  Units (UNIT) are inferred here only for the GEOGCS, in this case degrees.
2.   Projection (PROJECTION), which is the projection from geographic coordinates (lat/long) to projected coordinates.  This is essentially how the three-dimensional spheroid (Earth) is projected to a two-dimensional viewing medium.  In the example above, Transverse Mercator is selected, which uses the Universal Transverse Mercator (UTM) coordinate system.

Cylindrical projection - transverse aspect © USGS

3.  Various projection parameter values (PARAMETER).  The parameter is labeled in quotations, followed by its value. 
4.  Units for the projected coordinate system (UNIT).  Here meters are used as the linear unit with a conversion factor of “1”.  The conversion factor converts the described units into meters.  If “FOOT_US” is used, then the conversion factor would be 0.30480060960121924.

There may be some additional clauses in your projection file, but the ones listed above seem to be typical.  All of the keywords used in WKT format with descriptions can be found at GeoAPI here.
You can write your own projection files and GeospatialPython.com presents a method (there are other examples out there, just Google it).  However, it is much easier and much more practical to find an already-compiled projection file and use that.  If you have a georeferenced HEC-RAS project already, every shapefile used to create your geometry components (stream centerline, xscutlines, flowlines, etc.) comes with a projection file.  Just find where it is stored on your computer and use that. 

If you don’t have the GIS files that were used to create your georeferenced HEC-RAS project, you can find projection files in at least three different places:  ArcGIS 10.0 or earlier, spatialreference.org, and the EPSG Projection Database.  If you know of others, please comment below!

When using any of these sources, make sure you pick the correct projection file.  You’ll know if it is the right one by bringing in web imagery to RAS Mapper and checking to make sure that everything lines up spatially correct.  ArcGIS (Versions prior to 10.1) includes a Coordinate Systems folder that contains more than 5,000 geographic, projected, and vertical coordinate systems.  Unfortunately, newer versions of ArcGIS do not come with that folder.  If you have ArcGIS 10.1 or newer or don’t have ArcGIS at all, you can access a large database of spatial reference systems at http://spatialreference.org/












If you go to spatialreference.org, make sure you only select from the EPSG, IAU2000, or spatialreference.org references.  The ESRI references only contain the GEOGCS clause in the projection file and not the complete PROJCS clause.  They will not work in RAS Mapper.   Once you’ve found the reference you want, click on it, then select “.PRJ File” from the list of available formats.  A projection file will then be downloaded to your computer and you are ready to use it in RAS Mapper.  There is a convenient Search box that allows you to search on key words for your reference.  For example, if your project is in Hawaii and you know your horizontal datum is NAD83, you can enter the keywords:  Hawaii NAD83, click the Search button and you’ll see the following list of spatial references:



Also available on line is the EPSG Projection Database, hosted on GoogleCode by geospatialpython.org.  Here you'll find a text file of a multitude of projection files in the correct WKT format that can easily be copied and pasted into your own projection file.

Once you’ve selected a projection file and assigned it to RAS Mapper, double-check that it is correct by adding web imagery.  If everything lines up, you are good to go.  The figure below shows the Muncie dataset in RAS Mapper, with an incorrect projection file assigned.



Obviously our streamlines and cross sections in this example are not correctly aligned in Muncie Indiana where they belong.  The incorrect projection file has landed us in the middle of Alberta, Canada!




Reassigning the correct projection file gets the model back to its correct spatial reference.





Does anyone know of any other sources of projection files that we can use in HEC-RAS?  If so, please comment below.

And here are some great follow-up comments from Dudley M.  Thanks Dudley for passing along this information!  "I was using RAS Mapper to set the SRS. From the menu Tools->Set Projection for Project. This brings up the "Spatial Reference Projection File" dialog where you can specify a filename. RAS Mapper will read the file and interpret as Chris described to get the coordinate system and projection.

I knew I had a valid ESRI projection file because it came from ArcCatalog. But RAS Mapper complained "Error - unable to make a projection with specified file. Make sure the file is a valid ESRI projection (*.prj) file." I looked in the projection file with a text editor. I saw that mine included a vertical datum clause. Chris didn't mention this in the post, so I thought maybe this was something RAS Mapper didn't like. The vertical datum information is introduced by the keyword VERTCS. I removed this entire part of the projection file and it worked.

But before it worked, I encountered another hitch. It's in that dialog "Spatial Reference Projection File." If you browse for a file and choose the same one you had before, the app does not read the file again. In other words, it doesn't refresh. I had to select a different projection file, choose OK, then go back and choose my edited projection file, and choose OK. For many minutes I was mystified why my edits to the file were not taking. I was making edits to the projection file in a text editor, then switching over to RAS Mapper and attempting to have it read the file again.

So if you get this error message even though you think you're giving RAS Mapper a valid projection file, try what I did."