HMS Pre Pro User Guide
Open the PDF directly: View PDF .
Page Count: 11
Prepared By: Cynthia V. Castro
HMS-PrePro contains ArcGIS geoprocessing script tools for extracting data from Esri's Living Atlas,
deriving a watershed network, estimating hydrological parameters, and storing results in a .BASIN
output ASCII file that may be used as input for the HEC-HMS watershed modeling software.
Installation / Set-Up
1) Copy or unzip the HMS-PREPRO folder to any location on your hard drive
2) Ensure you have 64-bit geoprocessing capabilities by looking for a folder containing ArcGISx64
in C:\Python27. If you do not see this folder, contact your system administrator for installation.
Running HMS-PrePro without the 64-bit background geoprocessing may cause failures or a
notably longer execution time.
Enable background geoprocessing (64-bit) by clicking the Geoprocessing tab from the ArcMap
toolbar and selecting the Enable box under Background Processing. Click OK.
Page 2 of 11
3) Enable the 3D Analyst and Spatial Analyst extensions by selecting the Customize tab from the
ArcMap toolbar and choosing Extensions. Select the box next to 3D Analyst and Spatial Analyst.
4) Ensure ArcHydro is installed. In ArcMap you will see this toolbar:
a. If not, download and install the appropriate version of Arc Hydro tools here:
b. If you have a 64-bit computer, use the “x64” version for faster background processing.
5) The use of Esri Living Atlas landscape layers requires an ArcGIS Online organizational account.
This is different than an ArcGIS Online personal or global account. You may have been invited to
become a member of an ArcGIS organizational account through your university or workplace. If
so, it is recommended to use the login credentials registered with that organization when using
HMS-PrePro. Contact your organization’s administrator for access.
If you have not been invited to join an existing organizational account, you may create a
temporary one by signing up for the developer trial here:
d. NOTE: Access to the landscape layers within the Living Atlas is free and does not
consume any of your organizational credits/tokens.
** Prior to running HMS-PrePro, ensure that you are logged into your organizational account in
ArcMap by selecting File >> Sign In…
Page 3 of 11
Open ArcCatalog within ArcMap
Navigate to the installation directory in ArcCatalog and expand the HMS-PrePro folder.
Double-click on the script tool to run.
Or, using ArcToolbox:
Open ArcToolbox within ArcMap
Right-click the ArcToolbox folder and select Add Toolbox.
Navigate to the HMS-PREPRO directory and select the HMS-PrePro.tbx. Click Open.
Page 4 of 11
Using the HMS-PrePro GetData Tool
1) Double-click on the GetData script
NOTE: If you encounter an error, first try closing out of ArcMap and re-opening a blank project.
2) ArcGIS Username / ArcGIS Password
a. Input your ArcGIS organizational username and password.
3) Output Geodatabase
a. Create an empty geodatabase and navigate to that directory. This is where the output
layers will be saved. (NOTE: It is possible to create an empty geodatabase within the
tool by selecting the New File Geodatabase icon, as shown below.)
After selecting New File Geodatabase, rename the New File Geodatabase.gdb and
select the icon only once to add the .gdb to the Name field. Select Add.
Page 5 of 11
4) Watershed Boundary
a. Navigate to the watershed boundary layer. This layer may be a shapefile (.shp) or a
feature class within a geodatabase.
b. If you do not have a watershed boundary layer, you may create one for an area of
interest using the ArcGIS Watershed service tool (not part of this tutorial).
For more information about using the Watershed tool, visit:
c. NOTE: Do not select a watershed that is too large for your computer RAM and/or
internet connectivity speeds.
d. The watershed boundary may not be edited after execution of HMS-PrePro (without
having to re-calculate all sub-catchments, reaches, junctions, and catchment
parameters). Initial selection of the intended watershed boundary is very important.
e. Ensure that your watershed contains a projected coordinate system prior to execution.
5) Output Coordinates
a. Select the desired output coordinate system.
i. For hydrological purposes, ensure the output coordinate system preserves
spatial area. Examples include the Albers Equal Area Conic projection or the
State Plane systems.
ii. For use with the HMS-PrePro processing script, a Projected Coordinate System
must be selected.
iii. NOTE: The projected coordinate system only applies to the Subbasin and Reach
layers. The landscape rasters (soils, land use, impervious, and DEM) will remain
in the North America Albers Equal Area Conic projection for spatial analysis.
Page 6 of 11
Select the Use ArcHydro option if you wish to derive the stream network (subbasins, reaches,
nodes) from a DEM using ArcHydro tools instead of the NHDPlusV2.1 catchments and flowlines.
HMS-PrePro will use the stream threshold to delineate the watershed from a DEM.
Provide a Stream Threshold based on the number of DEM cells that you wish to define the
stream. The default value is 1000. Smaller stream thresholds will produce more drainage units.
After execution of the GetData script, carefully analyze the size of your catchments and reaches.
If these are too large or small, re-run the script and adjust the “Stream Threshold” value.
Manual editing of catchments/reaches/junctions prior to running the next script is technically
possible, however, if any of the Fields are edited (i.e. Name/HydroID, To_Node, From_Node,
NextDownID, NodeID) and the topology does not match perfectly, HMS-PrePro will be unable to
run the parameterization script. Manual editing of the basin catchments after running ArcHydro
is very typical for land-development projects, because the Node of interest typically lies at a
specific location. Care should be executed in updating the Watershed topology connections if
manual edits are desired.
The Esri Living Atlas may be used to obtain a 30-meter DEM, which is standard across the United
States, or a high-resolution DEM, which is a composite of the best publicly-available DEM in the
country. The high-resolution DEM will contain at minimum a 10-meter value from the National
Elevation Dataset. More information is available here:
By selecting the NED DEM 10m, a high-resolution DEM will be extracted that contains elevation
values (10-meter to 3-meter resolution) from the National Elevation Dataset. In some locations,
Page 7 of 11
FEMA LiDAR data is available. A coverage map is available here:
NOTE: By selecting the NED DEM 10m option, download and processing times will be notably
slower when compared to the NED DEM 30m.
You may also provide your own DEM raster to be used in the HMS-PrePro tool (i.e. LiDAR).
When this option is selected, no DEM data will be downloaded from the Living Atlas. If this
option is selected, ensure that proper Raster Mosaicing has been done and that the raster is in a
proper coordinate system.
Click OK to run Get Data.
You will see a dialog box describing the current processing steps and a status bar. Do not close
this box until you see “Completed” at the top.
Once the script has completed, you may navigate to the output folder directory to view the
hydrological geodatabase with landscape layers, subbasins, and reaches. Each of these layers
may be added to ArcMap for viewing. If you used ArcHydro, the longest flowpath layer will also
be available. If you used NHDPlusV2.1, you will have to extract the longest flowpath using
separate steps (outlined below).
Page 8 of 11
Longest Flowpath for NHDPlusV2.1: (not required when using the ArcHydro option)
Currently, the NHDPlusV2.1 longest flowpath layer is not included in the Esri Living Atlas. It is
anticipated that this layer will become available in future releases.
For now, you will need to extract this layer using the following steps:
a. Select the HUC-2 hydrological boundary for your area of interest here:
b. Download the FTP of the FdrFac file for your region. Austin is within the 12c region.
c. Extract this file to your computer. You may need 7-zip or winzip to open a .7z extension.
d. Project the Subbasin layer to the NAD_1983_Albers projection using the Project (Data
Management) tool. This projected layer will only be used to get the longest flowpath.
e. Open the Subbasin_proj layer and add a field called HydroID (Long Integer).
Populate this field with the Name column using Field Calculator.
Save the map before continuing.
f. Open ArcCatalog >> Toolboxes >> System Toolboxes >> ArcHydro Tools >> Watershed
Processing >> Longest Flow Path
g. Select the Subbasin_proj layer as the Input Drainage Area.
h. Select the fdr grid as the Input Flow Direction Grid.
i. Save the output in the “Get Data” geodatabase, and name the layer Longest.
j. Select OK.
Page 9 of 11
Using the Preprocess Basin Script
Double-click on the Preprocess Basin script
NOTE: If you encounter an error, first try closing out of ArcMap and re-opening a blank project.
Sometimes, background processing will crash if the layer being processed is open.
1) Select version of HEC-HMS.
2) Select the geodatabase created with the Get Data tool.
3) Select an output folder for the .BASIN HEC-HMS file.
4) Choose a name for the .BASIN file.
5) Select a time interval (whole number) for the HEC-HMS simulation.
6) Choose a Curve Number reduction factor (optional) according to observed/calibrated data.
7) You may choose to employ various Methodologies for basin losses and routing.
See HEC-HMS User’s Manual for more information.
8) Read the “Help” dialogue box for information regarding each Methodology and required input.
** This step is particularly important if you wish to execute the TR-55 Lag Time script. Follow
the user-steps listed under the “Help” screen, and then run the Optional “TR-55 Method” script
after fully executing the “Preprocess Basin” script and updating necessary parameters.
9) Select OK.
Page 10 of 11
Opening .BASIN File in HEC-HMS
Now that you have created a .BASIN file from the hydrological geodatabase, you may use this to
initialize a HEC-HMS model. Further calibration and engineering optimization is necessary to accurately
model the watershed response. These results should not be used for design or judgment purposes
without further analysis by a professional engineer.
1) Open HEC-HMS
Download available: http://www.hec.usace.army.mil/software/hec-hms/downloads.aspx
2) Create a New Project (File >> New…). Choose the U.S. Customary units.
3) Import the .BASIN file (File >> Import >> Basin Model).
Navigate to the directory where you saved the .BASIN file in the HMS-PrePro tool.
4) In the legend, open the Basin Models folder and select your basin. You may optimize the view
by selecting View >> Maximum Extents and changing the percentage value.
You may also import background images (i.e. subbasin, longest flowpath) by selecting View >>
Background Maps >> Add. When importing background images to HEC-HMS, the layer cannot
be contained in a geodatabase. You will need to export the data as a shapefile first.
5) To fully execute a HEC-HMS model, you will need to create a meteorological model, control
specifications, and a simulation run. Refer to the HEC-HMS manual for further information.
Page 11 of 11
For questions regarding this product, please contact:
Cynthia V. Castro
Please note that no requested coding updates will be conducted on this tool by the Author.
The current tool is compatible with ArcMap 10.6. If you wish to update the script codes for improved
performance or for future versions of ArcGIS/ArcPro/HEC-HMS/additional software, you must upload
the modified script back into GitHub for public use and contact the Author, per licensing agreement.