@BeginModule
@NewPage
@Name      = Magplot
@Title     = Lat/Lon plot
@Section   = Magics
@Arguments = ifile obase
@Operators = contour shaded grfill

@BeginDescription
The operators in this module generates 2D Lon/Lat plots.
The data for the plot is read from @file{ifile}.
Only data on rectilinear Lon/Lat grids are supported.
The output file will be named <obase>_<param>.<device> where param is the parameter name and
device is the device name. The default output file format is postscript,
this can be changed with the device parameter.
The type of the plot depends on the choosen operator.

Here is a list of all common plot parameters:

@BeginTable
 @bold{Keyname}     & @bold{Type}    & @bold{Description}      
 device      & STRING  & Output device (ps, eps, pdf, png, gif, gif_animation, jpeg, svg, kml)
 projection  & STRING  & Projection (cylindrical, polar_stereographic, robinson, mercator)
 style       & STRING  & Contour line style (solid, dash, dot, chain_dash, chain_dot)
 min         & FLOAT   & Minimum value
 max         & FLOAT   & Maximum value
 lon_max     & FLOAT   & Maximum longitude of the image
 lon_min     & FLOAT   & Minimum longitude of the image
 lat_max     & FLOAT   & Maximum latitude of the image
 lat_min     & FLOAT   & Minimum latitude of the image
 count       & INTEGER & Number of Contour levels / Colour bands  
 interval    & FLOAT   & Interval in data units between two bands lines
 list        & INTEGER & List of levels to be plotted
 RGB         & STRING  & TRUE or FALSE, to  indicate, if the input colour is in RGB format
 step_freq   & INTEGER & Frequency of time steps to be considered for making the animation
             &         & (device=gif_animation). Default value is "1" (all time steps).
             &         & Will be ignored if input file has multiple variables.
 file_split  & STRING  & TRUE or FALSE, to split the output file for each variable, if input has
             &         & multiple variables. Default value is "FALSE". Valid only for "PS" format.
@EndTable
@EndDescription
@EndModule


@BeginOperator_contour
@Title     = Contour plot
@Parameter = params

@BeginDescription
The operator @bold{contour} generates the discrete contour lines of the input field values.
The following additional parameters are valid for contour operator,
module in addition to the common plot parameters:

@BeginTable
 @bold{Keyname}      & @bold{Type}    & @bold{Description}      
 colour       & STRING  & Colour for drawing the contours
 thickness    & FLOAT   & Thickness of the contour line
 style        & STRING  & Line Style can be "SOLID", "DASH", "DOT", "CHAIN_DASH",
              &         & "CHAIN_DOT"
@EndTable
@EndDescription
@EndOperator


@BeginOperator_shaded
@Title     = Shaded contour plot
@Parameter = params

@BeginDescription
The operator @bold{shaded} generates the filled contours of the given input field values.
The following additional parameters are valid for shaded contour and gridfill operator,
in addition to the common plot parameters.

@BeginTable
 @bold{Keyname}      & @bold{Type}    & @bold{Description}      
 colour_min   & STRING  & Colour for the Minimum colour band
 colour_max   & STRING  & Colour for the Minimum colour band
 colour_triad & STRING  & Direction of colour sequencing for shading "CW" or "ACW",
              &         & to denote "clockwise" and "anticlockwise" respectively.
              &         & To be used in conjunction with "colour_min", "colour_max"
              &         & options. Default is "ACW"
 colour_table & STRING  & File with user specified colours with the format as
@EndTable

Example file for 6 colours in RGB format:
@BeginListing
	6
	RGB(0.0;0.0;1.0)
	RGB(0.0;0.0;0.5)
	RGB(0.0;0.5;0.5)
	RGB(0.0;1.0;0.0)
	RGB(0.5;0.5;0.0)
	RGB(1.0;0.0;0.0)
@EndListing

@EndDescription
@EndOperator


@BeginOperator_grfill
@Title     = Shaded gridfill plot
@Parameter = params

@BeginDescription
The operator @bold{grfill} is similar to satellite imaging and shades each cell (pixel) according
to the value of the field at that cell.
@C The following additional parameters are valid for shaded gridfill
@C operator, in addition to the common plot parameters and shaded contour parameters:
@C 
@C @BeginTable
@C  @bold{Keyname}      & @bold{Type}    & @bold{Description}      
@C  resolution   & FLOAT   &  Number of cells per cm for CELL shading.
@C @EndTable
@EndDescription
@EndOperator


@BeginNote
All colour parameter can be either standard name or in RGB format.
The valid standard name strings for "colour" are:

"red", "green", "blue", "yellow", "cyan", "magenta", "black", "avocado", "beige",
"brick", "brown", "burgundy", "charcoal", "chestnut", "coral", "cream", "evergreen",
"gold", "grey", "khaki", "kellygreen", "lavender", "mustard", "navy", "ochre",
"olive", "peach", "pink", "rose", "rust", "sky", "tan", "tangerine", "turquoise",
"violet", "reddishpurple", "purplered", "purplishred", "orangishred", "redorange",
"reddishorange", "orange", "yellowishorange", "orangeyellow", "orangishyellow",
"greenishyellow", "yellowgreen", "yellowishgreen", "bluishgreen", "bluegreen",
"greenishblue", "purplishblue", "bluepurple", "bluishpurple", "purple", "white"
@EndNote


@BeginParameter
@Item = params
STRING   Comma separated list of plot parameters
@EndParameter


@BeginExample
1) Shaded contour plot of a global temperature field with a resolution of 4 degree.
The contour interval is 3 with a rainbow color table.
@BeginVerbatim
  cdo shaded,interval=3,colour_min=violet,colour_max=red,colour_triad=cw temp plot
@EndVerbatim
@IfDoc
\vspace{1mm}

\includegraphics[width=\textwidth]{magshaded.pdf}

\vspace{1mm}
@EndifDoc

2) Shaded gridfill plot of a global temperature field with a resolution of 4 degree.
The contour interval is 3 with a rainbow color table.
@BeginVerbatim
  cdo grfill,interval=3,colour_min=violet,colour_max=red,colour_triad=cw temp plot
@EndVerbatim
@IfDoc
\vspace{1mm}

\includegraphics[width=\textwidth]{maggrfill.pdf}

\vspace{1mm}
@EndifDoc
@EndExample
