r.fill.dir(1grass)

✨ r.fill.dir ✨ (the GRASS manual page, but make it make sense bestie)

okay so bestie, welcome to the r.fill.dir page, coming at you from the GRASS User's Manual. This is the one that fixes your sad holey elevation rasters and hands you a flow direction map like a little gift 🎁. Buckle up, it's giving hydrology but make it cute.

KEYWORDS: raster, hydrology, sink, fill sinks, depressions

---

🌸 SYNOPSIS 🌸

r.fill.dir
r.fill.dir --help
r.fill.dir [-f] input=name output=name direction=name  [areas=name]
[format=string]   [--overwrite]  [--help]  [--verbose]  [--quiet]
[--ui]

🎀 Flags

• -f — only go find the unresolved areas, bestie. Don't fix them.
• --overwrite — let the output files bulldoze whatever's already sitting there. existing files say bye 💀
• --help — prints the usage summary, iykyk
• --verbose — the module gets chatty and tells you everything
• --quiet — shhh 🤫 module output goes silent
• --ui — forced to launch the GUI dialog, no takebacks

🦋 Parameters

• input=name [required] — the name of your input elevation raster map
• output=name [required] — name for the output depressionless elevation raster map
• direction=name [required] — name for the output flow direction map that goes with the depressionless elevation raster map
• areas=name — name for the output raster map of problem areas
• format=string — the aspect direction format
  • Options: agnps, answers, grass
  • Default: grass

---

💖 DESCRIPTION 💖

r.fill.dir filters stuff and generates a depressionless elevation map plus a flow direction map from whatever elevation raster you hand it. The whole filter-and-rectify method is based on the paper called "Extracting topographic structure from digital elevation model data for geographic information system analysis" by S.K. Jenson and J.O. Domingue (1988). iconic academic behavior 📚

So here's the tea on how it works: it takes your elevation layer as input and first fills all the depressions in one pass across the whole layer. Then the flow direction algorithm tries to find one single unique direction for every cell. If the watershed program spots areas with pothholes, it draws a line around that area to separate it from everything else, and then the depressions get filled again using the neighborhood technique that the flow direction routine uses. Final output? A depressionless elevation layer and a unique flow direction layer. slay ✨

The (D8) flow algorithm does this thing: at every raster cell the code figures out the slope to each of the 8 surrounding cells and assigns the flow direction to the steepest slope out of the cell. If there's more than one equal, non-zero slope, the code just picks one based on preferences that are hard-coded into the program (we don't make the rules bestie). And if the highest slope is flat and in more than one direction, the code first tries to pick an alternative based on flow directions in the adjacent cells. r.fill.dir iterates that whole process, which effectively propagates flow directions from areas where the directions are known into the area where the flow direction can't be resolved any other way. main character energy honestly 👑

The format parameter is the type of format you want your flow direction map in. Your flow direction map can be encoded in GRASS aspect format, ANSWERS (Beasley et.al, 1982), or AGNPS (Young et.al, 1985) format, so you can readily feed it to other GRASS modules or to the hydrological models mentioned above. Let's break it down:

• The grass format gives the same category values as r.slope.aspect gives for aspect, i.e. angles in degrees counter-clockwise from east in 45 degree increments.
• The agnps format gives category values from 1-8, with 1 facing north and increasing values in the clockwise direction.
• The answers format gives category values from 0-360 degrees, with 0 (represented as 360) facing east and values increasing in the counter-clockwise direction at 45 degree increments.

In all of those cases, NULL (no data) values are used for cells where the direction can't be determined. no cap.

In case of local problems, those unfilled areas can be stored optionally. Each unfilled area in this map is numbered. The -f flag tells the program to fill single-cell pits but otherwise to just find the undrained areas and exit. With the -f flag set, the program writes an elevation map with just single-cell pits filled, a direction map with unresolved problems, and a map of the undrained areas that were found but not filled. Why does this option exist? Because filling DEMs was often not the best way to solve a drainage problem. These options let you get a partially-fixed elevation map, identify the remaining problems, and fix the problems appropriately. 🫶

In some cases it may be necessary to run r.fill.dir repeatedly (using output from one run as input to the next run) before all of the problem areas are filled. Yes, like a loop. she's persistent.

The resulting depressionless elevation raster map can further be processed to derive slopes and other attributes required by other hydrological models.

