v.profile
Vector map profiling tool
v.profile [-cz] input=name [type=string [,string,...]] [where=sql_query] [layer=string] [output=string] [separator=character] [dp=integer] buffer=float [map_output=name] [coordinates=east,north [,east,north,...]] [profile_map=name] [profile_where=sql_query] [profile_layer=integer] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
v.profile input=name buffer=10
grass.script.run_command("v.profile", input, type="point,line", where=None, layer="1", output="-", separator="pipe", dp=2, buffer=10, map_output=None, coordinates=None, profile_map=None, profile_where=None, profile_layer=1, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)
Example:
gs.run_command("v.profile", input="name", buffer=10)
Parameters
input=name [required]
Name of input vector map
Or data source for direct OGR access
type=string [,string,...]
Input feature type
Allowed values: point, line
Default: point,line
where=sql_query
WHERE conditions of SQL statement without 'where' keyword
Example: income < 1000 and population >= 10000
layer=string
Layer number or name
Use features only from specified layer
Default: 1
output=string
Path to output text file or - for stdout
Default: -
separator=character
Field separator
Special characters: pipe, comma, space, tab, newline
Default: pipe
dp=integer
Number of significant digits
Allowed values: 0-32
Default: 2
buffer=float [required]
Buffer (tolerance) for points in map units
How far points can be from sampling line
Default: 10
map_output=name
Name for profile line and buffer output map
Profile line and buffer around it will be written
coordinates=east,north [,east,north,...]
Coordinates for profiling line nodes
Specify profiling line vertices and nodes
profile_map=name
Profiling line map
Vector map containing profiling line
profile_where=sql_query
WHERE conditions for input profile line map
Use to select only one line from profiling line map
profile_layer=integer
Profiling line map layer
Default: 1
-c
Do not print column names
-z
Do not print 3D vector data (z values)
Only affects 3D vectors
--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
Name of input vector map
Or data source for direct OGR access
Used as: input, vector, name
type : str | list[str], optional
Input feature type
Allowed values: point, line
Default: point,line
where : str, optional
WHERE conditions of SQL statement without 'where' keyword
Example: income < 1000 and population >= 10000
Used as: input, sql_query, sql_query
layer : str, optional
Layer number or name
Use features only from specified layer
Used as: input, layer
Default: 1
output : str, optional
Path to output text file or - for stdout
Used as: output
Default: -
separator : str, optional
Field separator
Special characters: pipe, comma, space, tab, newline
Used as: input, separator, character
Default: pipe
dp : int, optional
Number of significant digits
Allowed values: 0-32
Default: 2
buffer : float, required
Buffer (tolerance) for points in map units
How far points can be from sampling line
Default: 10
map_output : str, optional
Name for profile line and buffer output map
Profile line and buffer around it will be written
Used as: output, vector, name
coordinates : list[tuple[float, float]] | tuple[float, float] | list[float] | str, optional
Coordinates for profiling line nodes
Specify profiling line vertices and nodes
Used as: input, coords, east,north
profile_map : str, optional
Profiling line map
Vector map containing profiling line
Used as: input, vector, name
profile_where : str, optional
WHERE conditions for input profile line map
Use to select only one line from profiling line map
Used as: sql_query
profile_layer : int, optional
Profiling line map layer
Default: 1
flags : str, optional
Allowed values: c, z
c
Do not print column names
z
Do not print 3D vector data (z values)
Only affects 3D vectors
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
v.profile prints out distance and attributes of points/lines along a
profiling line. Distance is calculated from the first profiling line
coordinate pair or from the beginning of vector line.
The buffer (tolerance) parameter sets how far point can be located
from a profiling line and still be included in the output data set.
The output map option can be used to visually check which points are
profiled. The buffer (tolerance) setting does not affect lines. Lines
are sampled at their crossing point with profiling line.
By default Z values are printed if input vector is a 3D map. It can be
disabled with the -z flag.
The profiling line can be provided as N,E coordinate pairs or from an
input vector map. As a profiling line must be a single line, the user
should use the profile_where parameter to select a single line from a
profile input map if it contains multiple vector features.
NOTES
Currently the module can profile only points and lines (including 3D ones). Areas and other complex features are not supported. If in future users can provide reasonable examples how area sampling should work and why it is important, area (or any other feature type) sampling can be added.
Due to bugs in GRASS native buffering algorithms, this module for now depends on GEOS and will not function if GRASS is compiled without GEOS. This restriction will be removed as soon as GRASS native buffer generation is fixed.
EXAMPLES
List all geonames along part of road NC-96 (NC Basic dataset). The output will be stored in a file for later usage. We will use comma as delimiter and three numbers after decimal separator for distance. Output file will contain data for all points, that are within 500 m range to profiling line.
v.profile input=geonames@PERMANENT output=/home/user/NC_96_geonames.csv\
separator=comma dp=3 buffer=500 profile_map=roadsmajor@PERMANENT profile_where=cat=56
# Now lets see the output:
cat NC_96_geonames.csv
Number,Distance,cat,GEONAMEID,NAME,ASCIINAME,ALTERNATEN,FEATURECLA,FEATURECOD,COUNTRYCOD,CC2,ADMIN1,POPULATION,ELEVATION,GTOPO30,TIMEZONE,MODIFICATI,PPLKEY,SRC_ID,MAINT_ID
1,360.719,26881,4482019,"New Zebulon Elementary School","New Zebulon Elementary School","","S","SCH","US","","NC",0,106,91,"America/Iqaluit","2006-01-15 00:00:00",0,0,0
2,846.806,22026,4476596,"Little River, Township of","Little River, Township of","","A","ADMD","US","","NC",0,0,91,"America/Iqaluit","2006-01-15 00:00:00",0,0,0
3,2027.918,16681,4470608,"Hendricks Pond","Hendricks Pond","","H","RSV","US","","NC",0,0,91,"America/Iqaluit","2006-01-15 00:00:00",0,0,0
4,2027.918,16690,4470622,"Hendricks Dam","Hendricks Dam","","S","DAM","US","","NC",0,0,91,"America/Iqaluit","2006-01-15 00:00:00",0,0,0
5,2999.214,39338,4496159,"Union Chapel","Union Chapel","","","","US","","NC",0,0,96,"America/Iqaluit","2006-01-15 00:00:00",0,0,0
6,3784.992,43034,4500325,"Zebulon Airport","Zebulon Airport","","S","AIRP","US","","NC",0,108,98,"America/Iqaluit","2006-01-15 00:00:00",0,0,0
Create river valley crossection and provide river marker (Spearfish dataset):
# Take elevation samples
r.profile input=elevation.dem@PERMANENT output=/home/user/elevation.profile \
profile=600570.27364,4920613.41838,600348.034348,4920840.38617
# Now get distance to place where river marker should be set
v.profile input=streams@PERMANENT output=/home/user/river_profile.csv \
east_north=600570.27364,4920613.41838,600348.034348,4920840.38617
BUGS
Strings are enclosed in double quotes ", still quotes within string are not escaped.
Output does not contain Vector CAT values. Only way how to get CAT value is from the attribute table.
If sampled feature (point, line) contains multiple attribute entries (has multiple CAT values), only the first one is reported. If this is a limitation in some practical use case, a feature request in GRASS GIS issue tracker should be opened.
SEE ALSO
r.profile, Linear Referencing System
AUTHOR
Maris Nartiss
SOURCE CODE
Available at: v.profile source code
(history)
Latest change: Saturday Mar 29 14:59:39 2025 in commit 0bfa813