r3.what

Queries 3D raster in specified 2D or 3D coordinates.

r3.what [-mz] input=name [coordinates=east,north [,east,north,...]] [coordinates_3d=east,north,top [,east,north,top,...]] [points=name] [output=name] [separator=character] [null_value=string] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r3.what input=name coordinates=east,north

grass.script.run_command("r3.what", input, coordinates=None, coordinates_3d=None, points=None, output=None, separator="pipe", null_value="*", flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r3.what", input="name", coordinates=east,north)

Parameters

Command linePython (grass.script)

input=name [required]
    Input 3D raster map
coordinates=east,north [,east,north,...]
    Query with 2D coordinates
coordinates_3d=east,north,top [,east,north,top,...]
    Query with 3D coordinates
points=name
    Name of vector points map for query
    Or data source for direct OGR access
output=name
    Name for output file
separator=character
    Field separator
    Special characters: pipe, comma, space, tab, newline
    Default: pipe
null_value=string
    String representing NULL value
    Default: *
-m
    Use 3D raster mask (if exists) with input map
-z
    Ignore points Z values
--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

input : str, required
    Input 3D raster map
    Used as: input, raster_3d, name
coordinates : list[tuple[float, float]] | tuple[float, float] | list[float] | str, optional
    Query with 2D coordinates
    Used as: input, coords, east,north
coordinates_3d : list[tuple[float, float, float]] | tuple[float, float, float] | list[float] | str, optional
    Query with 3D coordinates
    Used as: input, coords, east,north,top
points : str, optional
    Name of vector points map for query
    Or data source for direct OGR access
    Used as: input, vector, name
output : str, optional
    Name for output file
    Used as: output, file, name
separator : str, optional
    Field separator
    Special characters: pipe, comma, space, tab, newline
    Used as: input, separator, character
    Default: pipe
null_value : str, optional
    String representing NULL value
    Used as: string
    Default: *
flags : str, optional
    Allowed values: m, z
    m
        Use 3D raster mask (if exists) with input map
    z
        Ignore points Z values
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
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

r3.what queries 3D raster at specified coordinates. The input parameter is a valid 3D raster map in the current mapset search path. The output parameter is used to output results in a text file. If output is not specified or '-' is used, then standard output (stdout) is used.

Coordinates can be specified directly using options coordinates as coordinate pairs (east, north), or using option coordinates_3d as east, north and top. If the coordinates are 2D, the result will be a list of values representing the vertical column of the 3D raster at that coordinates (from bottom to top). If 3D coordinates are provided only one value is returned. User can specify multiple coordinates.

Another option is to specify vector points map using option points. It can be either 2D or 3D. If a 3D vector points map is specified, one 3D raster value per point is printed. If that is not desired, flag z will ignore the z coordinate and the module returns values for the vertical column.

Example

We create a 3D raster where values depend on the depth. We query the 3D raster with two 2D coordinates:

g.region s=0 n=100 w=0 e=100 b=0 t=100 res3=1 res=1 tbres=10 -p3
r3.mapcalc "new = depth()"
r3.what input=new@user1 coordinates=10,20,50,50

10.000000|20.000000|1.000000|2.000000|3.000000|4.000000|5.000000|6.000000|7.000000|8.000000|9.000000|10.000000
50.000000|50.000000|1.000000|2.000000|3.000000|4.000000|5.000000|6.000000|7.000000|8.000000|9.000000|10.000000

Here we query the 3D raster with two 3D coordinates:

r3.what input=new@user1 coordinates_3d=10,10,1,10,10,11

10.000000|10.000000|1.000000|1.000000
10.000000|10.000000|11.000000|2.000000

AUTHOR

Anna Petrasova, NCSU GeoForAll Lab

SOURCE CODE

Available at: r3.what source code (history)
Latest change: Thursday Mar 20 21:36:57 2025 in commit 7286ecf