v.surf.bspline: fix default driver/db

                rename sparse param to sparse_input
                rename raster param to raster_output


git-svn-id: https://svn.osgeo.org/grass/grass/trunk@54444 15284696-431f-4ddb-bdfa-cd5b030d7da7

vector/v.surf.bspline/main.c

@@ -45,7 +45,7 @@ int main(int argc, char *argv[])
     double stepN, stepE, lambda, mean;
     double N_extension, E_extension, edgeE, edgeN;
 
-    const char *mapset, *dvr, *db, *vector, *map;
+    const char *mapset, *drv, *db, *vector, *map;
     char table_name[GNAME_MAX], title[64];
     char xname[GNAME_MAX], xmapset[GMAPSET_MAX];
 
@@ -77,7 +77,6 @@ int main(int argc, char *argv[])
     struct bound_box general_box, overlap_box, original_box;
 
     struct Point *observ;
-    struct line_pnts *points;
     struct line_cats *Cats;
     dbCatValArray cvarr;
 
@@ -93,7 +92,7 @@ int main(int argc, char *argv[])
     G_add_keyword(_("interpolation"));
     G_add_keyword(_("LIDAR"));
     module->description =
-	_("Bicubic or bilinear spline interpolation with Tykhonov regularization.");
+	_("Performs bicubic or bilinear spline interpolation with Tykhonov regularization.");
 
     cross_corr_flag = G_define_flag();
     cross_corr_flag->key = 'c';
@@ -112,18 +111,21 @@ int main(int argc, char *argv[])
     withz_flag->guisection = _("Settings");
 
     in_opt = G_define_standard_option(G_OPT_V_INPUT);
+    in_opt->label = _("Name of input vector point map");
+    
+    dfield_opt = G_define_standard_option(G_OPT_V_FIELD);
 
     in_ext_opt = G_define_standard_option(G_OPT_V_INPUT);
-    in_ext_opt->key = "sparse";
+    in_ext_opt->key = "sparse_input";
     in_ext_opt->required = NO;
-    in_ext_opt->description =
-	_("Name of input vector map of sparse points");
+    in_ext_opt->label =
+	_("Name of input vector map with sparse points");
 
     out_opt = G_define_standard_option(G_OPT_V_OUTPUT);
     out_opt->required = NO;
 
     out_map_opt = G_define_standard_option(G_OPT_R_OUTPUT);
-    out_map_opt->key = "raster";
+    out_map_opt->key = "raster_output";
     out_map_opt->required = NO;
 
     mask_opt = G_define_standard_option(G_OPT_R_INPUT);
@@ -167,10 +169,6 @@ int main(int argc, char *argv[])
     lambda_f_opt->answer = "0.01";
     lambda_f_opt->guisection = _("Settings");
 
-    dfield_opt = G_define_standard_option(G_OPT_V_FIELD);
-    dfield_opt->answer = "1";
-    dfield_opt->guisection = _("Settings");
-
     col_opt = G_define_standard_option(G_OPT_DB_COLUMN);
     col_opt->key = "column";
     col_opt->required = NO;
@@ -219,12 +217,13 @@ int main(int argc, char *argv[])
 
     flag_auxiliar = FALSE;
 
