Skip to content

r.curvenumber

Generates the Curve Number raster from the landcover and hydrologic soil group rasters

r.curvenumber landcover=name soil=name landcover_source=string [lookup=name] [hydrologic_condition=string] [antecedent_runoff_condition=string] output=name [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.curvenumber landcover=name soil=name landcover_source=nlcd output=name

grass.script.run_command("r.curvenumber", landcover, soil, landcover_source, lookup=None, hydrologic_condition="fair", antecedent_runoff_condition="ii", output, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.run_command("r.curvenumber", landcover="name", soil="name", landcover_source="nlcd", output="name")

grass.tools.Tools.r_curvenumber(landcover, soil, landcover_source, lookup=None, hydrologic_condition="fair", antecedent_runoff_condition="ii", output, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.r_curvenumber(landcover="name", soil="name", landcover_source="nlcd", output="name")

This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.

Parameters

landcover=name [required]
    Landcover raster
soil=name [required]
    Hydrologic Soil Group raster
landcover_source=string [required]
    Lookup table source
    Allowed values: nlcd, esa, custom
lookup=name
    CSV with columns lc,hsg,hc,cn (required if source=custom)
hydrologic_condition=string
    Hydrologic condition (groundcover density affecting runoff potential)
    Allowed values: poor, fair, good
    Default: fair
    poor: increased runoff
    fair: normal runoff
    good: lower runoff
antecedent_runoff_condition=string
    Antecedent Runoff Condition (the degree of wetness of a watershed before a rainfall event)
    Allowed values: i, ii, iii
    Default: ii
    i: dry
    ii: average
    iii: wet
output=name [required]
    Curve number raster
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

landcover : str, required
    Landcover raster
    Used as: input, raster, name
soil : str, required
    Hydrologic Soil Group raster
    Used as: input, raster, name
landcover_source : str, required
    Lookup table source
    Allowed values: nlcd, esa, custom
lookup : str, optional
    CSV with columns lc,hsg,hc,cn (required if source=custom)
    Used as: input, file, name
hydrologic_condition : str, optional
    Hydrologic condition (groundcover density affecting runoff potential)
    Allowed values: poor, fair, good
    poor: increased runoff
    fair: normal runoff
    good: lower runoff
    Default: fair
antecedent_runoff_condition : str, optional
    Antecedent Runoff Condition (the degree of wetness of a watershed before a rainfall event)
    Allowed values: i, ii, iii
    i: dry
    ii: average
    iii: wet
    Default: ii
output : str, required
    Curve number raster
    Used as: output, raster, name
overwrite : bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

landcover : str | np.ndarray, required
    Landcover raster
    Used as: input, raster, name
soil : str | np.ndarray, required
    Hydrologic Soil Group raster
    Used as: input, raster, name
landcover_source : str, required
    Lookup table source
    Allowed values: nlcd, esa, custom
lookup : str | io.StringIO, optional
    CSV with columns lc,hsg,hc,cn (required if source=custom)
    Used as: input, file, name
hydrologic_condition : str, optional
    Hydrologic condition (groundcover density affecting runoff potential)
    Allowed values: poor, fair, good
    poor: increased runoff
    fair: normal runoff
    good: lower runoff
    Default: fair
antecedent_runoff_condition : str, optional
    Antecedent Runoff Condition (the degree of wetness of a watershed before a rainfall event)
    Allowed values: i, ii, iii
    i: dry
    ii: average
    iii: wet
    Default: ii
output : str | type(np.ndarray) | type(np.array) | type(gs.array.array), required
    Curve number raster
    Used as: output, raster, name
overwrite : bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

Returns:

result : grass.tools.support.ToolResult | np.ndarray | tuple[np.ndarray] | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned. If an array type (e.g., np.ndarray) is used for one of the raster outputs, the result will be an array and will have the shape corresponding to the computational region. If an array type is used for more than one raster output, the result will be a tuple of arrays.

DESCRIPTION

Generates a Curve Number (CN) raster using landcover and hydrologic soil group (HSG) rasters, along with user-specified hydrologic condition and antecedent runoff condition.

Landcover Source

Select the source of the landcover classification and corresponding lookup table:

  • nlcd: Built-in NLCD lookup
  • esa: Built-in ESA WorldCover 2021 lookup
  • custom: Custom lookup table provided as a CSV file

For custom, the CSV must include the following columns:
lc,hsg,hc,cn

Hydrologic Soil Groups (HSG)

The HSG raster must contain only:

  • 1 – Group A: High infiltration, low runoff
  • 2 – Group B: Moderate infiltration
  • 3 – Group C: Low infiltration
  • 4 – Group D: Very low infiltration, high runoff
  • 11–14 – Dual groups: A/D, B/D, C/D, D/D (for drained/undrained soils)

Curve Number increases from HSG A to D due to reduced infiltration associated with increasing clay content and compaction.

If you are using SSURGO soil data, Hydrologic Soil Group (HSG) values are typically provided directly. For other soil datasets that do not include HSG classifications, see Reference 1 (Chapter 7) for guidance on assigning HSGs based on soil texture, hydraulic conductivity, and water table depth. This information can be used to develop a custom HSG raster.

Hydrologic Condition (HC)

Hydrologic condition reflects the percentage of surface groundcover and affects runoff potential. Generally:

  • poor: Less than 30% cover — compacted or bare
  • fair: 30–70% cover — partial vegetation (default)
  • good: More than 70% cover — dense and healthy vegetation

Curve Number decreases from poor to good due to improved infiltration with more vegetation.
See Reference 2 for further discussion.

Note: Curve Number for Cropland for fair condition is provided as the average of Curve Number of poor and good hydrologic conditions.

Antecedent Runoff Condition (ARC)

The variability in Curve Number (CN) arises from factors such as rainfall intensity and duration, total precipitation, soil moisture conditions, vegetative cover density, growth stage, and temperature. These factors collectively define the Antecedent Runoff Condition (ARC), which is classified into three categories:

  • ARC I – Dry conditions (low antecedent moisture)
  • ARC II – Average conditions (typical or normal moisture, default)
  • ARC III – Wet conditions (high antecedent moisture)

Curve Number increases from ARC I to ARC III as runoff potential rises.

A standard conversion table is used within the script to adjust CN values from ARC II to ARC I or ARC III, based on empirical relationships. This corresponds to Table 10-1 in Reference 3.

Sensitivity and CN Hierarchy

The CN is more sensitive to ARC than to HC.
Typical curve number values for a soil-cover complex follow this order:

p_iii > f_iii > g_iii > p_ii > f_ii > g_ii > p_i > f_i > g_i

Where:

  • p, f, g denote poor, fair, and good hydrologic conditions
  • i, ii, iii denote dry, average, and wet antecedent runoff conditions

EXAMPLES

# Example 1: NLCD lookup (built-in)
r.curvenumber \
  landcover=nlcd \
  hsg=soil_hsg \
  landcover_source=nlcd \
  h_c=poor \
  arc=iii \
  output=cn_nlcd

# Example 2: ESA WorldCover lookup (built-in)
r.curvenumber \
  landcover=esa \
  hsg=soil_hsg \
  landcover_source=esa \
  h_c=fair \
  arc=ii \
  output=cn_esa

# Example 3: Custom CSV lookup
r.curvenumber \
  landcover=custom_lc_map \
  soil=custom_hsg_map \
  landcover_source=custom \
  lookup=cn_table.csv \
  output=cn_custom

r.curvenumber example Figure: Example output from r.curvenumber

REFERENCES

  1. United States Department of Agriculture, Natural Resources Conservation Service. (2009). National Engineering Handbook, Part 630 Hydrology: Chapter 7 – Hydrologic Soil Groups (210-VI-NEH)

  2. United States Department of Agriculture, Natural Resources Conservation Service. (2004). National Engineering Handbook, Part 630 Hydrology: Chapter 9 – Hydrologic Soil-Cover Complexes (210-VI-NEH)

  3. United States Department of Agriculture, Natural Resources Conservation Service. (2004). National Engineering Handbook, Part 630 Hydrology: Chapter 10 – Estimation of Direct Runoff from Storm Rainfall (210-VI-NEH)

AUTHOR

Abdullah Azzam, New Mexico State University

SOURCE CODE

Available at: r.curvenumber source code (history)
Latest change: Friday Jul 18 02:39:02 2025 in commit 0d77232