
<section id='WCF_CommandLineOptions_id' type='appendix'
webfilename='commandlineoptions'>
    <title>
        Command-Line Options
    </title>
    <para>
        The name of one or more grid or plot files may be specified on
        the NMPlot command line. These files will be opened when NMPlot
        runs. This allows you to associate the extensions <filetext>.nmp</filetext>
        and <filetext>.grd</filetext> with the NMPlot application, and
        invoke NMPlot by double-clicking on a plot or grid file from Microsoft
        Windows Explorer.
    </para>
    <para>
        Enclose file names containing spaces with double-quotes, as in...
    </para>
    <para>
        <commandprompt>C:\></commandprompt><commandinput>nmplot "Sample
        Grid - Airport Noise.grd"</commandinput>
    </para>
    <para>
        NMPlot recognizes the following command-line options.
    </para>
    <section>
        <title>
            Display Help
        </title>
        <section>
            <title>
                Synopsis
            </title>
            <para>
                <commandinput>-Help</commandinput>
            </para>
        </section>
        <section>
            <title>
                Description
            </title>
            <para>
                Displays the NMPlot User's Guide.
            </para>
        </section>
        <section>
            <title>
                Example
            </title>
            <para>
                <commandprompt>C:\></commandprompt><commandinput>nmplot -help</commandinput>
            </para>
        </section>
    </section>
    <section>
        <title>
            Display a Plot of a Specific Grid
        </title>
        <section>
            <title>
                Synopsis
            </title>
            <para>
                <commandinput>-LoadPlotSetGrid</commandinput><commandparam> plotfilename
                gridfilename</commandparam>
            </para>
        </section>
        <section>
            <title>
                Description
            </title>
            <para>
                Loads the plot file <commandparam>plotfilename</commandparam>,
                sets the plot's <link target='#NMPlot_PrimaryGrid_id'> primary
                grid</link> to <commandparam>gridfilename</commandparam>, saves
                the modified plot, and then displays the plot. Note that this
                operation modifies the existing plot file <commandparam>plotfilename</commandparam>.
            </para>
        </section>
        <section>
            <title>
                Example
            </title>
            <para>
                <commandprompt>C:\></commandprompt><commandinput>nmplot -loadplotsetgrid
                myplot.nmp mygrid.grd</commandinput>
            </para>
        </section>
        <section>
            <title>
                Comments
            </title>
            <para>
                This command-line option is for third-party applications that
                use NMPlot to display graphical output. As an example, consider
                how a hypothetical numerical model called X might use NMPlot.
            </para>
            <para>
                X's developers create a plot file named <filetext>X.nmp</filetext>
                that is distributed with X. This plot's options are set appropriately
                for displaying grid files created by X.
            </para>
            <para>
                When a user running X requests a contour plot, X performs the
                following actions.
            </para>
            <orderedlist>
                <listitem>
                    <para>
                        X creates a grid file named <filetext><italic>UserCase</italic>.grd</filetext>,
                        where <italic>UserCase</italic> is the name of the user's current
                        scenario in X.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        X copies <filetext>X.nmp</filetext> to <filetext><italic>UserCase</italic>.nmp</filetext>.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        X runs NMPlot using the command line:
                    </para>
                    <para>
                        <commandinput>nmplot -loadplotsetgrid "</commandinput><commandparam>UserCase</commandparam><commandinput>.nmp"
                        "</commandinput><commandparam>UserCase</commandparam><commandinput>.grd"</commandinput>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        NMPlot displays the plot. The user can use the full power of NMPlot
                        to explore X's predictions.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        The user can access the plot later by simply double-clicking on
                        <filetext><italic>UserCase</italic>.nmp</filetext>. X no longer
                        needs to be running.
                    </para>
                </listitem>
            </orderedlist>
        </section>
    </section>
    <section>
        <title>
            Export a Plot in ARC/INFO Shapefile (SHP) Format
        </title>
        <section>
            <title>
                Synopsis
            </title>
            <para>
                <commandinput>-se</commandinput><commandparam> gridfilename [coordsys
                plotfilename shapefilename]</commandparam>
            </para>
        </section>
        <section>
            <title>
                Description
            </title>
            <para>
                Exports a plot in ARC/INFO Shapefile (SHP) format. NMPlot reads
                the plot from file <commandparam>plotfilename</commandparam>,
                temporarily sets the plot's <link
                target='#NMPlot_PrimaryGrid_id'>primary grid</link> to <commandparam>gridfilename</commandparam>,
                and exports the plot to a Geographic Information System (GIS)
                in ARC/INFO Shapefile (SHP) format.
            </para>
            <para>
                <commandparam>coordsys</commandparam> controls the coordinate
                system of the Shapefile(s) that are created. If it equals "default",
                then the <link target='#NMPlot_PrimaryGrid_id'>primary grid</link>'s
                <link target='#NMPlot_GridCoordinateSystem_id'>default coordinate
                system</link> will be used. Otherwise, <commandparam>coordsys</commandparam>
                must be the name of an NMPlot coordinate system file. To create
                a coordinate system file, 1) start NMPlot, 2) choose <menutext>Export
                to GIS</menutext> from the <menutext>File</menutext> menu, 3)
                press the Properties button, 4) choose Export in the Following
                Coordinate System, 5) press the Browse button <img
                src='WCF_ThreeDotsButton_Figure.png'/> to display the <link
                target='#WCGISxWCF_CoordinateSystemControl_id'>Select Coordinate
                System dialog box</link>, 6) select the desired coordinate system,
                including the datum, and 7) press the Save To File button, then
                type the desired file name.
            </para>
            <para>
                <commandparam>plotfilename</commandparam> is used to specify the
                plot options: the contour levels, whether geographic annotations
                are exported, etc. This file is not modified.
            </para>
            <para>
                <commandparam>shapefilename</commandparam> is a model file name
                that controls the name(s) of the Shapefile(s) created. This model
                file name works exactly like the Output Filenames section of NMPlot's
                Export to GIS dialog box. See <iref
                target='WCGIS_ExportingMapsToGIS_DialogBox_id'/> for more information.
            </para>
            <para>
                The last three parameters &emdash; <commandparam>coordsys</commandparam>,
                <commandparam>plotfilename</commandparam>, and <commandparam>shapefilename</commandparam>
                &emdash; are optional. If they do not appear, then their values
                are constructed by taking <commandparam>gridfilename</commandparam>
                and changing the file extension to <filetext>.coordsys</filetext>,
                <filetext>.nmp</filetext>, and <filetext>.shp</filetext>, respectively.
            </para>
        </section>
        <section>
            <title>
                Examples
            </title>
            <para>
                <commandprompt>C:\></commandprompt><commandinput>nmplot -se mygrid.grd
                mycoordsys.coordsys myplot.nmp myoutput.shp</commandinput>
            </para>
            <para>
                <commandprompt>C:\></commandprompt><commandinput>nmplot -se mygrid.grd
                default myplot.nmp myoutput.shp</commandinput>
            </para>
            <para>
                <commandprompt>C:\></commandprompt><commandinput>nmplot -se mygrid.grd</commandinput>
            </para>
        </section>
        <section>
            <title>
                Comments
            </title>
            <para>
                This command line is intended to be used as part of a batch operation.
                NMPlot will exit after creating the Shapefile(s). See <iref
                target='WC_BatchModeErrorHandling_id'/> for a discussion of how
                errors are handled while processing this option.
            </para>
        </section>
    </section>
    <section>
        <title>
            Export a Plot in DXF Format
        </title>
        <section>
            <title>
                Synopsis
            </title>
            <para>
                <commandinput>-ExportToDXF</commandinput><commandparam> gridfilename
                plotfilename dxffilename coordsys</commandparam>
            </para>
        </section>
        <section>
            <title>
                Description
            </title>
            <para>
                Exports a plot in AutoCAD Data Exchange Format (DXF) format. NMPlot
                reads the plot from file <commandparam>plotfilename</commandparam>,
                temporarily sets the plot's <link
                target='#NMPlot_PrimaryGrid_id'>primary grid</link> to <commandparam>gridfilename</commandparam>,
                and exports the plot to a Geographic Information System (GIS)
                in DXF format.
            </para>
            <para>
                <commandparam>plotfilename</commandparam> is used to specify the
                plot options: the contour levels, whether geographic annotations
                are exported, etc. This file is not modified.
            </para>
            <para>
                <commandparam>dxffilename</commandparam> is the name of the DXF
                file that will be created.
            </para>
            <para>
                <commandparam>coordsys</commandparam> controls the coordinate
                system used for locations in the DXF file. It must be either "Default"
                for the <link target='#NMPlot_PrimaryGrid_id'>primary grid</link>'s
                <link target='#NMPlot_GridCoordinateSystem_id'>default coordinate
                system</link>, or "LongLat" for decimal degrees of east longitude
                and north latitude.
            </para>
        </section>
        <section>
            <title>
                Example
            </title>
            <para>
                <commandprompt>C:\></commandprompt><commandinput>nmplot -ExportToDXF
                mygrid.grd myplot.nmp myoutput.dxf LongLat</commandinput>
            </para>
        </section>
        <section>
            <title>
                Comments
            </title>
            <para>
                This command line is intended to be used as part of a batch operation.
                NMPlot will exit after creating the DXF file. See <iref
                target='WC_BatchModeErrorHandling_id'/> for a discussion of how
                errors are handled while processing this option.
            </para>
        </section>
    </section>
    <section>
        <title>
            Interpolate Grid Data Levels at a List of User-Supplied Points
        </title>
        <section>
            <title>
                Synopsis
            </title>
            <para>
                <commandinput>-pi</commandinput><commandparam> gridfilename [coordsys
                pointsfilename resultsfilename]</commandparam>
            </para>
        </section>
        <section>
            <title>
                Description
            </title>
            <para>
                NMPlot reads the <link
                target='#NMPlot_IntroductionToGrids_id'>grid</link> from file
                <commandparam>gridfilename</commandparam>, reads the file <commandparam>pointsfilename</commandparam>
                (a text file containing a list of point coordinates specified
                using the coordinate system denoted by the <commandparam>coordsys</commandparam>
                parameter), determines the grid data level at each point by interpolating
                into the grid, and then writes the interpolated grid data levels
                to the text file <commandparam>resultsfilename</commandparam>.
            </para>
            <para>
                <commandparam>coordsys</commandparam> controls the coordinate
                system used to specify locations in the points file. If it equals
                "default", then the <link target='#NMPlot_PrimaryGrid_id'>primary
                grid</link>'s <link target='#NMPlot_GridCoordinateSystem_id'>default
                coordinate system</link> will be used. Otherwise, <commandparam>coordsys</commandparam>
                must be the name of an NMPlot coordinate system file. To create
                a coordinate system file, 1) start NMPlot, 2) choose <menutext>Export
                to GIS</menutext> from the <menutext>File</menutext> menu, 3)
                press the Properties button, 4) choose Export in the Following
                Coordinate System, 5) press the Browse button <img
                src='WCF_ThreeDotsButton_Figure.png'/> to display the <link
                target='#WCGISxWCF_CoordinateSystemControl_id'>Select Coordinate
                System dialog box</link>, 6) select the desired coordinate system,
                including the datum, and 7) press the Save To File button, then
                type the desired file name.
            </para>
            <para>
                <commandparam>pointsfilename</commandparam> is a simple text file.
                Its lines specify the points, one per line. Each line consists
                of three fields, separated by either commas or tab characters.
                The three fields contain:
            </para>
            <orderedlist>
                <listitem>
                    <para>
                        A descriptive alphanumeric name for each point
                    </para>
                </listitem>
                <listitem>
                    <para>
                        The X coordinate of each point
                    </para>
                </listitem>
                <listitem>
                    <para>
                        The Y coordinate of each point
                    </para>
                </listitem>
            </orderedlist>
            <para>
                The meaning of the X and Y coordinates will depend on the coordinate
                system of the points. For example, if the coordinate system is
                longitude and latitude, X is the longitude and Y is the latitude.
            </para>
            <para>
                Here is an example points file.
            </para>
            [-include "NMPlot_CommandLineOptions_SamplePointsFile_Appendix.txt"-]
            <para>
                <commandparam>resultsfilename</commandparam> is a simple text
                file. Its lines specify the interpolated grid data levels for
                each point, one per line, in the same order as the points appear
                in the points file. Each line consists of two fields, separated
                by either commas or tab characters (depending on the character
                used to separate columns in the points file). The two fields contain:
            </para>
            <orderedlist>
                <listitem>
                    <para>
                        The descriptive alphanumeric name of each point
                    </para>
                </listitem>
                <listitem>
                    <para>
                        The interpolated grid data level for each point, or -9999 if the
                        point is located outside of the grid's <link
                        target='#NMPlot_GridDefinedAreaPolygon_id'>defined area polygon</link>
                    </para>
                </listitem>
            </orderedlist>
            <para>
                Here is an example results file.
            </para>
            [-include "NMPlot_CommandLineOptions_SampleResultsFile_Appendix.txt"-]
            <para>
                The last three parameters &emdash; <commandparam>coordsys</commandparam>,
                <commandparam>pointsfilename</commandparam>, and <commandparam>resultsfilename</commandparam>
                &emdash; are optional. If they do not appear, then their values
                are constructed by taking <commandparam>gridfilename</commandparam>
                and changing the file extension to <filetext>.coordsys</filetext>,
                <filetext>.pts</filetext>, and <filetext>.out</filetext>, respectively.
            </para>
        </section>
        <section>
            <title>
                Examples
            </title>
            <para>
                <commandprompt>C:\></commandprompt><commandinput>nmplot -pi mygrid.grd
                mycoordsys.coordsys mypoints.pts results.out</commandinput>
            </para>
            <para>
                <commandprompt>C:\></commandprompt><commandinput>nmplot -pi mygrid.grd
                default mypoints.pts results.out</commandinput>
            </para>
            <para>
                <commandprompt>C:\></commandprompt><commandinput>nmplot -pi mygrid.grd</commandinput>
            </para>
        </section>
        <section>
            <title>
                Comments
            </title>
            <para>
                This command line is intended to be used as part of a batch operation.
                NMPlot will exit after creating the results file. See <iref
                target='WC_BatchModeErrorHandling_id'/> for a discussion of how
                errors are handled while processing this option.
            </para>
        </section>
    </section>
    [-include "WC_BatchModeErrorHandling_Section.rxl"
        ApplicableCommandLineFlagsList=
            "<listitem><para><commandinput>-se</commandinput></para></listitem>
             <listitem><para><commandinput>-ExportToDXF</commandinput></para></listitem>
             <listitem><para><commandinput>-pi</commandinput></para></listitem>"-]
</section>
