[scripts] AggSetCoord: -c option (fixed coords)

scripts/owlps-aggsetcoord.pl

@@ -10,28 +10,44 @@ owlps-aggsetcoord - set the coordinates in an aggregation CSV file
 B<owlps-aggsetcoord>
 [ B<-h> | B<-V> ]
 [ B<-v> ]
+[ B<-c> <I<coordinates>> ]
 [ B<-m> <I<mac>> ]
 [ <I<aggregation_file>> ]
 
 
 =head1 DESCRIPTION
 
-B<owlps-aggsetcoord> automatically filters an aggregation file and interpolates
-the blank coordinates according to the previous and next known coordinates and
-their timestamps, assuming the mobile moves at a constant speed between two
+B<owlps-aggsetcoord> is a tool to set the coordinates of mobile devices in a CSV
+aggregation file, in an automated way. It works only with lines containing
+positioning requests; the lines containing other types of requests are left
+untouched. Furthermore, only the default values of the coordinates will be
+treated; a non-default coordinate will always be left untouched. Note that the
+default coordinate in OwlPS is registered in aggregation files as "0.00",
+therefore this program considers the string "0.00" as the default value
+corresponding to an undefined coordinate. Zero coordinates are not prevented,
+but you have to write them in another way in your input file, such as "0",
+"00.00", "0.0", "0.000", etc.
+
+By default, B<owlps-aggsetcoord> uses the coordinates already present in the
+input file (manually set by the user, most of the time) to interpolate the
+coordinates of lines containing default values. A given coordinate is
+interpolated according to the previous and next known coordinates and their
+timestamps, assuming the mobile moves at a constant speed between two
 timestamps. The interpolation is done in 3 dimensions, each dimension being
 interpolated independently.
 
-Note that the default coordinate in OwlPS is registered in aggregation files as
-"0.00", therefore this program considers the string "0.00" as an undefined
-coordinate. Zero coordinates are not prevented, but you have to write them in
-another way in your input file, such as "0", "00.00", "0.0", "0.000", etc.
+Alternatively, using the B<-c> option will disable interpolation but apply an
+arbitrary set of coordinates to the lines containing only default values.
 
 In theory, you can provide more than one I<aggregation_file> at once, but don't
 do that unless you really know what you're doing. The (list of) aggregation file
 name(s) I<must> be placed after the options. If no file is provided, the
 standard input is read.
 
+The results are written on the standard output. It is advised to use graphical
+diff tools such as I<vimdiff> to visualise the differences between the input
+file and the result and make sure it corresponds to what was expected.
+
 
 =head1 LIMITATIONS
 
@@ -60,6 +76,12 @@ Print version message and exit.
 
 Turn on verbose mode (displays a trace on the standard error).
 
+=item B<-c> <I<coordinates>>
+
+Apply I<coordinates> to every positioning request with default X, Y and Z. A
+line in which at least one of the three coordinates is set to a non-default
+value will be left untouched. I<coordinates> is a string "X;Y;Z".
+
 =item B<-m> <I<mac>>
 
 Work only on positioning requests transmitted by MAC address I<mac>.
@@ -117,6 +139,11 @@ my $verbose;
 # Selected transmitter's MAC address (will stay undefined if -m was not used)
 my $selected_mac;
 
+# New coordinates to apply to the selected lines (will stay undefined if -c was
+# not used)
+my $new_coordinates;
+my ($new_x, $new_y, $new_z);
+
 # Current line
 my $cur_line;
 
@@ -290,7 +317,7 @@ sub apply_interpolation($$$$$$) {
 ## Option parsing ##
 
 $Getopt::Std::STANDARD_HELP_VERSION = 1;
-use constant OPTIONS => 'hm:vV';
+use constant OPTIONS => 'c:hm:vV';
 my %options;
 if (!getopts(OPTIONS, \%options)) {
     HELP_MESSAGE(*STDERR);
@@ -311,6 +338,11 @@ if ($options{'V'}) {
 $verbose      = $options{'v'};
 $selected_mac = $options{'m'};
 
+$new_coordinates = $options{'c'};
+if (defined($new_coordinates)) {
+    ($new_x, $new_y, $new_z) = split_point_3d($new_coordinates);
+}
+
 
 ## Main loop: read lines ##
 
@@ -373,6 +405,34 @@ while ($cur_line = <>) {
     }
 
 
+    # The user specified a coordinate to apply to every pertinent line (-c
+    # option): we print it immediately (we are sure not to have any previous
+    # lines in memory, since we don't do that in this mode)
+    if (defined($new_coordinates)) {
+        # If the current line is fully incomplete, we reconstitute it with the
+        # new coordinates
+        if (is_blank($x, $y, $z)) {
+            print($csv_format, ";",
+                  $mac,       ";",
+                  $type,      ";",
+                  $nb_pkt,    ";",
+                  $timestamp, ";",
+                  $new_x,     ";",
+                  $new_y,     ";",
+                  $new_z,     ";",
+                  $end_line
+            );
+        }
+        # If the current line has at least one of its coordinates to a
+        # non-default value, just print it
+        else {
+            print $cur_line;
+        }
+        # In either case, jump to the next line
+        next;
+    }
+
+
     # No previous line in memory: we might have got a chance to get rid of the
     # current line right now
     if (@prev_lines == 0) {