v.profile(1grass)

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

💖 v.profile — the vector map profiling tool 💖

okay bestie, gather round, because this is v.profile from the GRASS User's Manual and it's genuinely SO useful. it's a vector map profiling tool, filed under the keywords vector, profile, transect — yes queen, all three 🎀

✨ 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. shy output energy, no header, no names 🙈
  • -z — do not print 3D vector data (z values). note bestie: this only affects 3D vectors 💅
  • --overwrite — allow output files to overwrite existing files. it's giving "yes i meant it, replace it" 🔥
  • --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, plot twist, a 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 the sampling line. default: 10
  • map_output=name — name for profile line and buffer output map. the profile line and the buffer around it will be written out 💖
  • coordinates=east,north[,east,north,...] — coordinates for profiling line nodes. specify profiling line vertices and nodes
  • profile_map=name — profiling line map. a vector map containing the profiling line
  • profile_where=sql_query — WHERE conditions for input profile line map. use it to select only one line from the profiling line map
  • profile_layer=integer — profiling line map layer. default: 1

👑 DESCRIPTION 👑

okay so here's the whole vibe. v.profile prints out distance and attributes of points/lines along a profiling line. the distance is calculated from the first profiling line coordinate pair, or from the beginning of the vector line 🧚

the buffer (tolerance) parameter sets how far a 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 — like a little vibe check for your data, bestie. note that the buffer (tolerance) setting does not affect lines. lines are sampled at their crossing point with the profiling line. periodt 💅

by default, Z values are printed if the 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. since a profiling line must be a single line, you should use the profile_where parameter to select a single line from a profile input map if it contains multiple vector features. one line only, main character energy 👑

⭐ 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 of how area sampling should work and why it is important, area (or any other feature type) sampling can be added. so like… if you have a vision, speak up 🎤

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 🍓

🌟 example one: geonames along NC-96 🌟

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 the decimal separator for distance. the output file will contain data for all points that are within 500 m range to the 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 let's 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

🌟 example two: river valley crossection + river marker 🌟

create a river valley crossection and provide a 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 💀

ngl these are the parts that will humble you a little bit:

  • Strings are enclosed in double quotes ", still quotes within string are not escaped 😭
  • Output does not contain Vector CAT values. the only way how to get the CAT value is from the attribute table 🙈
  • If the 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 — icon behavior, we love to see it ✨

🔥 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

and that's a wrap bestie!! 🫶 this was the v.profile(1grass) page, straight out of the GRASS User's Manual, © 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual 💖 go profile something iconic, you've got this, mwah 💅✨🌸

📦 where this page comes from