TwoDMeshPlot.h

Go to the documentation of this file.

/*
*  Copyright (C) 2007 Jolien Creighton, Teviet Creighton
*
*  This program is free software; you can redistribute it and/or modify
*  it under the terms of the GNU General Public License as published by
*  the Free Software Foundation; either version 2 of the License, or
*  (at your option) any later version.
*
*  This program is distributed in the hope that it will be useful,
*  but WITHOUT ANY WARRANTY; without even the implied warranty of
*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
*  GNU General Public License for more details.
*
*  You should have received a copy of the GNU General Public License
*  along with with program; see the file COPYING. If not, write to the
*  Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
*  MA  02111-1307  USA
*/

/********************************* <lalVerbatim file="TwoDMeshPlotHV">
Author: Creighton, T. D.
$Id: TwoDMeshPlot.h,v 1.7 2007/06/08 14:41:52 bema Exp $
**************************************************** </lalVerbatim> */

/********************************************************** <lalLaTeX>

\section{Header \texttt{TwoDMeshPlot.h}}
\label{s:TwoDMeshPlot.h}

Provides routines to plot two-dimensional parameter meshes.

\subsection*{Synopsis}
\begin{verbatim}
#include "TwoDMeshPlot.h"
\end{verbatim}

\noindent This header covers routines that display 2-dimensional
parameter meshes as generated by the routines in \verb@TwoDMesh.h@.
The output is written to a C \verb@FILE@-type stream using
\verb@fprintf()@ The routines do not provide a system-level interface
to open or close file streams; they simply assume that they have been
passed an open, writable stream.  Nonetheless, their use of stream I/O
means that they cannot be included in LAL (although executables, in
particular the \verb@TwoDMesh.h@ test programs, may statically link
against their object files).

******************************************************* </lalLaTeX> */

#ifndef _TWODMESHPLOT_H
#define _TWODMESHPLOT_H

#include <lal/LALStdlib.h>

