
<section id='NMPlot_ContourPlots_id'
webfilename='contourplots'>
    <title>
        Contour Plots
    </title>
    <para>
        Contours are a powerful tool for visualizing a grid. Using NMPlot,
        you can easily create publication-quality contour plots.
    </para>
    <section id='NMPlot_PrimaryAndSecondaryContours_id'>
        <title>
            Primary and Secondary Contours
        </title>
        <para>
            Consider the following contour plot.
        </para>
        <exhibit>
            <img src='NMPlot_Figure_SampleContourPlot.png'/>
        </exhibit>
        <para>
            Note that this plot has two different <termtext>styles</termtext>
            of contour lines. One is thick, black, and labeled with the contour
            level. The other is thin, gray, and not labeled.
        </para>
        <para>
            Typically, contour plots are drawn using two styles of contours.
            <termtext> Primary contours</termtext> are bolder and often labeled.
            <termtext>Secondary contours</termtext> are subtler. There are
            usually several secondary contours between every adjacent pair
            of primaries. This reduces clutter, and results in a plot that
            is both informative and readable.
        </para>
        <para>
            However, there are situations where additional contour styles
            are required. An example is a plot in which each contour is filled
            with a different color.
        </para>
        <exhibit>
            <img
            src='NMPlot_Figure_SampleContourPlot_FilledWithDifferentColors.png'/>
        </exhibit>
    </section>
    <note type='tip'>
        <para>
            Use additional contour styles to highlight contour levels of specific
            interest. The following example plot uses conventional primary
            and secondary contours to show the terrain elevation near a river.
            The river's flood plain is highlighted by an additional red-filled
            contour.
        </para>
        <exhibit>
            <img
            src='NMPlot_Figure_SampleContourPlot_FloodPlainExample.png'/>
        </exhibit>
    </note>
    <section id='NMPlot_DisplayingContours_id'>
        <title>
            Displaying Contours
        </title>
        <para>
            To display contours on a plot, follow these steps.
        </para>
        <orderedlist>
            <listitem>
                <para>
                    Go to the Contours page of the <link
                    target='#NMPlot_PlotOptionsDialogBox_id'>Plot Options dialog box</link>.
                </para>
                <exhibit>
                    <img src='NMPlot_ScreenCap_PlotOptions_Contours.png'/>
                </exhibit>
            </listitem>
            <listitem>
                <para>
                    Check the box labeled <italic>Show Contours</italic>.
                </para>
            </listitem>
            <listitem>
                <para>
                    Visit the other contour pages of the Plot Options dialog box,
                    and set the options as desired.
                </para>
            </listitem>
        </orderedlist>
    </section>
    <section id='NMPlot_ContourLevels_id'>
        <title>
            Contour Levels
        </title>
        <para>
            To set the levels at which contours are drawn, follow these steps.
        </para>
        <orderedlist>
            <listitem>
                <para>
                    Go to the Levels page of the <link
                    target='#NMPlot_PlotOptionsDialogBox_id'> Plot Options dialog
                    box</link>.
                </para>
                <exhibit>
                    <img src='NMPlot_ScreenCap_PlotOptions_ContourLevels.png'/>
                </exhibit>
            </listitem>
            <listitem>
                <para>
                    Select how you would like to specify the contour levels.
                </para>
                <unorderedlist>
                    <listitem>
                        <para>
                            <italic>Automatically calculate contour levels</italic> - NMPlot
                            inspects the data values in your grid, and automatically chooses
                            an appropriate set of contour levels.
                        </para>
                        <orderedlist>
                            <listitem>
                                <para>
                                    Type the approximate number of <link
                                    target='#NMPlot_PrimaryAndSecondaryContours_id'>primary</link>
                                    contours that will be drawn. In order to select an aesthetically
                                    pleasing set of levels, NMPlot may choose to display a slightly
                                    different number of primary contours.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    Type the number of <link
                                    target='#NMPlot_PrimaryAndSecondaryContours_id'> secondary</link>
                                    contours that will be drawn between every adjacent pair of <link
                                    target='#NMPlot_PrimaryAndSecondaryContours_id'>primary</link>
                                    contours. Type zero to turn off the display of secondary contours.
                                </para>
                            </listitem>
                        </orderedlist>
                        <para>
                            The primary and secondary contours will be drawn using the <italic>Primary
                            Contours</italic> and <italic>Secondary Contours</italic> styles,
                            respectively. See <iref target='NMPlot_ContourStyles_id'/> for
                            more information.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            <italic>Manually specify contour levels</italic> - NMPlot calculates
                            the contour levels based on a set of conditions that you specify.
                        </para>
                        <orderedlist>
                            <listitem>
                                <para>
                                    Type the levels of the highest and lowest <link
                                    target='#NMPlot_PrimaryAndSecondaryContours_id'> primary</link>
                                    contours.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    Type the spacing between <link
                                    target='#NMPlot_PrimaryAndSecondaryContours_id'>primary</link>
                                    levels: i.e., the difference in levels between adjacent primary
                                    contours. For example, if you specify 50, 90, and 10 for the lowest
                                    level, highest level, and spacing, respectively, NMPlot will draw
                                    primary contours at the following levels: 50, 60, 70, 80, and
                                    90.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    Type the number of <link
                                    target='#NMPlot_PrimaryAndSecondaryContours_id'>secondary</link>
                                    contours that will be drawn between every adjacent pair of <link
                                    target='#NMPlot_PrimaryAndSecondaryContours_id'>primary</link>
                                    contours. Type zero to turn off the display of secondary contours.
                                </para>
                            </listitem>
                        </orderedlist>
                        <para>
                            The primary and secondary contours will be drawn using the <italic>Primary
                            Contours</italic> and <italic>Secondary Contours</italic> styles,
                            respectively. See <iref target='NMPlot_ContourStyles_id'/> for
                            more information.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            <italic>Manually specify each contour level</italic> - You explicitly
                            specify the level and style of every contour.
                        </para>
                        <para>
                            Enter one or more levels, and select the contour style associated
                            with each. Press the Add Row button to add another row to the
                            table. Press the Remove Row button to remove a row.
                        </para>
                        <para>
                            To associated more than one contour level with a particular style,
                            type a list of levels, separated by commas. For example, "10,
                            20, 30".
                        </para>
                        <para>
                            You can specify the levels in any order.
                        </para>
                    </listitem>
                </unorderedlist>
            </listitem>
        </orderedlist>
    </section>
    <section id='NMPlot_ContourStyles_id'>
        <title>
            Contour Styles
        </title>
        <para>
            NMPlot gives you full control over the styles (color, thickness,
            labeling, etc.) of your contours. The set the styles, follow these
            steps.
        </para>
        <orderedlist>
            <listitem>
                <para>
                    Go to the Styles page of the <link
                    target='#NMPlot_PlotOptionsDialogBox_id'>Plot Options dialog box</link>.
                </para>
                <exhibit>
                    <img src='NMPlot_ScreenCap_PlotOptions_ContourStyle.png'/>
                </exhibit>
            </listitem>
            <listitem>
                <para>
                    Contour styles are displayed using a standard spreadsheet control,
                    which functions much like a spreadsheet such as Microsoft Excel.
                    See <iref target='WCF_SpreadsheetControl_id'/> for more information
                    on using spreadsheet controls.
                </para>
                <para>
                    Press the Add Row button to add a style. Press the Remove Row
                    button to remove the style that contains the selected cell.
                </para>
                <para>
                    Press the Move Row Up and Move Row Down buttons to change the
                    order in which styles are listed. The order is irrelevant to NMPlot,
                    but you may wish to list styles in a logical order for organizational
                    purposes.
                </para>
                <note type='note'>
                    <para>
                        Two styles, named <italic>Primary Contours</italic> and <italic>Secondary
                        Contours</italic>, cannot be deleted. These styles are used for
                        the <link target='#NMPlot_PrimaryAndSecondaryContours_id'>primary</link>
                        and <link target='#NMPlot_PrimaryAndSecondaryContours_id'>secondary</link>
                        contours. See <iref target='NMPlot_ContourLevels_id'/> for more
                        information.
                    </para>
                </note>
            </listitem>
            <listitem>
                <para>
                    In the <italic>Style Name</italic> column, type a unique, descriptive
                    name for each of your styles.
                </para>
                <note type='note'>
                    <para>
                        You cannot change the names of the <italic>Primary Contours</italic>
                        and <italic>Secondary Contours</italic> styles.
                    </para>
                </note>
            </listitem>
            <listitem>
                <para>
                    In the <italic>Draw Line</italic> column, check the box to draw
                    the contour lines. Either this box or the Fill Contour box should
                    be checked: otherwise, the contours will not be visible.
                </para>
            </listitem>
            <listitem>
                <para>
                    In the <italic>Line Color</italic> column, select the color of
                    the lines used to draw your contours. See <iref
                    target='WCF_ColorControl_id'/> for information on selecting colors.
                </para>
            </listitem>
            <listitem>
                <para>
                    In the <italic>Line Width</italic> column, type the width, in
                    millimeters, of the lines used to draw your contours. Typically,
                    widths are between 0.2 to 1.0 millimeters.
                </para>
            </listitem>
            <listitem>
                <para>
                    In the <italic>Line Pattern</italic> column, select the dash pattern
                    (dashed, dotted, solid, etc.) of the lines used to draw your contours.
                    See <iref target='WCF_LinePatternControl_id'/> for information
                    on selecting line patterns.
                </para>
            </listitem>
            <listitem>
                <para>
                    In the <italic>Label</italic> column, type the text used to label
                    your contours. If you do not want the contours labeled, delete
                    the label text.
                </para>
                <para>
                    See <iref target='NMPlot_ContourLabelLocations_id'/> for information
                    on setting the locations where contours are labeled.
                </para>
                <para>
                    The label can include <termtext>symbolic fields</termtext>, placeholders
                    for text that is automatically inserted when the label is displayed.
                    For example, the field {Level} is automatically replaced with
                    the contour level.
                </para>
                <para>
                    Press the Insert Symbolic Field button <img
                    src='WCF_SymbolicFieldsTextControl_InsertFieldButton_ScreenCap.png'/>,
                    located to the right of the text box, to display a list of fields
                    from which you can choose.
                </para>
                <para>
                    Some of the fields commonly used in contour labels are:
                </para>
                <exhibit>
                    <table>
                        <tableheader>
                            <tablecolumnheader horzjust='center'>
                                Field
                            </tablecolumnheader>
                            <tablecolumnheader horzjust='left'>
                                Description
                            </tablecolumnheader>
                        </tableheader>
                        <tablerow>
                            <tablecell>
                                {Level}
                            </tablecell>
                            <tablecell>
                                Level of the contour being drawn
                            </tablecell>
                        </tablerow>
                        <tablerow>
                            <tablecell>
                                {Metric}
                            </tablecell>
                            <tablecell>
                                Metric of the grid being plotted: i.e., what is being measured
                                by the grid
                            </tablecell>
                        </tablerow>
                        <tablerow>
                            <tablecell>
                                {Units}
                            </tablecell>
                            <tablecell>
                                Physical units of the grid being plotted
                            </tablecell>
                        </tablerow>
                    </table>
                </exhibit>
                <para>
                    See <iref target='WCF_SymbolicFieldsTextControl_id'/> for more
                    information about symbolic fields.
                </para>
            </listitem>
            <listitem>
                <para>
                    In the <italic>Label Font</italic> column, select the font used
                    to draw contour labels. See <iref target='WCF_FontControl_id'/>
                    for information on selecting fonts.
                </para>
            </listitem>
            <listitem>
                <para>
                    In the <italic>Fill Contour</italic> column, check the box to
                    fill contours with a solid color. Either this box or the Draw
                    Line box should be checked: otherwise, the contours will not be
                    visible.
                </para>
            </listitem>
            <listitem>
                <para>
                    In the <italic>Fill Color</italic> column, select the color used
                    to fill your contours. See <iref target='WCF_ColorControl_id'/>
                    for information on selecting colors.
                </para>
            </listitem>
            <listitem>
                <para>
                    In the <italic>Fill Opacity</italic> column, type the percent
                    opacity of the fill color. The opacity may range from 0% (totally
                    transparent) to 100% (totally opaque). An intermediate opacity
                    will tint the contour areas with a translucent color that allows
                    a background map to show through.
                </para>
                <exhibit>
                    <img src='NMPlot_Figure_SampleTranslucentContourPlot.jpg'/>
                </exhibit>
            </listitem>
            <listitem id='NMPlot_ContourLineStyleLayerName_id'>
                <para>
                    NMPlot allows you to export a plot to a Geographic Information
                    System (GIS) in a number of common formats. Some GIS formats support
                    the concept of named layers. In the <italic>Contour Lines Layer
                    Name</italic> and <italic>Contour Labels Layer Name</italic> columns,
                    type the names of the layers that contour lines and contour labels
                    are exported in. To export to the default unnamed layer, delete
                    the layer name.
                </para>
            </listitem>
        </orderedlist>
    </section>
    <section id='NMPlot_SmoothingContours_id'>
        <title>
            Smoothing Contours
        </title>
        <para>
            If the distance between data points in a grid is relatively large,
            then a contour plot of the grid may contain sharp angles. NMPlot
            allows you to improve the appearance of these contours by smoothing
            them.
        </para>
        <exhibit>
            <img src='NMPlot_Figure_SmoothingContours.png'
            standard_colors='true'/>
        </exhibit>
        <para>
            To smooth contours, follow these steps.
        </para>
        <orderedlist>
            <listitem>
                <para>
                    Go to the Smoothing page of the <link
                    target='#NMPlot_PlotOptionsDialogBox_id'>Plot Options dialog box</link>.
                </para>
                <exhibit>
                    <img src='NMPlot_ScreenCap_PlotOptions_ContourSmoothing.png'/>
                </exhibit>
            </listitem>
            <listitem>
                <para>
                    Select the <italic>Smooth Contours</italic> radio button.
                </para>
            </listitem>
            <listitem>
                <para>
                    <italic>Tension:</italic> Type the smoothing tension. NMPlot uses
                    a smoothing method called Splines Under Tension. Intuitively,
                    you can imagine a contour as a rubber band. Without tension, the
                    rubber band curves smoothly. When pulled tight, the rubber band
                    becomes straight.
                </para>
                <para>
                    You can set the tension to any value between 0.1 and 100. A tension
                    of 1 or 2 will produce nicely smoothed contours. Smaller values
                    will make the contours more rounded. Larger values will decrease
                    the smoothing effect. Large tensions, above about 50, effectively
                    disable smoothing.
                </para>
            </listitem>
            <listitem>
                <para>
                    <italic>Maximum angle:</italic> When NMPlot draws smoothed contours,
                    what appears to be a continuous curve is actually drawn as a large
                    number of tiny straight line segments. Type the maximum angle,
                    in degrees, that is allowed between adjacent segments.
                </para>
                <para>
                    Decreasing the angle makes the contours appear smoother, but also
                    increases the time required to draw them. A value of 3 degrees
                    is a reasonable compromise: it usually results in contours that
                    appear smooth to the naked eye.
                </para>
                <para>
                    The Maximum Angle has the greatest effect on broadly curving contours.
                </para>
            </listitem>
            <listitem>
                <para>
                    <italic>Minimum segment length:</italic> When NMPlot draws smoothed
                    contours, what appears to be a continuous curve is actually drawn
                    as a large number of tiny straight line segments. Type the minimum
                    allowed length, in millimeters, of a line segment.
                </para>
                <para>
                    Decreasing this length makes the contours appear smoother, but
                    also increases the time required to draw them. A value of 1 millimeter
                    is a reasonable compromise: it usually results in contours that
                    appear smooth to the naked eye.
                </para>
                <para>
                    The Minimum Segment Length has the greatest effect on sharply
                    curving contours.
                </para>
            </listitem>
        </orderedlist>
        <note type='caution'>
            <para>
                Use care when smoothing contours. While it does improve the appearance
                of a plot, smoothing can give the impression that your grid has
                a finer resolution than it actually does. Unsmoothed contours
                will not mislead you about the accuracy of your data.
            </para>
        </note>
    </section>
    <section id='NMPlot_ContourLabelLocations_id'>
        <title>
            Contour Label Locations
        </title>
        <para>
            Use the Contour Label Locations page of the <link
            target='#NMPlot_PlotOptionsDialogBox_id'> Plot Options dialog
            box</link> to control where contour lines are labeled.
        </para>
        <exhibit>
            <img
            src='NMPlot_ScreenCap_PlotOptions_ContourLabelLocations.png'/>
        </exhibit>
        <para>
            Select the <italic>Do not label contours</italic> radio button
            to turn off contour labeling.
        </para>
        <para>
            Select the <italic>Position contour labels automatically</italic>
            radio button to turn on contour labeling. Type the distance, in
            centimeters, between adjacent labels along each contour line.
        </para>
        <para>
            See <iref target='NMPlot_ContourStyles_id'/> for information on
            setting the text used to label contours.
        </para>
    </section>
    <section id='NMPlot_ContourClipping_id'>
        <title>
            Contour Clipping
        </title>
        <para>
            Use the Contour Clipping page of the <link
            target='#NMPlot_PlotOptionsDialogBox_id'> Plot Options dialog
            box</link> to control how contours are displayed if they reach
            the edge of the grid.
        </para>
        <exhibit>
            <img src='NMPlot_ScreenCap_PlotOptions_ContourClipping.png'/>
        </exhibit>
        <para>
            Select <italic>Close contour by extending it along the edge of
            the grid</italic> if you want your contour lines to always appear
            as closed polygons. If a contour reaches the edge of the grid,
            it will follow the edge until it reaches the location where the
            contour reenters the grid.
        </para>
        <exhibit>
            <img src='NMPlot_Figure_ContourClipping_Extend.png'/>
        </exhibit>
        <para>
            Select <italic>Clip contour at the edge of the grid</italic> to
            stop contour lines at the edge of the grid. In this case, the
            contours will form isolated line segments instead of closed polygons.
        </para>
        <exhibit>
            <img src='NMPlot_Figure_ContourClipping_Clip.png'/>
        </exhibit>
        <note type='note'>
            <para>
                A grid's edge is defined by its defined area polygon: see <iref
                target='NMPlot_GridDefinedAreaPolygon_id'/>.
            </para>
        </note>
    </section>
    <section id='NMPlot_ContourTopology_id'>
        <title>
            Contour Topology
        </title>
        <para>
            Use the Contour Topology page of the <link
            target='#NMPlot_PlotOptionsDialogBox_id'> Plot Options dialog
            box</link> to control the topology of the polygons that represent
            contours.
        </para>
        <exhibit>
            <img src='NMPlot_ScreenCap_PlotOptions_ContourTopology.png'/>
        </exhibit>
        <para>
            Select <italic>Overlapping polygons</italic> to generate contour
            polygons with overlapping areas. For example, if you draw contours
            with levels of 10 and 20, the contour polygon representing level
            10 will enclose all points with a grid value above 10.
        </para>
        <para>
            Select <italic>Adjacent nested rings</italic> to generate contour
            polygons with adjacent, non-overlapping areas. For example, if
            you draw contours with levels of 10 and 20, the contour polygon
            representing level 10 will enclose all points with a grid value
            above 10 and below 20.
        </para>
        <note type='tip'>
            <para>
                Unless you have special needs, it is recommended that you select
                <italic>Overlapping polygons</italic>.
            </para>
        </note>
    </section>
    <section id='NMPlot_DisplayingContourAreas_id'>
        <title>
            Displaying Contour Areas
        </title>
        <para>
            To display the area inside each contour on a plot, choose <menutext>Display
            Contour Areas</menutext> from the <menutext>Plot</menutext> menu.
            The Contour Areas dialog box appears.
        </para>
        <exhibit>
            <img src='NMPlot_ScreenCap_ContourAreas.png'/>
        </exhibit>
        <para>
            You are warned if any contours are not completely enclosed by
            your grid's <link target='#NMPlot_GridDefinedAreaPolygon_id'>defined
            area polygon</link>. In this case, the displayed contour area
            is too low, since the area calculation does not include the portion
            of the contour beyond the edge of your grid.
        </para>
        <para>
            You can change the units used to display the areas. See <iref
            target='WCPUxWCF_ApplicationOptions_PhysicalUnits_id'/>.
        </para>
        <para>
            The current contour topology controls the meaning of a contour's
            area. See <iref target='NMPlot_ContourTopology_id'/>. If the topology
            is set to <italic>Overlapping polygons</italic>, then a contour's
            area includes all points where the grid value is greater than
            the contour's level. If the topology is set to <italic>Adjacent
            nested rings</italic>, then a contour's area includes all points
            where the grid value is greater than the contour's level but less
            than the next higher contour's level.
        </para>
    </section>
</section>
