[GRASS-SVN] r55439 - grass/trunk/lib/vector

[svn_grass at osgeo.org]

Author: wenzeslaus
Date: 2013-03-19 05:37:51 -0700 (Tue, 19 Mar 2013)
New Revision: 55439

Added:
   grass/trunk/lib/vector/vectorlib_faq.dox
Modified:
   grass/trunk/lib/vector/vectorlib.dox
Log:
vlib/dox: vector FAQ (answered by mmetz)

Modified: grass/trunk/lib/vector/vectorlib.dox
===================================================================
--- grass/trunk/lib/vector/vectorlib.dox	2013-03-19 11:42:32 UTC (rev 55438)
+++ grass/trunk/lib/vector/vectorlib.dox	2013-03-19 12:37:51 UTC (rev 55439)
@@ -4,13 +4,14 @@
 
 \tableofcontents
 
-\par Related
+\par Related pages
 - \subpage vlibDescription
 - \subpage vlibFormat
 - \subpage vlibTopology
 - \subpage vlibIndices
 - \subpage vlibAscii
 - \subpage vlibTin
+- \subpage vlibFAQ
 
 \par Data providers for external formats
 - \subpage vlibOgr

Added: grass/trunk/lib/vector/vectorlib_faq.dox
===================================================================
--- grass/trunk/lib/vector/vectorlib_faq.dox	                        (rev 0)
+++ grass/trunk/lib/vector/vectorlib_faq.dox	2013-03-19 12:37:51 UTC (rev 55439)
@@ -0,0 +1,110 @@
+/*! \page vlibFAQ Vector FAQ
+
+by GRASS Development Team (http://grass.osgeo.org)
+
+\par What is the difference between line and boundary?
+Only boundaries are used to construct areas. Boundaries know the areas to their left and right.
+
+\par 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).
+
+\par 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.
+
+\par 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, \gmod{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.
+
+\par 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 generaly 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.
+
+\par 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?
+\code{.py}
+# Python example using ctypes
+# checking category for each feature
+if areaCats.contents.n_cats == 0:
+    # skip processing
+    continue
+\endcode
+
+\par What is feature and what is line (not particular geometry type GV_LINE but thing read by Vect_read_line() function)?
+Vect_read_line() reads, GV_POINT, GV_LINE, GV_BOUNDARY, GV_CENTROID, GV_FACE.
+
+\par 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 \gmod{v.buffer} (GRASS 7 only) for an example.
+
+\par 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. 
+
+\par Why there is no function such as Vect_get_point() or Vect_get_boundary_points()?
+The GRASS-internal feature id refers to primitives (points, lines, boundaries, centroids, faces). These are all lumped together. That means that something like Vect_get_point() would use as arguments map and id, but this id can refer to any of points, lines, boundaries, centroids, faces. The coordinates of these primitives 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() 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
+\code{.c}
+if ((ltype & type))
+    continue;
+\endcode
+
+\par Can I read areas with Vect_read_next_line()?
+No. An area is constructed from boundaries and centroids.
+
+\par 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.
+
+\par 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.
+
+\par 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.
+
+\par 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.
+
+\par 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.
+
+\par 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, if not, create the column. If the module does create a new vector, a new table must also be created.
+
+\par I should add features to vector map, add tables or columns only if \c \-\-overwrite was specified, right?
+The behaviour for db operations is not cleary defined in GRASS. Quite a lot works without \c \-\-overwrite. Try \gmod{v.db.update} or \gmod{v.to.db}.
+
+\par 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.
+
+\par How can I handle memory correctly?
+<ul>
+<li>
+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().
+<li>
+Structure Map_info is usually created on stack so no need for deallocating. Structure Map_info is used by modules like this:
+\code{.c}
+struct Map_info In, Out;
+\endcode
+So, no pointers, no allocation, no deallocation.
+</ul>
+As a rule of thumb, whenever you use some \c Vect_new_*() function, there should also be a corresponding \c Vect_destroy_*() function. These deallocating functions need only be used if the \c 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.
+
+\par What is the propose 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.
+
+\par How can I handle data without topology or data which are topologically incorrect?
+Use Vect_read_next_line() function.
+
+\par 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.
+
+\par 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. For internal use, lines may be ok. Use lines instead of boundaries if you don't want to break into non-overlapping components.
+
+\par 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?
+
+\par When should I use the digitization threshold value from vector map metadata?
+
+\par What is the advantage of automatic attaching centroid to boundary to create area? How can be one sure that connecting it will be successful?
+
+\par Are there any functions providing functionality of \gmod{v.to.rast} and \gmod{r.to.vect} modules?
+
+\par What is Vector Simple Feature Access API? Is it related to OGC standard (like ST_ functions in Postgis)?
+
+*/