#ifdef __cplusplus
extern "C" {
#pragma }
#endif

NRCSID( TWODMESHPLOTH, "$Id: TwoDMeshPlot.h,v 1.7 2007/06/08 14:41:52 bema Exp $" );

/********************************************************** <lalLaTeX>
\subsection*{Error conditions}
****************************************** </lalLaTeX><lalErrTable> */
#define TWODMESHPLOTH_ENUL    1
#define TWODMESHPLOTH_EOUT    2
#define TWODMESHPLOTH_EMEM    3
#define TWODMESHPLOTH_EMETRIC 4
#define TWODMESHPLOTH_ENOPLOT 5

#define TWODMESHPLOTH_MSGENUL    "Unexpected null pointer in arguments"
#define TWODMESHPLOTH_MSGEOUT    "Output handle points to a non-null pointer"
#define TWODMESHPLOTH_MSGEMEM    "Memory allocation error"
#define TWODMESHPLOTH_MSGEMETRIC "Non-positive metric"
#define TWODMESHPLOTH_MSGENOPLOT "Nothing to plot"
/******************************************** </lalErrTable><lalLaTeX>

\subsection*{Constants}

\idx[Constant]{TWODMESHPLOTH\_XSIZE}
\idx[Constant]{TWODMESHPLOTH\_YSIZE}
\idx[Constant]{TWODMESHPLOTH\_XMARG}
\idx[Constant]{TWODMESHPLOTH\_YMARG}
\begin{center}\begin{tabular}{|ccp{4.5in}|}\hline
\texttt{<}\textit{name}\texttt{>} & value & description \\
\hline
\tt XSIZE & 540 & \vspace{-1.4ex}Horizontal size of plotting area (points = 1/72$''$) \\
\tt YSIZE & 720 & \vspace{-1.4ex}Vertical size of plotting area (points) \\
\tt XMARG &  36 & \vspace{-1.4ex}Distance from left of page to plotting area (points) \\
\tt YMARG &  36 & \vspace{-1.4ex}Distance from bottom of page to plotting area (points) \\
\hline
\end{tabular}\end{center}
\vspace{-.1in}The values in the table above are stored in the
constants \verb@TWODMESHPLOTH_@\texttt{<}\textit{name}\texttt{>}.

******************************************************* </lalLaTeX> */

#define TWODMESHPLOTH_XSIZE 540 /* horizontal plot size (points) */
#define TWODMESHPLOTH_YSIZE 720 /* vertical plot size (points) */
#define TWODMESHPLOTH_XMARG  36 /* horizontal margin (points) */
#define TWODMESHPLOTH_YMARG  36 /* vertical margin (points) */

/********************************************************** <lalLaTeX>

\subsection*{Types}

\subsubsection*{Structure \texttt{TwoDMeshPlotStruc}}
\idx[Type]{TwoDMeshPlotStruc}

\noindent This structure stores parameters specifying how to plot a
PostScript diagram of the parameter mesh.  The fields are:

\begin{description}
\item[\texttt{REAL4 theta}] Angle from the horizontal direction of the
plot counterclockwise to the $x$-coordinate axis of the mesh, in
degrees.

\item[\texttt{REAL4 xScale, yScale}] Plotting scale of the mesh
coordinate axes, in points per unit $x$ or $y$ (a point is 1/72 of an
inch).

\item[\texttt{REAL4 bBox[4]}] Bounding box surrounding the figure in
plot coordinates, measured in points.

\item[\texttt{BOOLEAN autoscale}] If true, \verb@xScale@ and
\verb@yScale@ will be adjusted so that the drawn figure will lie
within the \verb@bBox@.  If false, \verb@bBox@ will be adjusted to
enclose the figure, given \verb@xScale@ and \verb@yScale@.

\item[\texttt{REAL4 clipBox[4]}] Four components $x_\mathrm{min}$,
$y_\mathrm{min}$, $x_\mathrm{max}$, $y_\mathrm{max}$ (in that order)
specifying the corners of a box in the $x$-$y$ coordinate system
outside of which no marks will be made.  If either max value is less
than or equal to the corresponding min value, \verb@clipBox@ will be
ignored.

\item[\texttt{UINT4 nLevels}] The number of levels of recursive
submeshes to plot.  If zero, the mesh will not be plotted (although
the boundary may be).

\item[\texttt{UINT4 nBoundary}] \emph{half} the number of points to
plot along the boundary of the parameter region.  At least 4 points
are required; if \verb@plotBoundary@$<2$, none will be plotted.

\item[\texttt{INT2 *plotPoints}] An array from \verb@[0]@ to
\verb@[nLevels]@ indicating how to plot the mesh points at each
recursive level: a value of 0 means don't plot mesh points, a positive
value means to plot filled circles of that diameter (in points), a
negative value means to plot empty circles of that diameter (in
points).

\item[\texttt{BOOLEAN *plotTiles}] An array from \verb@[0]@ to
\verb@[nLevels]@ indicating whether to plot the tiles around each mesh
point, at each recursive level.

\item[\texttt{BOOLEAN *plotEllipses}] An array from \verb@[0]@ to
\verb@[nLevels]@ indicating whether to plot the mismatch ellipses
around each mesh point, at each recursive level.

\item[\texttt{TwoDMeshParamStruc *params}] An array from \verb@[0]@ to
\verb@[nLevels]@ of parameter structures used to generate the meshes
at each recursive level (making the assumption that \emph{all}
submeshes of the same level used the same parameters).  In general
only the \verb@getMetric()@ and \verb@mThresh@ fields are used from
parameter structures after the first.
\end{description}

******************************************************* </lalLaTeX> */

typedef struct tagTwoDMeshPlotStruc {
  /* public */
  REAL4 theta;
  REAL4 xScale, yScale;
  REAL4 bBox[4];
  BOOLEAN autoscale;
  REAL4 clipBox[4];
  UINT4 nLevels;
  UINT4 nBoundary;
  INT2 *plotPoints;
  BOOLEAN *plotTiles;
  BOOLEAN *plotEllipses;
  TwoDMeshParamStruc *params;

  /* private */
  BOOLEAN clip;             /* whether to use clipBox, above */
  REAL4 cosTheta, sinTheta; /* cosine and sine of theta, above */
} TwoDMeshPlotStruc;


/* <lalLaTeX>
\vfill{\footnotesize\input{TwoDMeshPlotHV}}
</lalLaTeX> */


/* Function prototypes. */

/* <lalLaTeX>
\newpage\input{TwoDMeshPlotC}
</lalLaTeX> */
void
LALPlotTwoDMesh( LALStatus         *stat,
                 FILE              *stream,
                 TwoDMeshNode      *mesh,
                 TwoDMeshPlotStruc *params );

/* <lalLaTeX>
\newpage\input{TwoDMeshTestC}
</lalLaTeX> */

#ifdef __cplusplus
#pragma {
}
#endif

#endif /* _TWODMESHPLOT_H */

---