---

plotspecification.h

Go to the documentation of this file.

#ifndef __PLOT_SPECIFICATION_H__
#define __PLOT_SPECIFICATION_H__

#include <utility>
#include <string>
using std::string;

// Uses roundabout paths to the current directory to avoid Cray C bug
#include "../src/matriximagefactory.h"
#include "../src/pointermap.h"
#include "../src/allocatingpointer.h"
#include "../src/tnt_gnuplot.h"
#include "../src/msg.h"
#include "../src/parammap.h"
#include "../src/stringutils.h"
#include "../src/matrixhistogram.h"
#include "../src/histogramimage.h"
#include "../src/scale.h"


/* Helper functions, without a real home */ 


template<class Color>
Color lookup_color
(const ParamMap& params, const string& basename, const Color& default_val)
{
  /* Assumes there will be three parameters named with the given
     suffixes, one for each color component. */
  const string R_param = basename+"_R";
  const string G_param = basename+"_G";
  const string B_param = basename+"_B";
  const double R = params.get_with_default(R_param.c_str(), default_val.red());
  const double G = params.get_with_default(G_param.c_str(), default_val.green());
  const double B = params.get_with_default(B_param.c_str(), default_val.blue());
  return Color(R,G,B);
}



template<class SubRegion>
SubRegion lookup_subregion
(const ParamMap& params, const SubRegion& default_val)
{
  const int s_c  = params.get_with_default("start_c", -1);
  const int s_r  = params.get_with_default("start_r", -1);
  const int e_c  = params.get_with_default("end_c",   -1);
  const int e_r  = params.get_with_default("end_r",   -1);

  if (s_c<0 || s_r<0 || e_c<0 || e_r<0)
    return default_val;
  return   SubRegion(-s_c,-s_r,-e_c,-e_r);
}



namespace  Plot {


  
template<class ParamMapType>
ParamMapType* PlotSpec_params(const string& child_name,
                              ParamMapType& parent,
                              const string& strength_name="",
                              const string& color_name="",
                              const string& confidence_name="")
{
  /* The dynamic_cast is required only because new_child has to return
     the base type only (to work with some compilers, e.g. Cray C++) */
  ParamMapType* p  = dynamic_cast<ParamMapType*>(parent.new_child(child_name));
  PlotSpec_child_map(*p,"Strength",strength_name);
  PlotSpec_child_map(*p,"Color",color_name);
  PlotSpec_child_map(*p,"Confidence",confidence_name);
  PlotSpec_child_map(*p,"Histogram","",false);
  return p;
}



template<class ParamMapType>
ParamMapType* PlotSpec_child_map(ParamMapType& parent, const string& childname, const string& matrixname="",
                                 bool setmatrixname=true)
{
  ParamMapType* c = dynamic_cast<ParamMapType*>(parent.new_child(childname,true)); assert(c);
  if (setmatrixname) c->set_local("name",matrixname);
  return c;
}


template <class Matrix, class String=string, class ScaleType=Scale::Linear<>,
          class MatrixTableType=PointerMap<Matrix>,
          class ParameterMapType=ParamMap >
class PlotSpecification {
  typedef const String cStr;
  typedef ParameterMapType ParamMapType;
  typedef Histo::OneDHistogram<> Histogram;
  typedef Plot::RGBPixel<> ColorType;
  
public:
  typedef MatrixTableType  MatrixTable;

private:
  
  PlotSpecification(cStr& objectname, const MatrixTable& maptable, cStr& name, ParamMapType* params_)
    : plotname(name), objname(objectname), params(params_,true), maps(&maptable) { }

public:
  typedef Boundary::AAArbitraryRectangle<double,int> SubRegion;

  const Matrix* reference_mapptr() const {
    assert (maps->begin()!=maps->end());
    return maps->begin()->second;
  }
  
  template <class DerivedFromParamMap>
  PlotSpecification(cStr& objectname, const MatrixTable& maptable, cStr& name, DerivedFromParamMap& parentparams,
                    const string& strength_name="", const string& color_name="", const string& confidence_name="")
    : plotname(name), objname(objectname),
      params(PlotSpec_params(name,parentparams,strength_name,color_name,confidence_name),true),
      maps(&maptable) { }

