#ifndef pz_plot_gauge_H
#define pz_plot_gauge_H

/* Plotting routines for gauges (scale icons) */
/* Last edited on 2008-02-08 12:48:45 by stolfi */

#include <pz_window.h>
#include <pz_types.h>
#include <pz_plot.h>

#include <argparser.h>
#include <pswr.h>

/* PLOTTING DIMENSIONAL GAUGES

  The following procedures draw "gauges", i.e. pictorial
  representations of a filtering scale or a similar linear dimension.
  The representation may be the graph of the filtering kernel, a
  circle with critical or characteristic radius, a scale bar, etc..
  
  The {pz_plot_gaussian_kernel} and {pz_plot_critical_circle
  procedure} draw the icon within a rectangle of specified {width} and
  {height}, with its bottom side centered on the point {(x,y)}. All
  these dimensions are in units of the current coordinate system. The
  icon is drawn with the specified {lineWidth} (in mm), and the
  current line style and color. The line drawing is supressed in
  {lineWidth} is zero.

  If {dotStep} and {dotSize} are positive, the procedure also plots
  round dots along the graph, spaced {dotStep} in the horizontal
  direction, using the current fill color.  The dots' diameter will be 
  {dotSize} times the current line width. */

void pz_plot_gaussian_kernel
  ( PSStream *f,
    double lambda,
    double x,
    double y,
    double width,
    double height,
    double lineWidth,
    double dotStep,   /* (:= 0.0) */
    double dotSize    /* (:= 0.0) */
  );
  /* Draws the graph of a gaussian with standard deviation {lambda},
    clipped to the specified {width} and scaled to fit 
    the specified {height}.  The origin of the graph's coordinate system
    will be at {(x,y)}. */

void pz_plot_critical_circle
  ( PSStream *f,
    double radius,
    double x,
    double y,
    double width,
    double height,
    double lineWidth,
    double dotStep,   /* (:= 0.0) */
    double dotSize    /* (:= 0.0) */
  );
  /* Draws a circle with specified {radius}.  The circle is centered in
    the specified rectangular window if possible; otherwise only the
    top part of it is shown, clipped to the rectangle. */

void pz_plot_scale_bar(
    PSStream *f,
    double barStep,
    unsigned barCount,
    double x,
    double y,
    double lineWidth,
    double tickLength 
  );
  /* Draws a horizontal H-bar of length {barCount*barStep}, with ticks 
    every {barStep}, centered at the point {(x,y)}.  Uses the current
    line style and color. */

typedef enum { NoGauge, KernelGauge, CircleGauge } pz_plot_gauge_style_t;

typedef struct
  pz_plot_gauge_options_t
    { pz_plot_gauge_style_t style;       /* Icon type. */
      unsigned barCount;                 /* Number of segments in scale bar. */
      double dotStep;                    /* Spacing of dots on icon (0 = no dots). */
      double tickLength;                 /* Length of tick marks on scale bar. */
    } pz_plot_gauge_options_t;
    /* See {pz_plot_gauge} below. */

void pz_plot_gauge ( PSStream *f, double lambda, pz_plot_gauge_options_t *o );
  /* Plots an iconic indication of filtering scale, at the 
    lower left corner of the current drawing of {f}.
    
    The {NoGauge} style icon is no icon at all, just a scale bar.
    
    The {KernelGauge} style icon is the graph of a Gaussian with deviation
    {lambda}, clipped to {2.5*lambda} in each direction, with the
    scale bar as the horizontal axis.
    
    The {CircleGauge} style icon is a circle that is critical for the
    filtering scale {lambda} (i.e. with radius {sqrt(e/2)*lambda}),
    above a scale bar.
    
    The scale bar is an horizontal line with length {o.barCount*lambda} and
    ticks every {lambda}. In all styles, if {o.barCount == 0}, the scale bar
    is not plotted.
    
    If {o.dotStep} is positive, the procedure also puts down dots with
    that spacing along the kernel graph or circle. This parameter is
    irrelevant if {o.style == None}.

    The icon will be clipped or supressed if it would be too big
    compared to the drawing size. Ditto for the scale bar. */
  
#define pz_plot_gauge_OPTIONS_HELP \
    "  [ -scaleBar COUNT | \\\n" \
    "    { -scaleIcon {None|Bar|Circle|Kernel} [ -scaleDotStep NUM ] } \\\n" \
    "  ]"

pz_plot_gauge_options_t *pz_plot_parse_gauge_options ( argparser_t *pp );
  /* Parses scale icon parameters from the command line input,
    as shown in the {pz_plot_gauge_OPTIONS_HELP} string above.
    
    {None} is nothing at all; {Bar} produces only a scale
    bar with one segment (same as {-scaleBar 1}); {Circle} includes
    {-scaleBar 1}; and {Kernel} includes {-scaleBar 2}. */

#endif