-    if (!(db = G__getenv2("DB_DATABASE", G_VAR_MAPSET)))
-	G_fatal_error(_("Unable to read name of database"));
-
-    if (!(dvr = G__getenv2("DB_DRIVER", G_VAR_MAPSET)))
-	G_fatal_error(_("Unable to read name of driver"));
-
+    drv = db_get_default_driver_name();
+    if (!drv)
+        G_fatal_error(_("No default DB driver defined"));
+    db = db_get_default_database_name();
+    if (!db)
+        G_fatal_error(_("No default DB defined"));
+    
     /* Set auxiliary table's name */
     if (vector) {
 	if (G_name_is_fully_qualified(out_opt->answer, xname, xmapset)) {
@@ -235,12 +234,12 @@ int main(int argc, char *argv[])
     }
 
     /* Something went wrong in a previous v.surf.bspline execution */
-    if (db_table_exists(dvr, db, table_name)) {
+    if (db_table_exists(drv, db, table_name)) {
 	/* Start driver and open db */
-	driver = db_start_driver_open_database(dvr, db);
+	driver = db_start_driver_open_database(drv, db);
 	if (driver == NULL)
 	    G_fatal_error(_("No database connection for driver <%s> is defined. Run db.connect."),
-			  dvr);
+			  drv);
 	if (P_Drop_Aux_Table(driver, table_name) != DB_OK)
 	    G_fatal_error(_("Old auxiliary table could not be dropped"));
 	db_close_database_shutdown_driver(driver);
@@ -254,7 +253,7 @@ int main(int argc, char *argv[])
     if (1 > Vect_open_old(&In, in_opt->answer, mapset))
 	G_fatal_error(_("Unable to open vector map <%s> at the topological level"),
 		      in_opt->answer);
-
+    
     bspline_field = Vect_get_field_number(&In, dfield_opt->answer);
     bspline_column = col_opt->answer;
 
@@ -263,7 +262,8 @@ int main(int argc, char *argv[])
 	G_fatal_error(_("Input vector is not 3D, can not use z coordinates"));
     }
     else if (!withz_flag->answer && (bspline_field <= 0 || bspline_column == NULL))
-	G_fatal_error(_("Both layer and column with z values must be given"));
+	G_fatal_error(_("Option '%s' with z values or '-%c' flag must be given"),
+                      col_opt->key, withz_flag->key);
 
     if (withz_flag->answer)
 	bspline_field = 0;
@@ -272,12 +272,13 @@ int main(int argc, char *argv[])
     if (spline_step_flag->answer) {
 	double dens, dist;
 	if (P_estimate_splinestep(&In, &dens, &dist) == 0) {
-	    G_message("Estimated point density: %.4g", dens);
-	    G_message("Estimated mean distance between points: %.4g", dist);
+	    fprintf(stdout, _("Estimated point density: %.4g"), dens);
+            fprintf(stdout, _("Estimated mean distance between points: %.4g"), dist);
 	}
-	else
-	    G_warning(_("No points in current region!"));
-	
+	else {
+	    fprintf(stdout, _("No points in current region"));
+	}
+        
 	Vect_close(&In);
 	exit(EXIT_SUCCESS);
     }
@@ -319,10 +320,10 @@ int main(int argc, char *argv[])
     /* Open output map */
     /* vector output */
     if (vector && !map) {
-	if (strcmp(dvr, "dbf") == 0)
+	if (strcmp(drv, "dbf") == 0)
 	    G_fatal_error(_("Sorry, the <%s> driver is not compatible with "
 			  "the vector output of this module. "
-			  "Try with raster output or another driver."), dvr);
+			  "Try with raster output or another driver."), drv);
 
 	Vect_check_input_output_name(in_opt->answer, out_opt->answer,
 				     G_FATAL_EXIT);
@@ -343,8 +344,8 @@ int main(int argc, char *argv[])
 	}
 	Vect_hist_command(&Out);
 
-	G_message(_("Points in input vector map <%s> will be interpolated"),
-		  vector);
+	G_verbose_message(_("Points in input vector map <%s> will be interpolated"),
+                          vector);
     }
 
     /* raster output */
@@ -354,8 +355,8 @@ int main(int argc, char *argv[])
 	grid = TRUE;
 	raster = Rast_open_fp_new(out_map_opt->answer);
 
-	G_message(_("Cells for raster map <%s> will be interpolated"),
-		  map);
+	G_verbose_message(_("Cells for raster map <%s> will be interpolated"),
+                          map);
     }
 
     /* read z values from attribute table */
@@ -394,10 +395,10 @@ int main(int argc, char *argv[])
     G_debug(1, "Interpolation()");
 
     /* Open driver and database */
-    driver = db_start_driver_open_database(dvr, db);
+    driver = db_start_driver_open_database(drv, db);
     if (driver == NULL)
 	G_fatal_error(_("No database connection for driver <%s> is defined. "
-			"Run db.connect."), dvr);
+			"Run db.connect."), drv);
 
     /* Create auxiliary table */
     if (vector) {
@@ -410,7 +411,7 @@ int main(int argc, char *argv[])
 	/* db_create_index2(driver, table_name, "ID"); */
 	/* sqlite likes that */
 	db_close_database_shutdown_driver(driver);
-	driver = db_start_driver_open_database(dvr, db);
+	driver = db_start_driver_open_database(drv, db);
     }
 
     /* Setting regions and boxes */
