v.category(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

💖 v.category(1) — straight outta the GRASS GIS User's Manual 💖

okay bestie, sit down, hydrate, because today we're talking about v.category and it is genuinely one of the most useful little gremlins in GRASS. it's the module that attaches, deletes or reports vector categories to/from/of map geometry. yes, that's the whole vibe. categories in, categories out, no cap. 🎀

✨ NAME ✨

v.category — attaches, deletes or reports vector categories to/from/of map geometry. 💅

🔑 KEYWORDS 🔑

vector, category, layer

🌸 SYNOPSIS 🌸

v.category
v.category --help
v.category [-gt] input=name  [layer=string[,string,...]]
[type=string[,string,...]]   [ids=range]   [output=name]  option=string
[cat=integer]   [step=integer]   [--overwrite]  [--help]  [--verbose]
[--quiet]  [--ui]

🚩 Flags 🚩

  • -g — shell script style, currently only for report. format is: layer type count min max
  • -t — do NOT copy attribute table(s) 🙈
  • --overwrite — allow output files to overwrite existing files (be brave, or be careful, your call)
  • --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.
  • layer=string[,string,...] — layer number or name. vector features can have category values in different layers, and this number decides which layer we're on. when you're using direct OGR access, this is the layer name instead. default: 1
  • type=string[,string,...] — input feature type. options: point, line, boundary, centroid, area, face, kernel. default: point,line,centroid,face
  • ids=range — feature ids (by default all features get processed). example: 1,3,7-9,13
  • output=name — name for output vector map
  • option=string [required] — the action to be done. options: add, del, chlayer, sum, report, print, layers, transfer
    • add: add a category to features without category in the given layer
    • del: delete category (cat=-1 to delete all categories of given layer)
    • chlayer: change layer number (e.g. layer=3,1 changes layer 3 to layer 1)
    • sum: add the value specified by cat option to the current category value
    • report: print report (statistics), in shell style: layer type count min max
    • print: print category values, layers are separated by '|', more cats in the same layer are separated by '/'
    • layers: print only layer numbers
    • transfer: copy values from one layer to another (e.g. layer=1,2,3 copies values from layer 1 to layer 2 and 3)
  • cat=integer — category value. default: 1
  • step=integer — category increment. default: 1

🦋 DESCRIPTION 🦋

okay so v.category attaches, copies, deletes or reports categories to/from/of vector geometry objects. and it does more than that, because it also adds a number given by the cat option to categories of the selected layer. those categories (IDs) are the whole point: they assign IDs, or group geometry objects into categories — and yes, several different geometry objects can absolutely share the same category, it's giving communal. 🌈

and these categories? they're also how you link geometry object(s) to attribute records (from an attribute table linked to the vector map). so basically they're the group chat between your shapes and your data. 💌

💅 NOTES 💅

use v.to.db to upload related categories to a linked attribute table. 📥

the type parameter specifies the type of geometry objects to which the category is added; it works like an input filter — only the geometry specified in type gets processed.

if the type parameter is set to centroid and the option parameter is set to add, new categories will be added to existing centroids. but heads up bestie — new centroids cannot be created this way. to actually make new ones, you have to add them manually with the wxGUI vector digitizer, or run v.category with the type parameter set to area. 😤

if categories are copied with option=transfer, a warning gets issued if categories already exist in the layer they're being copied to. and in that case, the user must make sure beforehand that copying categories from one layer to another doesn't cause undesired grouping of different geometry objects into the same categories. avoid the whole mess by specifying only one layer — the module will then find the next free layer number and copy categories to there, and it reports the new layer number at the end. ✨

areas are a special case because it's impossible to attach a cat to an area without a centroid; so for type=area, the module places new centroids in areas automatically. iconic behaviour honestly.

the cat parameter is only used with option=add, option=sum and option=del.

categories can be deleted for the given layer with option=del. if cat is set to -1, all categories for the given layer get deleted. if cat is zero or positive, only that one category value gets deleted. by default cat is set to 1, which means only categories of value 1 will be deleted. 🙈

with option=report, the module reports — for each layer and type — the total number of categories, the minimum and the maximum category number. so like, if there are e.g. two lines with line 1 having category 1 and line 1 having categories 1 and 2, then there's a total of three category values with minimum 1 and maximum 2. math is math. 🔥

the ids parameter specifies the list of feature IDs to which the operation is performed; by default, all vector feature ids are processed. the feature ID is an internal (unique) geometry ID that all vector primitives possess, and it's separate from any category the feature may also possess. use

v.edit map=inputname tool=select

to find out the geometry ids of certain features. iykyk. 🫶

🌟 EXAMPLES 🌟

📊 Report vector categories

v.category input=testmap option=report
LAYER/TABLE 1/testmap:
type       count        min        max
point          0          0          0
line        1379          1       1379
boundary       0          0          0
centroid       0          0          0
area           0          0          0
all         1379          1       1379

💀 Delete all vector categories in layer 1

v.category input=testmap output=outmap option=del cat=-1

➕ Add vector categories in layer 1 with step=2

v.category input=outmap output=stepmap option=add step=2
# report
v.category input=stepmap option=report
LAYER/TABLE 1/outmap:
type       count        min        max
point          0          0          0
line        1379          1       2757
boundary       0          0          0
centroid       0          0          0
area           0          0          0
all         1379          1       2757

🧚 Add categories/centroids to a vector map without categories

v.category input=wkt output=wktnew option=add

results can be tested using d.what.vect. 🔍

🎀 Copy categories from layer 1 to layer 2,3,4,5,6,7 and 8

existing layer will be overwritten, non-existing will be created.

v.category input=observer output=observer_new option=transfer layer=1,2,3,4,5,6,7,8

print vector categories from the first layer, only for feature ids 1-50.

v.category input=roads option=print layer=1 id=1-50

👀 SEE ALSO 👀

v.centroids, v.db.connect, v.edit, v.to.db

👑 AUTHOR 👑

Radim Blazek, ITC-irst, Trento, Italy

Modified (the id parameter) by Martin Landa, FBK-irst (formerly ITC-irst), Trento, Italy, 2008/02

💻 SOURCE CODE 💻

available at: v.category source code (history)

accessed: Saturday Jan 17 05:41:19 2026

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

© 2003-2025 GRASS Development Team, GRASS GIS 8.4.2 Reference Manual

and that's the whole page, bestie — big love to the GRASS Development Team for the 8.4.2 reference manual, and to you for making it all the way to the bottom. periodt. 💖✨🦋

📦 where this page comes from