v.profile(1)

NAME
v.profile - Vector map profiling tool

KEYWORDS
vector, profile, transect

SYNOPSIS
v.profile
v.profile --help
v.profile [-cz] input=name [type=string[,string,...]] [where=sql_query] [layer=string] [output=string] [separator=character] [dp=integer] [format=name] buffer=float [map_output=name] [coordinates=east,north[,east,north,...]] [profile_map=name] [profile_where=sql_query] [profile_layer=integer] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

  Flags:

-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

--ui
    Force launching GUI dialog

  Parameters:

input=name [required]
    Name of input vector map
    Or data source for direct OGR access

type=string[,string,...]
    Input feature type
    Options: 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
    Options: 0-32
    Default: 2

format=name
    Output format
    Options: plain, csv, json
    Default: plain
    plain: Plain text with pipe separator
    csv: CSV (Comma Separated Values)
    json: JSON (JavaScript Object Notation)

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

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 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: Sunday Jan 25 10:11:34 2026 in commit: 662eb2196d98b7b68c137e7ec02380a16b8eea64

Main index | Vector index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.1dev Reference Manual