TriangulateTin

DESCRIPTION

    This utility is used to convert georeferenced, statistical measurements to a TIN.
    Typically, this utility is used to triangulate accumulated precipitation measurements
    from at least three gage locations. 

    Each input file to be processed must contain a minimum of X, Y, and measurement
    values to create a valid TIN. It may also include a measurement name and type for
    each location.

    The location data is assumed to be in longitude and latitude, unless a projection is 
    defined at the top of the input file.

    In addition to the measurement data, the input file can contain the following
    metadata:
        sTime, eTime, dTime, label, units, parseDelimiter, parseOrder and projection
        All file settings can be overridden at the command line, except the projection.

    The general format of the file is:
    Line 1: Title for the dataset
    Line 2-n: metadata name/value pairs. e.g. units:INCH
    Line n+1-m: measurement data.

    Within the input file, lines can be commented by prepending "#" or ";".

USAGE

    TriangulateTin (-fileList file &| -inFile fileSpec -inFile fileSpec...)
                               ( [-sTimeWindow time] [-dTimeWindow timespan] [-eTimeWindow time] | [-sTime time] [-dTime timespan] [-eTime time] )
                               [-tinInputInterval timeInterval]
                               [-parseDelimiter delimiter] [-parseOrder order]
                               [-label label] [-units units]
                               -outFile fileSpec [-outPath pathSpec]
                               [-maxTins numTins] [-reverseX] [-dms]
                               [-randomize] [-slendernessRatio ratio] 
                               [-force] [-test] [-verbose] [-validate] [-check]

OPTIONS

    -fileList file

        The input file that holds a list of the input file specifications.
        This option is always processed first. Each line contained in the file
        denotes a filename or file mask to be processed. Blank lines are ignored.

    -inFile fileSpec

        Specifies the data file containing the raw data to be processed.
        Multiple fileSpecs can be used. The fileSpec can be a simple filename or can
        contain masks.

    The next three options specify the timespan to use to constrain the TIN data
    files retrieved to a specified date range. Two of the three options must be
    specified if any date mask strings are specified for the TINs.

    -sTimeWindow time

        Beginning date & time for filling in dated file masks.
        Use Time Window arguments when file searching using masked filenames.
        Time Window arguments are not compatible with the other time arguments.
        See Command Line Time Specifications for supported time formats.

    -dTimeWindow timepan

        The amount of time from either the start or end time expressed in one of 
        three time span formats as illustrated in the Command Line Time Specifications
        section. This is only used when dated file masks are specified

    -eTimeWindow time

        Ending date & time for filling in dated file masks.
        Use Time Window arguments when file searching using masked filenames.
        Time Window arguments are not compatible with the other time arguments.
        See Command Line Time Specifications for supported time formats.

   -tinInputInterval timeInterval

        This acts as a filter to further constrain the files that are processed, when
        using file masks.
        Refer to -dTimeWindow option for applicable formats.

    -sTime time

        Beginning date & time override when using a single file.
        See Command Line Time Specifications

    -dTime timespan

        The amount of time from either the start or end time expressed in one of 
        three time span formats as illustrated in the Command Line Time Specifications

    -eTime time

        Beginning date & time override when using a single file.
        See Command Line Time Specifications

    -parseDelimiter 'delimiter'

        The default delimiter is any whitespace character (i.e. single space,
        multiple space, tab). If a different delimiter is preferred, that can be
        selected with the -parseDelimiter argument.

        If the delimiter is a single character, or a single character surrounded
        by quotes, that single character will be used directly as the delimiter.
        e.g. -parseDelimiter "," to specify a comma or -parseDelimiter "|" to specify a
        pipe character.

        If the argument following the -parseDelimiter starts with 0x, the character
        is interpreted as a hex value representing the character.
        e.g. -parseDelimiter 0x0020 would be a space delimiter.

        If the argument following the -parseDelimiter has multiple characters, not
        starting with 0x, then it is assumed to be a regular expression.

        NOTE: quotes, hex values and regular expressions are only supported when
        specifying the delimiter at the command line. When specified in the
        triangulate TIN file, only a single character, without quotes, is supported.

    -parseOrder order

        Specify the order of parsing the fields within the file.
        If not specified the order will be "label,y,x,measurement,gagetype".
        Possible values for the order are label, x, y, measurement, gagetype and
        skip. Skip will skip a field in the line so that if a line resembles
        "item1,-98.5,33.4,gage1,5th and elm,5.2,quality X,4" the parseOrder would
        be "skip,x,y,label,skip,measurement,skip,gagetype".
        The fields that  x, y, and measurement are required.

    -label label

        The label is the name of the variable (i.e. precipitation, temperature, etc.)
        Default is 'Rainfall' if not specified on the command line or in the
        input file. This will override the value in the input file if it exists.

    -units units

        Specify data units. Default is 'INCHES' if not specified.
        This will override the value in the input file if it exists.
        See Unit Aliases for options.

    -outFile fileSpec

        An output filename or file mask similar to the -inFile command line argument,
        except that only a single fileSpec can be used.

    -outPath pathSpec

        The DSS path or mask to use for output. This is similar to the -inPath
        command line argument, except that only a single path or path mask can be
        specified. Since the program will automatically populate the D and E path
        parts, the need to specify a path mask instead of a simple path for output
        is rare.