@@ -528,8 +529,8 @@ int main(int argc, char *argv[])
     P_get_edge(bilin, &dims, stepE, stepN);
     P_set_dim(&dims, stepE, stepN, &nsplx_adj, &nsply_adj);
 
-    G_verbose_message(_("adjusted EW splines %d"), nsplx_adj);
-    G_verbose_message(_("adjusted NS splines %d"), nsply_adj);
+    G_verbose_message(_("Adjusted EW splines %d"), nsplx_adj);
+    G_verbose_message(_("Adjusted NS splines %d"), nsply_adj);
 
     /* calculate number of subregions */
     edgeE = dims.ew_size - dims.overlap - 2 * dims.edge_v;
@@ -549,7 +550,6 @@ int main(int argc, char *argv[])
     nsubregions = nsubregion_row * nsubregion_col;
 
     /* Creating line and categories structs */
-    points = Vect_new_line_struct();
     Cats = Vect_new_cats_struct();
     Vect_cat_set(Cats, 1, 0);
 
@@ -601,8 +601,8 @@ int main(int argc, char *argv[])
 	    subregion_col++;
 	    subregion++;
 	    if (nsubregions > 1)
-		G_message(_("subregion %d of %d"), subregion, nsubregions);
-
+		G_message(_("Subregion %d of %d..."), subregion, nsubregions);
+            
 	    P_set_regions(&elaboration_reg, &general_box, &overlap_box, dims,
 			  GENERAL_COLUMN);
 
@@ -684,7 +684,8 @@ int main(int argc, char *argv[])
 	    G_debug(1,
 		    "Interpolation: (%d,%d): Number of points in <elaboration_box> is %d",
 		    subregion_row, subregion_col, npoints);
