v.category(1grass)

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

🦋 v.category — the GRASS User's Manual page, but make it make sense 💅

okay bestie, gather round, because we're talking about v.category, the GRASS module that attaches, deletes or reports vector categories to/from/of map geometry. fr fr. that's the whole vibe. categories are the little ID numbers that tell geometry objects who they are and which attribute table row is theirs. it's giving matchmaker energy. 💖

✨ 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]  format=name  [separator=character]
[--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

🎀 Flags 🎀

  • -g — CSV style output, currently only for report — deprecated 🙈. Format: layer type count min max. so listen, this flag is deprecated and will be removed in a future release. use format=csv instead, no cap.
  • -t — Do not copy attribute table(s). like, leave the tables where they are.
  • --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.
  • layer=string[,string,...] — Layer number or name. Vector features can have category values in different layers. This number determines which layer to use. When used with direct OGR access this is the layer name. 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 are processed). Example: 1,3,7-9,13
  • output=name — Name for output vector map.
  • option=string [required] — 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 CSV 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
  • format=name [required] — Output format. Options: plain, csv, json Default: plain
    • plain: Human readable text output
    • csv: CSV (Comma Separated Values)
    • json: JSON (JavaScript Object Notation)
  • separator=character — Field separator. Special characters: pipe, comma, space, tab, newline

👑 DESCRIPTION 👑

v.category** attaches, copies, deletes or reports categories to/from/of vector geometry objects. and like, beyond that? v.category adds a number given by the cat option to categories of the selected layer.

these categories (they're IDs, bestie) are used to assign IDs or to group geometry objects into categories — and yes, several different geometry objects can share the same category, that's the whole point, it's a group chat not a DM. 💌 these categories are also what link geometry object(s) to attribute records (from an attribute table linked to the vector map). so iconic.

🧚 NOTES 🧚

Use v.to.db to upload related categories to a linked attribute table. that's the handoff, periodt.

The type parameter specifies the type of geometry objects to which the category is added; it is similar to an input filter — only the geometry specified in 'type' is processed. vibe check, but for geometry.

If the type parameter is set to centroid and the option parameter set to add, new categories will be added to existing centroids. but lowkey note this: new centroids cannot be created this way. 🚫 to do that, they must be added manually using wxGUI vector digitizer or by running v.category with the type parameter set to area.

If categories are copied with option=transfer, a warning is issued if categories already exist in the layer they are copied to. in that case the user must make sure beforehand that copying categories from one layer to another layer does not cause undesired grouping of different geometry objects into the same categories. 😭 you can dodge this 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. slay.

Areas are a special case because it is impossible to attach a cat to an area without a centroid; in this case, the module places new centroids in areas automatically for type=area. it just does it for you, bestie. 🫶

The cat parameter is only used with option=add, option=sum and option=del. that's it. that's the list.

Categories can be deleted for the given layer with option=del. If cat is set to -1, all categories for the given layer are deleted. If cat is zero or positive, only this category value will be deleted. By default, cat is set to 1, which means that only categories of value 1 will be deleted. ⚠️ so be careful out there.

With option=report, the module reports for each layer and type the total number of categories, the minimum and the maximum category number. If there are e.g. two lines with line 1 having category 1 and line 1 having categories 1 and 2, then there are a total of three category values with minimum 1 and maximum 2. math is mathing. ✨

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 is 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

Report vector categories in JSON format:

v.category input=testmap option=report format=json
[
  {
      "type": "line",
      "layer": 1,
      "count": 1379,
      "min": 1,
      "max": 1379
  },
  {
      "type": "all",
      "layer": 1,
      "count": 1379,
      "min": 1,
      "max": 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

Print vector categories from the first layer, only for feature ids 1-50 in JSON format.

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

🍓 Using v.category JSON output with pandas

Using report option in JSON format with pandas:

import grass.script as gs
import pandas as pd
# Run v.category command with report option.
data = gs.parse_command(
    "v.category",
    input="bridges",
    option="report",
    format="json",
)
df = pd.DataFrame(data)
print(df)
    type  layer  count  min    max
0  point      1  10938    1  10938
1    all      1  10938    1  10938

Using print option with the first layer, only for feature ids 1-5 in JSON format with pandas:

import grass.script as gs
import pandas as pd
# Run v.category command with print option.
data = gs.parse_command(
    "v.category",
    input="bridges",
    option="print",
    ids="1-5",
    format="json",
)
df = pd.DataFrame(data)
print(df)
    id  layer  category
0   1      1         1
1   2      1         2
2   3      1         3
3   4      1         4
4   5      1         5

🔥 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)

Latest change: Tuesday Dec 23 01:01:29 2025 in commit: bd72a099936e70015686f5793bbc8eac9be0b901

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

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual

and that's the whole page bestie 🫶💅 this was v.category from GRASS 8.5.0, dated GRASS 8.5.0 in the footer, and the source shipped as v.category(1grass) — go forth and categorize responsibly, mwah 💜

📦 where this page comes from