GradeIT

Road Grade Inference Tool — add elevation and road grade to GPS points.

GradeIT is a Python package from the National Laboratory of the Rockies. It takes GPS coordinates as input and returns the corresponding elevation and road grade. It gets elevation from the USGS Digital Elevation Model, filters the elevation profile, and calculates road grade. The typical and tested application for this is to add elevation and road grade information to vehicle telematics data.

from gradeit import gradeit

result = gradeit(trace)

result.grade_dec_filtered  # decimal road grade (rise/run), per point
result.elevation_ft_filtered  # cleaned elevation, feet
result.elevation_ft_unfiltered  # the raw DEM lookup, always preserved

The problem this solves

Vehicle telematics data might collect GPS elevation data but these signals are often noisy and unreliable for calculating accurate road grade.

To compensate for this, we can reference collected elevation data from a digital elevation model, but it comes with own challenges.

Namely, in GradeIT, we use a bare-earth digital elevation model. It shows the elevation of the ground, not the road surface, creating artifacts that need to be corrected.

GradeIT removes these artifacts and preserves the nearby terrain.

Take a look at the methodology for more details.

Where to go

If you want to…	Read
Install it	Installation
See the shortest path to a grade profile	Quickstart
Get elevation data on your machine	Elevation Data
Watch it work on a real trace	Your First Grade Profile
Understand what the filter does	How Filtration Works
Deal with bridges and overpasses	Bare-Earth Bridges
Plug in your own elevation source	Custom Elevation Sources
Look up a class or function	API Reference

Citation

If you use GradeIT in published work, please cite the software:

National Laboratory of the Rockies. GradeIT: Road Grade Inference Tool (version 0.2.0) [Computer software]. NatLabRockies/gradeit

@software{gradeit,
  title    = {{GradeIT}: Road Grade Inference Tool},
  author   = {{National Laboratory of the Rockies}},
  version  = {0.2.0},
  url      = {https://github.com/NatLabRockies/gradeit},
  license  = {BSD-3-Clause}
}

The repository also carries a CITATION.cff, which GitHub renders as "Cite this repository".