-
+            if (npoints > 0)
+                G_verbose_message(_("%d points found in this subregion"), npoints);
 	    /* only interpolate if there are any points in current subregion */
 	    if (npoints > 0 && npoints_ext > 0) {
 		int i;

vector/v.surf.bspline/v.surf.bspline.html

@@ -1,18 +1,25 @@
 <h2>DESCRIPTION</h2>
-<em>v.surf.bspline</em> performs a bilinear/bicubic spline interpolation with
-Tykhonov regularization. The input is a 2D or 3D vector points map. Values to
-interpolate can be the z values of 3D points or the values in a user-specified
-attribue column in a 2D or 3D map. Output can be a raster or vector map.
-Optionally, a "sparse point" vector map can be input which indicates the
-location of <b><i>output</i></b> vector points.
-<p>From a theoretical perspective, the interpolating procedure takes place in two
-parts: the first is an estimate of the linear coefficients of a spline function
-is derived from the observation points using a least squares regression; the
-second is the computation of the interpolated surface (or interpolated vector
-points). As used here, the splines are 2D piece-wise non-zero polynomial
-functions calculated within a limited, 2D area. The length of each spline step
-is defined by <b><i>sie</i></b> for the east-west direction and
-<b><i>sin</i></b> for the north-south direction. For optimum performance, the
+
+<em>v.surf.bspline</em> performs a bilinear/bicubic spline
+interpolation with Tykhonov regularization. The <b>input</b> is a 2D
+or 3D vector <em>points</em> map. Values to interpolate can be the z
+values of 3D points or the values in a user-specified attribute column
+in a 2D or 3D vector map. Output can be a raster
+(<b>raster_output</b>) or vector (<b>output</b>) map.  Optionally, a
+"sparse point" vector map can be input which indicates the location
+of <b>output</b> vector points.
+
+<h2>NOTES</h2>
+
+<p>From a theoretical perspective, the interpolating procedure takes
+place in two parts: the first is an estimate of the linear
+coefficients of a spline function is derived from the observation
+points using a least squares regression; the second is the computation
+of the interpolated surface (or interpolated vector points). As used
+here, the splines are 2D piece-wise non-zero polynomial functions
+calculated within a limited, 2D area. The length of each spline step
+is defined by <b>sie</b> for the east-west direction and
+<b>sin</b> for the north-south direction. For optimum performance, the
 length of spline step should be no less than the distance between observation
 points. Each vector point observation is modeled as a linear function of the
 non-zero splines in the area around the observation. The least squares
@@ -20,57 +27,66 @@ regression predicts the the coefficients of these linear functions.
 Regularization, avoids the need to have one one observation and one coefficient
 for each spline (in order to avoid instability). 
 
-<p>With regularly distributed data points, a spline step corresponding to the
-maximum distance between two points in both the east and north directions is
-sufficient. But often data points are not regularly distributed and require
-statistial regularization or estimation. In such cases, v.surf.bspline will
-attempt to minimize the gradient of bilinear splines or the curvature of bicubic
-splines in areas lacking point observations. As a general rule, spline step
-length should be greater than the mean distance between observation points
-(twice the distance between points is a good starting point). Separate east-west
-and north-south spline step length arguments allows the user to account for some
-degree of anisotropy in the distribution of observation points. Short spline
-step lengths--especially spline step lengths that are less than the distance
-between observation points--can greatly increase processing time.
-
-<p>Moreover, the maximum number of splines for each direction at each time is
-fixed, regardless of the spline step length. As the total number of splines used
-increases (i.e., with small spline step lengths), the region is automatically split
-into subregions for interpolation. Each subregion can contain no more than
-150x150 splines. To avoid subregion boundary problems, subregions are created to
-partially overlap each other. A weighted mean of observations, based on point
-locations, is calculated within each subregion. 
-
-<p>The Tykhonov regularization parameter ("<b><i>lambda_i</i></b>") acts to smooth
-the interpolation. With a small <b><i>lambda_i</i></b>, the interpolated surface
-closely follows observation points; a larger value will produce a smoother
-interpolation.
-
-<p>The input can be a 2D pr 3D vector points map. If "<b><i>layer =</i></b>" 0 the
-z-value of a 3D map is used for interpolation. If layer &gt; 0, the user must
-specify an attribute column to used for interpolation using the
-"<b><i>column=</i></b>" argument (2D or 3D map). 
-
-<p>v.surf.bspline can produce a raster OR a vector output (NOT simultaneously).
-
-<p>If output is a vector points map and a "<b><i>sparse=</i></b>" vector points map
-is not specified, the output vector map will contain points at the same
-locations as observation points in the input map, but the values of the output
-points are interpolated values. If instead a "<b><i>sparse=</i></b>" vector points
-map is specified, the output vector map will contain points at the same locations as
-the sparse vector map points, and values will be those of the interpolated
-raster surface at those points.
-
-<p>A cross validation "leave-one-out" analysis is available to help to determine
-the optimal <b><i>lambda_i</i></b> value that produces an interpolation that
-best fits the original observation data. The more points used for
-cross-validation, the longer the time needed for computation. Empirical testing
-indicates a threshold of a maximum of 100 points is recommended. Note that cross
-validation can run very slowly if more than 100 observations are used. The
-cross-validation output reports <i>mean</i> and <i>rms</i> of the residuals from
-the true point value and the estimated from the interpolation for a fixed series
-of <b><i>lambda_i</i></b> values. No vector nor raster output will be created
-when cross-validation is selected. 
+<p>With regularly distributed data points, a spline step corresponding
+to the maximum distance between two points in both the east and north
+directions is sufficient. But often data points are not regularly
+distributed and require statistial regularization or estimation. In
+such cases, v.surf.bspline will attempt to minimize the gradient of
+bilinear splines or the curvature of bicubic splines in areas lacking
+point observations. As a general rule, spline step length should be
+greater than the mean distance between observation points (twice the
+distance between points is a good starting point). Separate east-west
+and north-south spline step length arguments allows the user to
+account for some degree of anisotropy in the distribution of
+observation points. Short spline step lengths - especially spline step
+lengths that are less than the distance between observation points -
+can greatly increase processing time.
+
+<p>Moreover, the maximum number of splines for each direction at each
+time is fixed, regardless of the spline step length. As the total
+number of splines used increases (i.e., with small spline step
+lengths), the region is automatically split into subregions for
+interpolation. Each subregion can contain no more than 150x150
+splines. To avoid subregion boundary problems, subregions are created
+to partially overlap each other. A weighted mean of observations,
+based on point locations, is calculated within each subregion.
+
+<p>The Tykhonov regularization parameter (<b>lambda_i</b>) acts to
+smooth the interpolation. With a small <b>lambda_i</b>, the
+interpolated surface closely follows observation points; a larger
+value will produce a smoother interpolation.
+
+<p>The input can be a 2D or 3D vector points map. If <b>-z</b> is
+given or <b>layer</b> is 0 the z-value of a 3D map is used for
+interpolation. If <b>layer</b> &gt; 0, the user must specify an
+attribute column to used for interpolation using the <b>column</b>
+argument (2D or 3D map).
+
+<p><em>v.surf.bspline</em> can produce a <b>raster_output</b> OR
+a <b>output</b> (but NOT simultaneously). Note that topology is not
+build for output vector point map. The topology can be built if
+required by <em><a href="v.build.html">v.build</a></em>.
+
+<p>If output is a vector points map and a <b>sparse</b> vector points
+map is not specified, the output vector map will contain points at the
+same locations as observation points in the input map, but the values
+of the output points are interpolated values. If instead
+a <b>sparse</b> vector points map is specified, the output vector map
+will contain points at the same locations as the sparse vector map
+points, and values will be those of the interpolated raster surface at
+those points.
+
+<p>A cross validation "leave-one-out" analysis is available to help to
+determine the optimal <b>lambda_i</b> value that produces an
+interpolation that best fits the original observation data. The more
+points used for cross-validation, the longer the time needed for
+computation. Empirical testing indicates a threshold of a maximum of
+100 points is recommended. Note that cross validation can run very
+slowly if more than 100 observations are used. The cross-validation
+output reports <i>mean</i> and <i>rms</i> of the residuals from the
+true point value and the estimated from the interpolation for a fixed
+series of <b>lambda_i</b> values. No vector nor raster output will be
+created when cross-validation is selected.
 
 
 <h2>EXAMPLES</h2>
@@ -81,8 +97,8 @@ when cross-validation is selected.
 v.surf.bspline input=point_vector output=interpolate_surface method=bicubic
 </pre></div>
 
-A bicubic spline interpolation will be done and a vector points map with estimated
-(i.e., interpolated) values will be created. 
+A bicubic spline interpolation will be done and a vector points map
+with estimated (i.e., interpolated) values will be created.
 
 <h3>Basic interpolation and raster output with a longer spline step</h3>
 
@@ -90,10 +106,11 @@ A bicubic spline interpolation will be done and a vector points map with estimat
 v.surf.bspline input=point_vector raster=interpolate_surface sie=25 sin=25
 </pre></div>
 
-A bilinear spline interpolation will be done with a spline step length of 25 map
-units. An interpolated raster map will be created at the current region resolution.
+A bilinear spline interpolation will be done with a spline step length
+of 25 map units. An interpolated raster map will be created at the
+current region resolution.
 
-<h3>Estimation of <b><i>lambda_i</i></b> parameter with a cross validation proccess</h3>
+<h3>Estimation of lambda_i parameter with a cross validation proccess</h3>
 
 <div class="code"><pre>
 v.surf.bspline -c input=point_vector 
@@ -105,31 +122,54 @@ v.surf.bspline -c input=point_vector
 v.surf.bspline input=point_vector sparse=sparse_points output=interpolate_surface
 </pre></div>
 
-An output map of vector points will be created, corresponding to the sparse vector map, with interpolated values.
+An output map of vector points will be created, corresponding to the
+sparse vector map, with interpolated values.
 
 <h3>Using attribute values instead Z-coordinates</h3>
+
 <div class="code"><pre>
 v.surf.bspline input=point_vector raster=interpolate_surface layer=1 column=attrib_column
 </pre></div>
 
-The interpolation will be done using the values in attrib_column, in the
-table associated with layer 1.
+The interpolation will be done using the values
+in <i>attrib_column</i>, in the table associated with layer 1.
 
 <h3>North carolina location example using Z-coordinates for interpolation</h3>
+
 <div class="code"><pre>
-v.surf.bspline --o --v input=elev_lid792_bepts@PERMANENT raster=elev_lid792_rast sie=5 sin=5 method=bicubic lambda_i=0.1 -z
+v.surf.bspline input=elev_lid792_bepts@PERMANENT raster=elev_lid792_rast sie=5 sin=5 method=bicubic lambda_i=0.1 -z
 </pre></div>
 
 
 <h2>BUGS</h2>
+
 Known issues:
-<p>In order to avoid RAM memory problems, an auxiliary table is needed for
-recording some intermediate calculations. This requires the "<b>GROUP BY</b>"
-SQL function is used, which is not supported by the "<b>dbf</b>" driver. For
-this reason, vector map output "<b><i>output=</i></b>" is not permitted with the
-DBF driver. There are no problems with the raster map output from the DBF
-driver.
 
+<p>
+In order to avoid RAM memory problems, an auxiliary table is needed
+for recording some intermediate calculations. This requires
+the <i>GROUP BY</i> SQL function is used, which is not supported by
+the DBF driver. For this reason, vector map output
+(<b>output</b>) is not permitted with the DBF driver. There are
+no problems with the raster map output from the DBF driver.
+
+<h2>REFERENCES</h2>
+
+<ul>
+  <li>Brovelli M. A., Cannata M., and Longoni U.M., 2004, LIDAR Data
+    Filtering and DTM Interpolation Within GRASS, Transactions in GIS,
+    April 2004, vol. 8, iss. 2, pp. 155-174(20), Blackwell Publishing Ltd</li>
+  <li>Brovelli M. A. and Cannata M., 2004, Digital Terrain model
+    reconstruction in urban areas from airborne laser scanning data: the
+    method and an example for Pavia (Northern Italy). Computers and
+    Geosciences 30, pp.325-331</li>
+  <li>Brovelli M. A e Longoni U.M., 2003, Software per il filtraggio di
+    dati LIDAR, Rivista dell'Agenzia del Territorio, n. 3-2003, pp. 11-22
+    (ISSN 1593-2192)</li>
+  <li>Antolin R. and Brovelli M.A., 2007, LiDAR data Filtering with GRASS GIS for the 
+    Determination of Digital Terrain Models. Proceedings of Jornadas de SIG Libre,
+    Girona, Espa&ntilde;a. CD ISBN: 978-84-690-3886-9</li>
+</ul>
 
 <h2>SEE ALSO</h2>
 
@@ -138,32 +178,11 @@ driver.
 <a href="v.surf.rst.html">v.surf.rst</a>
 </em>
 
-
 <h2>AUTHORS</h2>
 
-Original version in GRASS 5.4: (s.bspline.reg)
-<br>
-Maria Antonia Brovelli, Massimiliano Cannata, Ulisse Longoni, Mirko Reguzzoni
-<p>Update for GRASS 6.X and improvements:
-<br>
-Roberto Antolin
-
-
-<h2>REFERENCES</h2>
-
-Brovelli M. A., Cannata M., and Longoni U.M., 2004, LIDAR Data
-Filtering and DTM Interpolation Within GRASS, Transactions in GIS,
-April 2004, vol. 8, iss. 2, pp. 155-174(20), Blackwell Publishing Ltd
-<p>Brovelli M. A. and Cannata M., 2004, Digital Terrain model
-reconstruction in urban areas from airborne laser scanning data: the
-method and an example for Pavia (Northern Italy). Computers and
-Geosciences 30, pp.325-331
-<p>Brovelli M. A e Longoni U.M., 2003, Software per il filtraggio di
-dati LIDAR, Rivista dell'Agenzia del Territorio, n. 3-2003, pp. 11-22
-(ISSN 1593-2192)
-<p>Antolin R. and Brovelli M.A., 2007, LiDAR data Filtering with GRASS GIS for the 
-Determination of Digital Terrain Models. Proceedings of Jornadas de SIG Libre,
-Girona, Espa&ntilde;a. CD ISBN: 978-84-690-3886-9 <br>
+Original version (s.bspline.reg) in GRASS 5.4:
+Maria Antonia Brovelli, Massimiliano Cannata, Ulisse Longoni, Mirko Reguzzoni<br>
+Update for GRASS 6 and improvements: Roberto Antolin
 
 <p>
 <i>Last changed: $Date$</i>