  ~PlotSpecification() {  }
  
  const string name()       const {  return plotname;  }

  const string objectname() const {  return objname;  }

  bool                 save_matrix  (const string filebase, const MatrixTable* tempmaps=0,
                                     const SubRegion* overriding_region=0) const;
  bool                 gnuplot_image(const string filebase, const MatrixTable* tempmaps=0,
                                     const SubRegion* overriding_region=0) const;
  Plot::MatrixImage<>* bitmap_image(const double master_scale=-1, const SubRegion* reference=0, const MatrixTable* tempmaps=0,
                                    const SubRegion* overriding_region=0,
                                    const int border_width=-1, const string overriding_colorspec="") const;
  Plot::AARImage<>*    bitmap_histogram(const double master_scale, const ParamMap& defaults, const SubRegion* reference,
                                        const MatrixTable* tempmaps=0, const string& name="Histogram") const;

  
  static void message(Msg::MessageLevel m, const string& s, const bool terminate=True) {
    // Written in this awkward fashion to avoid bug (ICE) in GCC 2.95
    const bool nonnull = (mhp!=0 && (*mhp)); 
    if (nonnull) (**mhp)(m,s,terminate);
  }

  template <class T>
  T lookup_param(const string& name, const T& default_val) const 
    {  return lookup_param(*params,name.c_str(),default_val);  }
  
  /* Cascading lookup command, with up to two levels of backup maps.
     The routine retrieves the parameter from each of the given maps,
     in order, returning the first value found that differs from the
     given default. If none were found or none differed, the default
     value itself is returned.

     This routine could possibly be used (within the ParameterMap
     class routine get_with_default) as the basis for a
     general-purpose defaults system, with each ParameterMap knowing
     the name of its set of defaults, to which get_with_default turns
     when only a default value is found (e.g. if never set
     explicitly).
  */
  template <class T>
  T lookup_param(const ParamMap& params1, const string& name, const T& default_val,
                 const ParamMap* params2=0, const ParamMap* params3=0) const {
    const T p1=params1.get_with_default(name.c_str(),default_val);
    if (p1!=default_val || !params2) return p1;

    const T p2=params2->get_with_default(name.c_str(),default_val);
    if (p2!=default_val || !params3) return p2;
    
    return     params3->get_with_default(name.c_str(),default_val);
  }
  

  ParamMapType&       param_map()       {  return *(params.valueptr());  }
  const ParamMapType& param_map() const {  return *params;               }
  
private:
  Plot::AARImage<>* histogram_image(const double master_scale,
                                    const SubRegion* reference,
                                    const ParamMap&  histoparams,
                                    const Histogram& histo) const;
    
  double compute_size_scale(const double master_scale, const double specified_scale,
                            const SubRegion& paramregion, const SubRegion* reference) const;

  const Matrix* map_getptr(const string& name, const MatrixTable* tempmaps=0, bool warn=true) const {
    if (name=="") return 0;
    const Matrix* p  = (tempmaps ? tempmaps->getptr(name) : 0);
    const Matrix* pp = (p? p : maps->getptr(name) );
    if (warn && !pp && name!=lastwarning && name!=previouswarning) {
      message(Msg::Warning, "Could not find map matrix named '" + name
              + "' when plotting " + plotname + " for " + objname );
      previouswarning=lastwarning;
      lastwarning=name;
    }
    return pp;
  }
  

  /* Convenience macro which looks up the map name under the given
     paramname in the given parameter map */
  const Matrix* map_getptr(const ParamMap& params, const MatrixTable* tempmaps=0,
                           bool warn=true, const string& paramname="name") const
    {  return map_getptr(lookup_param(params, paramname, string()),tempmaps, warn);  }
  
  String plotname, objname;
  
  OwningPointer<ParamMapType> params;
  const MatrixTable* maps;
  
  mutable string lastwarning,previouswarning;

