changelog bump, release

The image is intended to be background, so I want it to be rendered first, with
everything else on top of it

Changes

@@ -1,4 +1,16 @@
-feedgnuplot (1.42) unstable; urgency=medium
+feedgnuplot (1.44)
+
+  * --image draws its output beneath everything else
+
+ -- Dima Kogan <dima@secretsauce.net>  Tue, 20 Jun 2017 16:44:30 -0700
+
+feedgnuplot (1.43)
+
+  * Added --image
+
+ -- Dima Kogan <dima@secretsauce.net>  Mon, 19 Jun 2017 13:12:38 -0700
+
+feedgnuplot (1.42)
 
   * Data can now come from STDIN or files on the cmdline.
     This fixes a regression. Self-plotting data files work again

bin/feedgnuplot

@@ -15,7 +15,7 @@ use Text::ParseWords; # for shellwords
 use Pod::Usage;
 use Time::Piece;
 
-my $VERSION = 1.42;
+my $VERSION = 1.44;
 
 my %options;
 interpretCommandline();
@@ -109,6 +109,7 @@ sub interpretCommandline
              'style=s{2}', 'curvestyle=s{2}', 'curvestyleall=s', 'styleall=s', 'with=s', 'extracmds=s@', 'set=s@', 'unset=s@',
              'square!', 'square_xy!', 'hardcopy=s', 'maxcurves=i', 'monotonic!', 'timefmt=s',
              'equation=s@',
+             'image=s',
              'histogram=s@', 'binwidth=f', 'histstyle=s',
              'terminal=s',
              'rangesize=s{2}', 'rangesizeall=i', 'extraValuesPerPoint=i',
@@ -419,6 +420,27 @@ sub interpretCommandline
       }
     }
   }
+
+  # deal with --image. I just fill in --equation, and reverse the y extents if
+  # none are explicitly given
+  if( defined $options{image} )
+  {
+      # images generally have the origin at the top-left instead of the
+      # bottom-left, so given nothing else, I flip the y axis
+      if( !defined $options{ymin} && !defined $options{ymax} &&
+          ! any { /^ *yrange\b/ } @{$options{set}} )
+      {
+          push @{$options{set}}, "yrange [:] reverse";
+      }
+
+      if ( ! -r $options{image} )
+      {
+          die "Couldn't read image '$options{image}'";
+      }
+
+      unshift @{$options{equation}}, qq{"$options{image}" binary filetype=auto flipy with rgbimage};
+      delete $options{image};
+  }
 }
 
 sub getGnuplotVersion
@@ -1729,6 +1751,17 @@ times.
 
 =item
 
+C<--image filename>
+
+Overlays the data on top of a raster image given in C<filename>. This is passed
+through to gnuplot via C<--equation>, and is not interpreted by C<feedgnuplot>
+other than checking for existence. Usually images have their origin at the
+top-left corner, while plots have it in the bottom-left corner instead. Thus if
+the y-axis extents are not specified (C<--ymin>, C<--ymax>, C<--set 'yrange
+...'>) this option will also flip around the y axis to make the image appear
+properly. Since this option is just a passthrough to gnuplot, finer control can
+be achieved by passing in C<--equation> and C<--set yrange ...> directly.
+
 C<--equation xxx>
 
 Gnuplot can plot both data and symbolic equations. C<feedgnuplot> generally
@@ -1993,11 +2026,21 @@ in a Thinkpad.
 
 =head2 Plotting points on top of an existing image
 
-This can be done by using C<--equation> to pass arbitrary plot input to gnuplot:
+This can be done with C<--image>:
+
+ $ < features_xy.data
+   feedgnuplot --points --domain --image "image.png"
+
+or with C<--equation>:
 
  $ < features_xy.data
    feedgnuplot --points --domain
-     --equation '"image.png" binary filetype=png flipy with rgbimage'
+     --equation '"image.png" binary filetype=auto flipy with rgbimage'
+     --set 'yrange [:] reverse'
+
+The C<--image> invocation is a convenience wrapper for the C<--equation>
+version. Finer control is available with C<--equation>.
+
 
 Here an existing image is given to gnuplot verbatim, and data to plot on top of
 it is interpreted by feedgnuplot as usual. C<flipy> is useful here because

completions/bash/feedgnuplot

@@ -21,6 +21,7 @@ complete -W               \
     --set                 \
     --unset               \
     --equation            \
+    --image               \
     --geometry            \
     --hardcopy            \
     --help                \

completions/zsh/_feedgnuplot

@@ -33,6 +33,7 @@ _arguments -S
     '*--set[Additional 'set' gnuplot commands]:set-option'                        \
     '*--unset[Additional 'unset' gnuplot commands]:unset-option'                  \
     '*--equation[Raw symbolic equation]:equation'                                 \
+    '--image[Image file to render beneath the data]:image'                        \
     '--square[Plot data with square aspect ratio]'                                \
     '--square_xy[For 3D plots, set square aspect ratio for ONLY the x,y axes]'    \
     '--hardcopy[Plot to a file]:filename'                                         \