Vector FAQ

by GRASS Development Team (https://grass.osgeo.org)

What is the difference between line and boundary?

Only boundaries are used to construct areas. Boundaries know the areas to their left and right.

What is the difference between feature id and category?

A category, as the name implies, is used to assign a feature to a certain category. A category is thus not a unique id, even though it can be used as such. Unique feature id's are created automatically be the vector lib and can change when the vector is modified (features added, deleted, topology rebuilt).

In my module I need a unique identifier for feature. The identifier is for internal use only, i.e values will be used to identify features only when module is running. Can I use (internal) feature id for this?

If you want to be sure that feature number x is always the same, it is safer to set categories such that they can be used as feature ids.

I need a unique identifier of a feature. I'm using category for this. How should I check and handle states when number of categories for one line is not equal to 1?

A category always belongs to a given layer. Check if there is one and only one category for the desired layer. If there is no category value set, skip this feature. If there are more categories set for the desired layer, the procedure depends on the purpose of the module. For example, v.extract would extract a feature if any of the categories set for the given layer is in the list of categories to be selected.

I'm using category as a unique identifier of a feature. Thus, the case when number of categories is zero or more than one, I cannot continue in processing. Should I print warning or should I call G_fatal_error()?

Both cases are generally valid in GRASS. Do not print a warning, maybe a verbose message. It is the responsibility of a module to make a reasonable plan how to handle these cases.

My module requires using categories. When iterating over features, my algorithm have to bother with checking of input. It is possible to check categories in some other way i.g., for the whole map at once?

# Python example using ctypes
# checking category for each feature
if areaCats.contents.n_cats == 0:
    # skip processing
    continue

What is feature and what is line (not particular geometry type GV_LINE but the object read by Vect_read_line() function)?

Vect_read_line() reads a feature from the coor file or from external datasources which can be for native GRASS vectors of type GV_POINT, GV_LINE, GV_BOUNDARY, GV_CENTROID or GV_FACE. In the code of the vector library and modules, the word 'line' often refers to a feature in general, not only to features of type GV_LINE.

Can one feature have several categories? Do these categories have to be assigned to one feature in different layers (i.e. can I assign two or more categories to one feature in one layer)?

GRASS supports M:N mapping of categories. Several features can share the same category, and one feature can have several categories. Further more, one feature can have several categories in the same layer. See manual of v.buffer (GRASS 7 only) for an example.

What can I expect to get from function Vect_read_line() according to various combinations of features and categories in vector map?

The return value of Vect_read_line() is the feature type, which must be positive, otherwise the read request was illegal. Vect_read_line() fills the Points and Cats structures with coordinates and categories.

Why there is no function such as Vect_get_point() or Vect_get_boundary_points()?

Because Vect_read_line() does that, i.e. it can read points, lines, boundaries, centroids, faces. The coordinates of these primitive features are stored in one file, and this file does not have separate sections for points, lines, boundaries, centroids, faces. The equivalent of Vect_get_point() etc is done on module level by checking the return type of Vect_read_line(). Further on, sometimes it is desired to work with more than one type at the same time. That's the reason for

if (!(ltype & type))
    continue;

Can I read areas with Vect_read_next_line()?

No. An area is constructed from boundaries and centroids.

What are the standard options for module which has a vector map without attribute table as an input?

Input, output, type. Sometimes layer and category lists.

What are the standard options for module which has a vector map with attribute table as an input?

The above plus where for SQL where option.

When should be layer number taken into account if user requires to do so?

If the user requires it, you have to take it into account if you read features from a map or data from attribute table. More generally, whenever you work with categories.

After reading feature by Vect_read_line() function you should loop over categories in line_cats structure?

It depends. If the feature should only be processed if it belongs to a certain category, yes.

My module reads some data from attribute table columns specified by user. What should I check before I can read from attribute table?

If the columns exist. But sometimes column can be an expression of columns, e.g. col_a/col_b. Otherwise nothing unusual.

My module writes some data to attribute table columns specified by user.

What should I check before I can write to attribute table? If the specified table doesn't exists, should I create one? If the module does not create a new vector, and a table exists, check if the column exists and is of the correct type, if not, create the column. If the module does create a new vector, a new table must also be created.

I should add features to vector map, add tables or columns only if --overwrite was specified, right?

The behaviour for db operations is not cleary defined in GRASS. Quite a lot works without --overwrite. Try v.db.update or v.to.db.

Checking user input is tedious are there any functions which makes it easier?

Not really. There is G_legal_filename(), Vect_legal_filename() and Vect_check_input_output_name(). Module-specific options must be checked by the module.

How can I handle memory correctly?

• Memory allocated by Vect_new_line_struct() and Vect_new_cats_struct() can be automatically reallocated many times by various library functions. However at the end of your work you have to deallocate memory by calling functions Vect_destroy_line_struct() and Vect_destroy_cats_struct().
• Structure Map_info is usually created on stack so no need for deallocating. Structure Map_info is used by modules like this:

  struct Map_info In, Out;

  So, no pointers, no allocation, no deallocation.

As a rule of thumb, whenever you use some Vect_new_*() function, there should also be a corresponding Vect_destroy_*() function. These deallocating functions need only be used if the Vect_new_*() functions are called in a loop. A one-time call does not matter, memory is freed by the system when the module exits.

What is the purpose of cat_list and ilist structures?

A cat_list is used to store a list of cats, e.g. from a cats option. The ilist struct is a list of integers.

How can I handle data without topology or data which are topologically incorrect?

Use Vect_read_next_line() function.

How can I handle overlapping areas? Can I use boundaries (GV_BOUNDARY) instead of areas (GV_AREA)?

Overlapping boundaries are not topologically correct either. Either break boundaries, or (internal use only) do not build areas, or use lines if lines can hold all the info you need.

Can I use boundaries or lines to represent topologically incorrect (i.e. overlapping) areas?

In general, overlapping areas must be broken up into non-overlapping components. Some of the new areas will have several categories, one for each original area. For internal use, lines may be ok. Use lines instead of boundaries if you don't want to break into non-overlapping components.

Region is not taken into account by vector library functions. Should my module do the same or it should do its work only in current region?

It depends what your module is supposed to do. See v.in.ogr, v.in.region or v.to.rast for examples where the current region is considered.

When should I use the digitization threshold value from vector map metadata?

What is the advantage of automatically attaching centroids to areas? How can one be sure that connecting will be successful?

This question is unclear. What would be the alternative? The method to attach centroids to areas is well tested and has been working reliably for many years.

Are there any functions providing functionality of v.to.rast and r.to.vect modules?

No. Considering the large code base of these two modules, this would require new libraries which in turn would depend on both the vector and the raster libraries.

What is Vector Simple Feature Access API? Is it related to OGC standard (like ST_ functions in Postgis)?