r.null

Manages NULL-values of given raster map.

Command linePython (grass.script)

r.null [-fincrz] map=name [setnull=val[-val] [,val[-val],...]] [null=float] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.null map=name

grass.script.run_command("r.null", map, setnull=None, null=None, flags=None, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.null", map="name")

Parameters

Command linePython (grass.script)

map=name [required]
    Name of raster map for which to edit null values
setnull=val[-val] [,val[-val],...]
    List of cell values to be set to NULL
null=float
    The value to replace the null value by
-f
    Only do the work if the map is floating-point
-i
    Only do the work if the map is integer
-n
    Only do the work if the map doesn't have a NULL-value bitmap file
-c
    Create NULL-value bitmap file validating all data cells
-r
    Remove NULL-value bitmap file
-z
    Re-create NULL-value bitmap file (to compress or uncompress)
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

map : str, required
    Name of raster map for which to edit null values
    Used as: input, raster, name
setnull : str | list[str], optional
    List of cell values to be set to NULL
    Used as: val[-val]
null : float, optional
    The value to replace the null value by
flags : str, optional
    Allowed values: f, i, n, c, r, z
    f
        Only do the work if the map is floating-point
    i
        Only do the work if the map is integer
    n
        Only do the work if the map doesn't have a NULL-value bitmap file
    c
        Create NULL-value bitmap file validating all data cells
    r
        Remove NULL-value bitmap file
    z
        Re-create NULL-value bitmap file (to compress or uncompress)
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

The function of r.null is to explicitly create the NULL-value bitmap file. The intended usage is to update maps that do not have a NULL-value bitmap file (i.e. to indicate for each pixel if zero is a valid value or is to be considered as NULL, i.e. no data value). The module does not work with reclassified or external maps.

The design is flexible. Ranges of values can be set to NULL and/or the NULL value can be eliminated and replace with a specified value.

The setnull parameter is used to specify values in the ranges to be set to NULL. A range is either a single value (e.g., 5.3), or a pair of values (e.g., 4.76-34.56). Existing NULL-values are left NULL, unless the null argument is requested.

The null parameter eliminates the NULL value and replaces it with value. This argument is applied only to existing NULL values, and not to the NULLs created by the setnull argument.

NOTES

Note that the value is restricted to integer if the map is an integer map.

r.null and reclassified maps

r.null does not support reclassified maps because, if r.null was run on the reclass raster it would alter the original and any other reclass rasters of the original. Therefore r.null does not allow recoding reclassified maps (products of r.reclass).
As a workaround, the way to recode such a map is: The user creates a raster map out of the reclassified map by copying it:

r.mapcalc "newmap = reclass"

NULL data compression

By default no data files (i.e., NULL files) are not compressed unless a specific environment variable is set. The NULL file compression must be explicitly turned on with export GRASS_COMPRESS_NULLS=1.
Warning: such raster maps can then only be opened with GRASS GIS 7.2.0 or later. NULL file compression can be managed with r.null -z.

External maps

From the r.external documentation: GDAL-linked (r.external) maps do not have or use a NULL bitmap, hence r.null cannot manipulate them directly. Here NULL cells are those whose value matches the value reported by the GDALGetRasterNoDataValue() function. To introduce additional NULL values to a computation based on a GDAL-linked raster, the user needs to either create a mask with with r.mask and then "apply" it using e.g. r.resample or r.mapcalc, or use r.mapcalc to create a copy with the appropriate categories changed to NULL (if() condition).

EXAMPLES

Set specific values of a classified map to NULL:

r.null map=landcover.30m setnull=21,22

Set NULL-values of a map to a specific value:

r.null map=fields null=99

AUTHOR

U.S.Army Construction Engineering Research Laboratory

SOURCE CODE

Available at: r.null source code (history)
Latest change: Friday Mar 07 10:39:45 2025 in commit 4b9d1a2