LESSER USED OPTIONS

    -maxTins numTins

        Specify the maximum number of TINs that can be processed during the
        invocation of the command. All the possible variations of the command
        options may result in an unintentionally large set of TINs to be processed.
        For example, if an erroneous time span was entered, an excessive number
        of TINs may be processed. When this occurs the program can appear to
        freeze as it iterates through all the possibilities.
        By default this value is set as 100,000.

    -reverseX

        multiply all x coordinates by -1 so that 95.56 becomes -95.56.
        This is to support legacy formatted files where the longitudes were
        positive values, but assumed to be in the western hemisphere.

    -dms

        If the units in the file are longitude/latitude, process them as
        degrees, minutes and seconds instead of decimal degrees. A valid
        DMS format would resemble -1053030 whereas a valid decimal degrees
        format for the same value would be -105.5083

    -randomize

        Randomizes or 'shuffles' the data points. Triangulation performs more
        efficiently with randomly ordered data. When using ordered data (i.e.
        gridded data), randomizing the points makes the triangulation more
        efficient. Note that this routine is not optimal for processing
        row/column type data.

    -slendernessRatio ratio

        Specifies the ratio of long to short triangle side lengths that defines a
        'slender' triangle. Slender triangles that exist on the perimeter of the
        dataset will be removed if they meet this criteria. A typical value would
        be ~4 or greater, but must be greater than 1 to be meaningful. Normally
        triangulated datasets have a convex hull. If this ratio is specified it
        is likely that the resultant dataset is non-convex, and may even result
        in multiple disconnected groups of TIN points.

    -force

        Forces the program to ignore many errors and process the file. Normally
        when the program encounters more than 10 errors, it will quit processing.
        This is to preclude the processing of files that were not meant to be
        processed by this program. An example of where to use this option would
        be in the case of a file that had comments interspersed in the file that
        did not use the standard # and ; column 1 comment characters.

    -test

        Output information on filenames and paths to be read and written but
        do not process the files.

    -verbose

        Give detailed output of files and paths etc.

    -validate

        Checks grid consistency after the TIN is created.

    -check

        Warns about duplicate locations and duplicate point labels.

SAMPLE COMMAND LINE ARGUMENTS:

    Triangulate TIN and write to DSS
        -inFile C:\\gagedata.txt -outFile C:\\results.dss -outPath /a/b/PRECIP///f/

    Triangulate TIN with different order
        -inFile C:\\gagedata.txt -parseOrder Label,X,Y,Measurement,GageType
        -outFile C:\\results.dss -outPath /a/b/PRECIP///f/

    Triangulate TIN with different parse delimiter
        -inFile C:\\gagedata.txt -parseDelimiter ,
        -outFile C:\\results.dss -outPath /a/b/PRECIP///f/

GAGE TYPE NOTE

The gageType in input files is used to define the symbol type MetVue
    uses when displaying the gage as a point value.
        Possible values are:
        1 - Triangle
        2 - Square
        3 - Diamond
        4 - Inverted triangle
        5 - Circle
        Any other value - 'X'

NOTE ON PERFORMANCE

   This program may utilize a significant amount of memory depending on datasets specified.
   For extra intensive data operations, it may be necessary to increase the memory allocated
   to the jvm. This can be performed by setting the -Xmx argument, which can be altered
   easily in the "memory_setting" variable in the TriangulateTin.cmd example file provided.