r.random(1grass)

📦
version 8.5.0 · 10 versions
, in alpine 3.24, ubuntu stonking

💖 r.random — the manual page, but make it make sense 💖

ok bestie, welcome to r.random(1grass) ✨ this is the GRASS tool that drops random cells and random points like confetti, except the confetti is scientifically valid 🎀

🌈 NAME 🌈

r.random — creates randomly placed raster cells or vector points. Like, it makes a raster map and a vector point map full of randomly located cells and points. both. at once. slay 💅

👑 KEYWORDS 👑

raster, sampling, vector, random, level1

🦋 SYNOPSIS 🦋

r.random
r.random --help
r.random [-snzb] input=name  [cover=name]  npoints=number[%]
[raster=name]   [vector=name]   [seed=integer]   [--overwrite]  [--help]
[--verbose]  [--quiet]  [--ui]

✨ OPTIONS ✨

🎀 Flags

  • -s — generate a random seed. heads up bestie: the result is non-deterministic, so no two runs will match 🙈
  • -n — generate points for NULL cells too. yes, even the empty ones, we love inclusivity 💖
  • -z — generate vector points as 3D points. the input raster values get used for Z coordinates, it's giving elevation energy ⛰️
  • -b — do not build topology. and specifically: do not build topology for vector points. saves resources, iconic 🌸
  • --overwrite — lets output files overwrite existing files. permission to be a little destructive 🫶
  • --help — prints the usage summary. your bestie when you're lost 😭
  • --verbose — verbose module output. it will not stop talking and honestly? valid 💅
  • --quiet — quiet module output. the shut-up button, we love her 🤫
  • --ui — force launching the GUI dialog. for when you want buttons instead of typing 🎀

🌸 Parameters

  • input=name [required] — name of the input raster map. this is the one you literally cannot skip.
  • cover=name — name of a cover raster map. optional cover, optional drama ✨
  • npoints=number[%] [required] — the number of points (or cells) to generate. also required! it's the number of vector points or raster cells to generate, and it can be a percentage of the number of cells. so like 10 or 10%, both valid 💜
  • raster=name — name for the output raster map.
  • vector=name — name for the output vector map.
  • seed=integer — seed value for the random number generator. using the same seed = identical results every time, while a randomly generated seed = different outcome every run. pick your fighter 🔥

💜 DESCRIPTION 💜

So r.random creates a raster map with values in random places. OR, if you'd rather, it creates random vector points at those same places. choose your own adventure fr fr 🦋

The number of random cells or points can be a fixed number, OR a percentage of the cells from the input. Default behavior: the generated cells or points are a subset of the non-NULL cells of the input. And the resulting raster map? It consists of the original cell values at the selected random locations, and NULL (no data) values everywhere else. so it's mostly vibes and emptiness with a few little treasures scattered in 💎

🧚 Placement of cells and points

The module lets you create a raster map and/or a vector points map containing coordinates of points whose locations have been randomly determined. It places these randomly generated vector points within the current computational region and raster mask (if any), on non-NULL raster cells in a user-specified raster map.

If you set the -n flag, points get randomly generated across all cells — yes, even the ones with NULL values. no cell left behind 💖

Cells in the resulting raster overlap with the cells of the input raster based on the current computational region. And the points in the resulting vector map? They're placed in the cell centers of these cells. dead center. main character positioning 💅

🍓 Number of cells and points

You can specify how many random locations to generate either as:

  • a positive integer (e.g. 10), or
  • a percentage of the raster map's cells (e.g. 10%, or 3.05%)

The number of cells considered for the percentage reflects whether or not the -n flag was given. Options are 0-100; and fractions of a percent are totally allowed as decimals (e.g. 66.67%, or 0.05%). yes bestie, go precise 🎯

⭐ Values

The cell values — and corresponding category names, if present — associated with the random point locations in the input map get assigned to the newly generated cells in the raster map.

If -n is specified, then a unique entry is made for the value used where the input was NULL. This value is at least 1 less than the smallest value in the input raster, and it's given a medium gray color. 🩶

If a cover raster map is specified, values are taken from the cover raster map instead of the input raster map. And if a cover raster map is specified and the cover map contains NULL (no data) values, those points are suppressed in the resulting vector or raster map. gone. not invited to the party 🙈

👑 Vector output

The vector file created by r.random contains vector points that represent the center points of the randomly generated cells.

A value attribute contains the cell value of the input raster (or the assigned value when -n is used). If a cover map is additionally specified, a second column covervalue is populated with raster values from the cover map. two columns, double the lore 💖

If you set the -b flag, vector points are written without topology to minimize the required resources. This is suitable input to v.surf.rst and other vector modules. efficient queen ✨

🔥 NOTES 🔥

To decide on the number of points r.random will create, use r.univar, g.region, or r.report.

r.univar is the fastest way to obtain the number of non-NULL cells and NULL cells in a raster map, given the current computational region and raster mask:

r.univar map=inputmap

The text output contains the total number of null and non-null cells (called cells in the machine-readable shell script style output), total null cells (null_cells), and number of non-null cells (n). 📊

Alternatively, you can use the following to examine the computational region AND the raster map:

g.region -p
r.report map=inputmap units=c null="*" nsteps=1

To create random vector point locations within some, but not all, categories of an integer input raster map (aka a CELL raster map), you must first create a reclassified raster map of the original raster map (e.g., using the GRASS module r.reclass) that contains only the desired categories, and then use that reclassed raster map as the input to r.random. You cannot skip this step, bestie, it's the law 😤

🌈 EXAMPLES 🌈

💜 Random 2D vector elevation points

Random vector elevation points sampled from an elevation map in the North Carolina sample dataset region, result stored in a 2D vector map:

g.region raster=elevation -p
r.random elevation vector=elevrand n=100
v.db.select elevrand
v.univar elevrand col=value type=point

💜 Random 3D vector elevation points

Random vector elevation points sampled from an elevation map in the North Carolina sample dataset region, with collocated values sampled from a landuse map, result stored in a 3D vector map:

g.region raster=elevation -p
r.random -z elevation cover=landclass96 vector=luserand3d n=100
# data output (value: elevation, covervalue: landuse class):
v.db.select luserand3d
cat|value|covervalue
1|111.229591|5
2|71.093758|1
3|122.51075|5
4|146.17395|4
...

look at those numbers. look at that covervalue column. we ate 🍽️🔥

🫶 SEE ALSO 🫶

  • g.region — for setting the computational region and examining the total number of cells
  • r.reclass — for working only with a subset of values in the raster map
  • v.random — for generating vector points without any involvement of raster data
  • r.random.cells — for generating random cells with spatial dependence (minimal distance)
  • r.surf.random — as an option for generating random cell values
  • v.surf.rst — as an option for creating a surface from sampled points

all of these are besties of r.random, go say hi 💖

💅 AUTHORS 💅

  • Dr. James Hinthorne, GIS Laboratory, Central Washington University
  • Modified for GRASS 5.0 by Eric G. Miller
  • Cover map support by Markus Neteler, 2007

legends, all of them 👑

⭐ SOURCE CODE ⭐

Available at: r.random source code (history)

Latest change: Saturday Oct 25 22:50:58 2025, in commit ee87f21833475fd40805f58d1702f7d64478a27b

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

ok that's the whole page, you're officially educated ✨ and a lil sign-off for the road: this doc? © 2003-2026 GRASS Development Team, straight out of the GRASS 8.5.0 Reference Manual — and it was generated on GRASS 8.5.0. mwah, go run it bestie 🎀💖🦋

📦 where this page comes from