@BeginModule
@NewPage
@Name      = Magplot
@Title     = Lat/Lon plot
@Section   = Magics
@Arguments = ifile ofile
@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}.
The result is written to @file{ofile}. 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
 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,
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
