watchpoint function target

A watchpoint can be set for the target value of a function. The function is evaluated at the beginning and end of each line segment in the plot. If the endpoint values span the target value, the [x,y] hit coordinates are reported after linear interpolation.

     plot FOO watch func(...)=targetvalue

The trivial example below sets a watchpoint target that will place a label where the curve crosses the line y = ax + b. When evaluated at [x,y] the function Line(a,b) returns the deviation of the current y coordinate from the value ax + b. Thus when evaluated at an intersection of the plotted curve with the line ax+b, the function returns zero. We set this as the watch target.

     Line(x,y) = (a*x + b) - y
     plot cos(x) watch Line(x,y)=0,   a*x + b

During evaluation the corresponding values of x, y, and z at that point are available to the function whether or not they are named parameters. So the variant below achieves the same result as the previous example.

     Line(dummy1,dummy1) = dummy1*x + dummy2 - y
     plot cos(x) watch Line(a,b)=0,   a*x + b

The same again, using a function block instead of an in-line function.

    function $Line() << EOF
       return (a*x + b) - y
    EOF
    plot cos(x) watch $Line()=0,   a*x + b

A more interesting use is to constrain the placement of contour labels on a contour plot. Gnuplot has several options to modify the automatic placement of contour labels see set cntrlabel) but these may not be satisfactory for labelling crowded plots. You can instead place labels only at positions where a watchpoint function target is satisfied.

Here is an example where a straight line across the area of the plot is chosen and contour labels are placed only where a contour crosses one that line. For the complete worked example see demo watch_contours.dem.

     set style watchpoint labels center nopoint font ",9"
     set style textbox noborder opaque margins 0.5, 0.5
     line(a,b) = a*x+b - y
     a = 0.6; b = 0.5

     set contours
     set cntrparam levels incr 0, .2, 4
     set view map

     splot f(x,y) with lines nosurface watch line(a,b)=0 label sprintf("%.1f",z)

Each label is generated using the z value of that contour. The default watchpoint labels " x : y " would not be useful for this plot so we provide a formatting function that prints the z value of the contour.