  static Msg::LevelHandler<>** mhp;
};


/* Static variables */
template <class Matrix,class String,class ScaleType,class MatrixTableType,class ParameterMapType>
Msg::LevelHandler<>**
PlotSpecification<Matrix,String,ScaleType,MatrixTableType,ParameterMapType>::
mhp=&(Msg::LevelHandler<>::default_instance());



template <class Matrix,class String,class ScaleType,class MatrixTableType,class ParameterMapType>
bool
PlotSpecification<Matrix,String,ScaleType,MatrixTableType,ParameterMapType>::
gnuplot_image(const string filebase, const MatrixTable* tempmaps,
              const SubRegion* overriding_region) const
{
  const string  outname = (filebase=="" ? "" : filebase+"_"+objectname()+"_"+name()+".ps");
  const string  title   = objectname() + " " + name();
  const Matrix* s = map_getptr(params->get_child("Strength"), tempmaps);
  const Matrix* c = map_getptr(params->get_child("Color"),    tempmaps);
  const SubRegion paramregion = lookup_subregion(*params,SubRegion());
  const SubRegion subregion   = (overriding_region? *overriding_region : paramregion);
  typedef typename Matrix::value_type T;
  typedef mat::MatrixInterface<T> BaseMatrixType;
  typedef mat::MatrixAdapter<BaseMatrixType> MatrixWindow;
  
  const string messages = (s?  mat::gnuplot(MatrixWindow(*s,1.0,subregion),title,outname) :
                           (c? mat::gnuplot(MatrixWindow(*c,1.0,subregion),title,outname) : string()));

  if (messages != "") {
    message(Msg::Warning, "Gnuplot wrapper for " + title + ": " + messages);
    return false;
  }
  
  return true;
}



template <class Matrix,class String,class ScaleType,class MatrixTableType,class ParameterMapType>
bool
PlotSpecification<Matrix,String,ScaleType,MatrixTableType,ParameterMapType>::
save_matrix(const string filebase, const MatrixTable* tempmaps,
            const SubRegion* overriding_region) const
{
  /* Mostly copied from gnuplot_image */
  const string  outname = (filebase=="" ? "" : filebase+".matrix");
  const string  title   = objectname() + " " + name();
  const Matrix* s = map_getptr(params->get_child("Strength"), tempmaps);
  const Matrix* c = map_getptr(params->get_child("Color"),    tempmaps);
  const SubRegion paramregion = lookup_subregion(*params,SubRegion());
  const SubRegion subregion   = (overriding_region? *overriding_region : paramregion);
  typedef typename Matrix::value_type T;
  typedef mat::MatrixInterface<T> BaseMatrixType;
  typedef mat::MatrixAdapter<BaseMatrixType> MatrixWindow;

  std::ofstream matrixfile(outname.c_str());
  if (!matrixfile) {
    message(Msg::Warning, "Could not open matrix file " + outname);
    return false;
  }
  if (!c && !s){
    message(Msg::Warning, "Nothing to plot");
    return true;
  }
  MatrixWindow submatrix((s? *s : *c),1.0,subregion);
  
  /* Octave-compatible header */
  matrixfile
    << "# Created from " << title << std::endl
    << "# name: "        << name() << std::endl
    << "# type: matrix"  << std::endl
    << "# rows: "        << submatrix.nrows() << std::endl
    << "# columns: "     << submatrix.ncols() << std::endl;

  stream_output(MatrixWindow((s? *s : *c),1.0,subregion),matrixfile);

  return true;
}



template <class Matrix,class String,class ScaleType,class MatrixTableType,class ParameterMapType>
double
PlotSpecification<Matrix,String,ScaleType,MatrixTableType,ParameterMapType>::
compute_size_scale(const double master_scale, const double specified_scale,
                   const SubRegion& paramregion, const SubRegion* reference) const
{
  if (!reference) return specified_scale;

  if (master_scale>0) {
    const double height  = (!paramregion.isinfinite()? paramregion.height() : reference_mapptr()->nrows());
    const double width   = (!paramregion.isinfinite()? paramregion.width()  : reference_mapptr()->ncols());
    const int    hfactor = int(master_scale*reference->height()/height);
    const int    wfactor = int(master_scale*reference->width()/width);
    const int    factor  = std::min(hfactor,wfactor);
    if (factor>0) return factor;
  }
  
  return specified_scale;
}



template <class T>
struct normalized_difference_fnobj : public std::binary_function<T, T, T> {
  T operator()(const T& x, const T& y) const { return 0.5+0.5*(x-y); }
};


template <class Matrix,class String,class ScaleType,class MatrixTableType,class ParameterMapType>
Plot::MatrixImage<>*
PlotSpecification<Matrix,String,ScaleType,MatrixTableType,ParameterMapType>::
bitmap_image(const double master_scale, const SubRegion* reference,
             const MatrixTable* tempmaps, const SubRegion* overriding_region,
             const int border_width, const string overriding_colorspec) const
{
  /* Get values for parameters (or use specified defaults if none) */
  const Tristate  paper_based = lookup_param(*params,"ppm_paper_based_colors", False);
  const double    subplot_hue = lookup_param(*params,"ppm_subplot_hue",        0.0);
  const string    colorspec   =(overriding_colorspec!=""? overriding_colorspec :
                                lookup_param(*params,"colorspec",              string("RYW")));
  const ColorType bordercolor = lookup_color(*params,"ppm_bg",  AARImage<>::default_border);
  const int       border      = (border_width>=0 ? border_width : lookup_param(*params,"ppm_border", 1));
  const ParamMap& strength    = params->get_child("Strength");
  const ParamMap& color       = params->get_child("Color");
  const ParamMap& confidence  = params->get_child("Confidence");
  const SubRegion paramregion = lookup_subregion(*params,SubRegion());
  const SubRegion subregion   = (overriding_region? *overriding_region : paramregion);
  const double    size_scale  = compute_size_scale(master_scale,lookup_param(*params,"size_scale", 1.0),
                                                   paramregion,reference);

  Plot::ColorLookupFactory<>::result_type* clu =
    Plot::ColorLookupFactory<>(paper_based,subplot_hue)(colorspec);
  typedef typename Matrix::value_type T;
  typedef mat::MatrixInterface<T> BaseMatrixType; 
  const Plot::MatrixImageFactory<BaseMatrixType,T,ScaleType>
    factory(paper_based,size_scale,border,subregion,clu,bordercolor);

  
  /* Compute value with respect to reference, if any */
  typedef normalized_difference_fnobj<T>                               RefFunType;
  typedef mat::MatrixInterfaceBinaryAdapter<BaseMatrixType,RefFunType> BinFunAdapter;
  typedef mat::MatrixInterfaceAdapter<BaseMatrixType>                  MatAdapter;
  const BaseMatrixType*   strengthptr  = map_getptr(strength, tempmaps);
  const BaseMatrixType*   refptr       = map_getptr("__StrengthReference", tempmaps,false);
  const BinFunAdapter*    strength_ref = 0;
  if (strengthptr && refptr) {
    strength_ref = new BinFunAdapter(*strengthptr,*refptr,RefFunType());
    assert (strength_ref);
    strengthptr = strength_ref;
  }

  /* Create image */
  Plot::MatrixImage<>* img =
    factory(strengthptr,
            ScaleType( lookup_param(strength,   "value_scale", 1.0),
                       lookup_param(strength,   "value_offset",0.0)),
            map_getptr(color, tempmaps),
            ScaleType( lookup_param(color,      "value_scale", 1.0),
                       lookup_param(color,      "value_offset",0.0)),
            map_getptr(confidence, tempmaps),
            ScaleType( lookup_param(confidence, "value_scale", 1.0),
                       lookup_param(confidence, "value_offset",0.0)) );
  
  delete clu;
  delete strength_ref;
  
  /* Overlay line plots here? */
  //if (show_overlay)
  
  return img;
}



template <class Matrix,class String,class ScaleType,class MatrixTableType,class ParameterMapType>
Plot::AARImage<>*
PlotSpecification<Matrix,String,ScaleType,MatrixTableType,ParameterMapType>::
bitmap_histogram(const double master_scale, const ParamMap& defaults,
                 const SubRegion* reference, const MatrixTable* tempmaps,
                 const string& name) const
{
  const ParamMap& histoparams = params->get_child(name);
  
  /* The histogram values are determined by the Strength matrix of this plot (optional) */
  const Matrix*   str_mat     = map_getptr(params->get_child("Strength"), tempmaps); 
  
  /* The histogram bins are determined by name, if set, or default to the Color matrix of the plot */
  const ParamMap& colorparams = params->get_child("Color");
  const string    bin_name    = lookup_param(histoparams,"name",string(),&defaults,&colorparams);
  /* Warnings are turned off for this map lookup, to make the global
     default be easy to set even if some areas don't have the
     corresponding map. */
  const Matrix*   bin_mat     = map_getptr(bin_name, tempmaps, false);
  const bool      enabled     = lookup_param(histoparams,"ppm_histograms",True);
  if (!enabled || !bin_mat) return 0; /* No plot needed */

  const int       num_bins    = lookup_param(histoparams,"num_bins",    24  );
  const bool      cyclic      = lookup_param(histoparams,"cyclic",      True);
  ScaleType scale(num_bins);

  if (!str_mat) {  /* Substitute constant matrix for strength */
    typedef mat::MatrixInterfaceConstant<float>  ConstantMatrix;
    ConstantMatrix const_one(1.0,bin_mat->nrows(),bin_mat->ncols());
    return histogram_image(master_scale, reference, histoparams,
                           Histogram(Histo::matrix_histogram(*bin_mat,const_one,num_bins,scale,cyclic)));
  }
  else
    return histogram_image(master_scale, reference, histoparams,
                           Histogram(Histo::matrix_histogram(*bin_mat,*str_mat, num_bins,scale,cyclic)));
}



template <class Matrix,class String,class ScaleType,class MatrixTableType,class ParameterMapType>
Plot::AARImage<>* 
PlotSpecification<Matrix,String,ScaleType,MatrixTableType,ParameterMapType>::
histogram_image(const double master_scale, const SubRegion* reference,
                const ParamMap& histoparams, const Histogram& histo) const
{
  const ColorType bordercolor   = lookup_color(histoparams,"ppm_bg", AARImage<>::default_border);
  const double    range         = lookup_param(histoparams,"range_end",   0.25);
  const bool      vertical      = lookup_param(histoparams,"vertical",    True);
  const double    aspect_ratio  = lookup_param(histoparams,"aspect_ratio",0.25);
  const int       border        = lookup_param(histoparams,"ppm_border",  1   );
  const string    hcolorspec    = lookup_param(histoparams,"histo_colorspec",string(""));
  const string    colorspec     =(hcolorspec!=""? hcolorspec :
                                  lookup_param(histoparams,"colorspec",   string("Hue")));
  const double    subplot_hue   = lookup_param(histoparams,"ppm_subplot_hue", 0.0);
  const Tristate  paper_based   = lookup_param(histoparams,"ppm_paper_based_colors", False);
  const ColorType histobg       = lookup_color(histoparams,"ppm_line",    ColorType());
  const double    psize_scale   = lookup_param(*params,"size_scale", 1.0);
  const SubRegion fakesubregion = SubRegion(0,0,
                                            histo.num_bins()*(vertical? aspect_ratio : 1.0),
                                            histo.num_bins()*(vertical? 1.0 : aspect_ratio));
  const double    size_scale    = compute_size_scale(master_scale,psize_scale,fakesubregion,reference);

  OwningPointer<Plot::ColorLookupFactory<>::result_type> clu
    (Plot::ColorLookupFactory<>(paper_based,subplot_hue)(colorspec),true);

  return new
    Plot::OneDHistogramImage<>(histo,vertical,size_scale,aspect_ratio,
                               range,border,*clu,bordercolor,histobg);
}


} /* namespace Plot */
#endif /* __PLOT_SPECIFICATION_H__ */

---