Pages

Thursday, May 14, 2015

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”.

image

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. 

image

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/

image










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:

image

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.

image

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!

image


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

image

image

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."  

27 comments:

  1. I saw your post on projections on your blog and thought it might be good to mention that you can convert the coordinate system of the model in HEC-RAS now.

    ReplyDelete
  2. HEC-RAS supports esri's WKT format of the PRJ. Using other WKT formats is YMMV.

    ReplyDelete
    Replies
    1. Thanks for the head's up. I believe all of the prj files on spatialreference.org follow the format used by HEC-RAS (at least the ones I've checked), except (ironically) the 447 ESRI references. They only have the GEOGCS clause, none of the others.

      Delete
  3. HEC-RAS currently supports esri's WKT format. Other WKT formats are YMMV.

    ReplyDelete
  4. Hi

    Can I load own link WMS in the RasMapper?

    Because, my model is created in the S-JTSK / Krovak East North and bacgkround/WMS (ortophoto,satellite image) in the WGS-84. When I load a bacgkround, so my model is displaced out- this error is predictable.

    Best Regards!

    Robert


    ReplyDelete
    Replies
    1. The projection that your model was created in and the projection you load in RAS Mapper must be the same.

      Delete
    2. Chris confirmed my idea:
      When you work the other coordinate projections as WGS84, so you can´t use the WMS imagery servers (RasMapper- Tools). Nowday, RasMapper doesn´t support to join the other WMS.
      You have to solve a background using static image (georeferenced image)

      I hope, that I write it well, Chris!

      Best regards
      Robert

      Delete
    3. Robert. I think I understand your question better (with the help of Cameron at HEC). If you go to the HEC-RAS project directory, you will see a folder called GDAL. In there, you'll see a folder called Web Map Services. There you will see an xml file for every web imagery service available in HEC-RAS. If you would like to add more web imagery services, you can create your own xml and put it in this directory. It should then show up in the Web Imagery Window in HEC-RAS. If you are able to do this with your own web imagery, please forward the xml to me so we can share with others.

      Delete
  5. With ArcGIS 10.1+ simply add a projection to your favorite list and it will create and place a projection file at:
    C:\Users\"UserName"\AppData\Roaming\ESRI\Desktop10.2\ArcMap\Coordinate Systems

    ReplyDelete
  6. I'm very sorry for any cryptic parts of this message, but after some hours of investigating why the Hungarian EOV (Unified National Projection) is not projected correctly in RAS Mapper, I'd discovered that all information to do this correctly is available in the GDAL library that RAS Mapper uses.

    The erroneous projection might originally be caused by an error in a parameter value in the info source, but that has been long corrected and the correction is part of the GDAL library file 'datum_shift.csv'.

    There are actually 5 (!) datum shift parameterizations listed in this file ("SEQ_KEY" 350 to "SEQ_KEY" 354) and any of these would be much more accurately shift from HD72 to WGS 84 then the current implementation.

    So, Is the GDAL library only partly implemented? Or is there a bug that prevents RAS Mapper from applying the preferred datum shift defined in the GDAL library file 'datum_shift.csv'?

    ReplyDelete
    Replies
    1. Gerrit- thanks for the information. I'm not sure what the issue could be. I'll point some others to your question to see if we can get a good response.

      Delete
  7. Hi Chris, thanks for this post. I'm having a problem with my geometry being offset from the WMS river/terrain (see link below). I've found a workaround by manually editing the .prj file, but will this affect the projection of the 2D model e.g. flood maps?

    http://hec-ras-help.1091112.n5.nabble.com/Problem-with-misaligned-spatial-projection-prj-British-National-Grid-tt3753.html

    ReplyDelete
    Replies
    1. Hi Mike. That's a good question. I'm not sure how it will work. My gut instinct says it should work fine, but I think this is just one of those things you have to try out to know for sure. Let me know how it goes.
      Chris

      Delete
  8. Hello,

    Is the projection file only significant for RAS-Mapper, or geometry as well? I inherited a RAS model that is supposed to be working, they even sent over final run results. I am not able to run it because of a geometry error - it seems some river reaches are not lined up correctly to their associated cross sections. Also some weirs fall below the terrain elevation. I believe these issues might be because of a lack of projection file.

    ReplyDelete
    Replies
    1. It sounds like errors in the geometry setup. Should have nothing to do with the projection.

      Delete
  9. I have a project where RAS Mapper was displaying the map just fine using a UTM Zone 15 NAD83 (meters) projection file, but when I converted the project from meters to feet using Options->Convert Project Units, the map no longer worked. How do I change my projection file for the new project so it'll display the project in the right place? Or would it make more sense download a new projection file based on the unit conversion? And if so what would that new horizontal datum be?

    ReplyDelete
    Replies
    1. You'll have to get a new projection file (or create your own) that has the correct unit system.

      Delete
    2. The thing is that the projection is still UTM Zone 15 NAD83 (meters), but it's just been converted to feet now.

      This is how the coordinates changed after the unit conversion at a specific point where a cross section intersects with the river reach:

      (Originally) Meters: 451305.5383, 4625115.6106
      (After conversion) Feet: 1480661.2147, 15174263.8183

      Here's the shape projection file I was using before I did the conversion:

      PROJCS["NAD_1983_UTM_Zone_15N",GEOGCS["GCS_North_American_1983",DATUM["D_North_American_1983",SPHEROID["GRS_1980",6378137,298.257222101]],PRIMEM["Greenwich",0],UNIT["Degree",0.017453292519943295]],PROJECTION["Transverse_Mercator"],PARAMETER["latitude_of_origin",0],PARAMETER["central_meridian",-93],PARAMETER["scale_factor",0.9996],PARAMETER["false_easting",500000],PARAMETER["false_northing",0],UNIT["Meter",1]]

      How should this be modified to make it so my project doesn't end up in the middle of the Arctic Ocean after the unit conversion? I've tried modifying the UNIT["Meter",1]] to say UNIT["Feet",3.28084]] but that doesn't seem to fix the problem.

      Delete
  10. I've been trying to resolve a mysterious horizontal datum shift that RAS does for quite some time. I export a surface from Civil 3D using CA State Plane Zone 1, US Feet, EPSG 2225. For my latest work-around test, I made a projection file for RAS that has the exact same projection data as the Civil 3D tif. It says "Same As Project" when I make a new terrain. Then when I open the geometry editor and look at the coordinates of a landmark, it's off by about 12 feet in the easting direction and a few in the northing. The shift is NOT there when i bring the tif into GIS, so it doesn't seem that it's a problem with Civil 3D export. I'm stumped! Any ideas? It's problematic because all the RAS results rasters are then shifted and don't line up.

    ReplyDelete
  11. Actually, that worked! RAS users who work with Civil 3D may need to ensure that the SRS is "Same As Project" in order to avoid having a mystery shift occur. But as long as they're exactly the same, they should be good to go.

    ReplyDelete
  12. Hello, I need your help. I can not make the prj file work from: "http://spatialreference.org/". I need for "EPSG: 22174: POSGAR 98 / Argentina 4"
    I can not find the error. Thank you very much.

    PROJCS["Gauss-Kruger",GEOGCS["Campo Inchauspe",DATUM["D_Campo_Inchauspe",SPHEROID["International_1924",6378388,297.000745017694]],PRIMEM["Greenwich",0],UNIT["Degree",0.017453292519943295]],PROJECTION["Gauss-Kruger"],PARAMETER["False_Easting",4500000],PARAMETER["False_Northing",0],PARAMETER["Central_Meridian",-63],PARAMETER["Scale_Factor",1.0],PARAMETER["Latitude_of_Origin",-90],UNIT["Meter",1]]

    ReplyDelete
  13. HEC-RAS project is setup as follows:

    • Units: US customary
    • LiDAR dataset
    o State plane projection
    o Horizontal units = international feet
    • Projection used in RAS Mapper
    o State plane projection
    o Horizontal units = meters

    Aerial imagery lines up correctly. But, when the measure tool is used in RAS Mapper, it gives distances in feet but the measurement indicates it should be meters. For example, a distance that measures 10 feet with the measure tool is actually 10/0.30458 = 32.8 feet. Will this model produce correct results or is the landscape through which the flow is routed basically shrunken by a factor of 3.28 (1/0.3048)?

    ReplyDelete
    Replies
    1. I think that’s just a bug and you’re okay. But make sure to double check.

      Delete
  14. 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.

    ReplyDelete
    Replies
    1. This is good information Dudley, so I'm copying this up to the post itself.

      Delete

Note: Only a member of this blog may post a comment.