And bestie, as any GRASS module, r.fill.dir respects the computational region settings. So you can use this module to generate a flow direction map for any sub-area within the full raster map layer. Also, r.fill.dir will take into account an active raster mask. 👑

---

🧚 NOTES 🧚

• The r.fill.dir module can be used not only to fill depression, but also to detect water bodies or potential water bodies based on the nature of the terrain and the digital elevation model used.
• Not all depressions are errors in digital elevation models. In fact, many are wetlands, and as Jenkins and McCauley (2006) note, careless use of depression filling may lead to unintended consequences such as loss of wetlands. so like, be careful 💀
• Although many hydrological algorithms require depression filling, advanced algorithms such as those implemented in r.watershed and r.sim.water do not require a depressionless digital elevation model to work.
• The flow direction map can be visualized with d.rast.arrow. cute!

---

🌈 EXAMPLES 🌈

Generic example: create a depressionless (sinkless) elevation map ansi.fill.elev and a flow direction map ansi.asp for the type "grass":

r.fill.dir input=ansi.elev output=ansi.fill.elev direction=ansi.asp

North Carolina sample dataset example: The LiDAR derived 1m elevation map is sink-filled. The outcome are a depressionless elevation map, the flow direction map and an error map.

# set computational region to elevation map
g.region raster=elev_lid792_1m -p
# generate depressionless DEM and related maps
r.fill.dir input=elev_lid792_1m output=elev_lid792_1m_filled \
           direction=elev_lid792_1m_dir areas=elev_lid792_1m_error
# generate elevation map of pixelwise differences to see obtained terrain alterations
r.mapcalc "elev_lid792_1m_diff = elev_lid792_1m_filled - elev_lid792_1m"
r.colors elev_lid792_1m_diff color=differences
# assess univariate statistics of differences
r.univar -e elev_lid792_1m_diff
# vectorize filled areas (here all fills are of positive value, see r.univar output)
r.mapcalc "elev_lid792_1m_fill_area = if(elev_lid792_1m_diff > 0.0, 1, null() )"
r.to.vect input=elev_lid792_1m_fill_area output=elev_lid792_1m_fill_area type=area
# generate shaded terrain for better visibility of results
r.relief input=elev_lid792_1m_filled output=elev_lid792_1m_filled_shade
d.mon wx0
d.shade shade=elev_lid792_1m_filled_shade color=elev_lid792_1m_filled
d.vect elev_lid792_1m_fill_area type=boundary color=red

Figure: Sink-filled DEM (shown as shaded terrain) with areas of filling shown as vector polygons 🗺️

---

📚 REFERENCES 📚

• Beasley, D.B. and L.F. Huggins. 1982. ANSWERS (areal nonpoint source watershed environmental response simulation): User’s manual. U.S. EPA-905/9-82-001, Chicago, IL, 54 p.
• Jenkins, D. G., and McCauley, L. A. 2006. GIS, SINKS, FILL, and disappearing wetlands: unintended consequences in algorithm development and use. In Proceedings of the 2006 ACM symposium on applied computing (pp. 277-282).
• Jenson, S.K., and J.O. Domingue. 1988. Extracting topographic structure from digital elevation model data for geographic information system analysis. Photogram. Engr. and Remote Sens. 54: 1593-1600.
• Young, R.A., C.A. Onstad, D.D. Bosch and W.P. Anderson. 1985. Agricultural nonpoint surface pollution models (AGNPS) I and II model documentation. St. Paul: Minn. Pollution control Agency and Washington D.C., USDA-Agricultural Research Service.

---

👀 SEE ALSO 👀

d.rast.arrow, d.shade, g.region, r.fillnulls, r.relief, r.slope.aspect

---

💅 AUTHORS 💅

• Fortran version: Raghavan Srinivasan, Agricultural Engineering Department, Purdue University
• Rewrite to C with enhancements: Roger S. Miller

---

🔥 SOURCE CODE 🔥

Available at: r.fill.dir source code (history)

Latest change: Friday Apr 17 01:04:26 2026 in commit: 32a143358df26b2e518b03c7e0d79541e8d1e5b1

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

---

and that's the whole page bestie!! your girl r.fill.dir is out here at GRASS 8.5.0, from the GRASS 8.5.0 Reference Manual, brought to you by the certified icons at © 2003-2026 GRASS Development Team. go fill some sinks, hydrate, and remember that not every depression is a bug 🫶✨💖