AddTin

DESCRIPTION

This utility is used to aggregate multiple TINs into a single TIN. This utility
can be used to combine images temporally or spatially. The spatial combining
is useful to take two or more TINs that cover different geographic areas and
combine them into a single TIN that covers the total geographic area of the
individual TINs. Temporal combination will compute a statistic of the values
at each point for all TINs, commonly the total (e.g. for precipitation) or
average (e.g. for temperature).

Currently, the utility can combine TINs either temporally or spatially during a
single invocation but not both. To combine TINs in both time and space, the
utility would have to be executed twice.

USAGE

AddTin (-controlFile file &| -inFile fileSpec1 -inFile fileSpec2 ...) [-inPath pathSpec]
[-sTime time] [-dTime timespan] [-eTime time] [-readTimeZone timeZone]
[-instantaneousInput] [-tinInputInterval timeInterval]
[-maxTins nnn]
[-temporal | -spatial] [-mergeType mergetype] [ -union | -intersection ]
[-prjFile file] [-gridSpacing number] [-slendernessRatio ratio] [-noProject]
[-samplingMethod ( inverseDistSq | surfaceInterp )] [-nearestNeighbor [ dist ]]
[-shiftInTime timespan]
[-outputUnits units] [-title title] [-writeTimeZone timeZone]
[-?writeProvider] [-writeProviderprovider] [-writeType writeType]
-outFile fileSpec [-outPath pathSpec]
[-test] [-verbose]

OPTIONS

-controlFile file

The input file that holds a list of the input file and path specifications.
This option is always processed first. Other command line options will
override contents of this file. Use 'infile:' and 'inpath:' in file to
denote files/filemasks and DSS paths/pathmasks repsectively.
Use an * in column 1 for comments. Blank lines are ignored.

-inFile fileSpec

Multiple filespecs can be used. The filespec can be a simple filename or can
contain masks.

-inPath pathSpec

The DSS path or mask to use. Multiple paths can be specified.
If this is specified then all filesspecs that end in '.dss' are
considered to be DSS files. Any pathSpecs can use masks.

-readTimeZone timeZone

Override of the read time zone. If specified, the time zone specified
in the input file's metadata will be ignored, and replaced with the
time zone specified at the command line.

A listing of the available time zones can be found at
https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. The TZ
database name should be passed in as the argument. It's preferred to use
time zone specifications with the Canonical status if possible.

-instantaneousInput

Identifies that the input data is instantaneous. If this flag is not used,
the duration of each image is assumed to be equal to the interval. This
is only necessary when using path masking with dates. Once the files are
read, the metadata is parsed to determine if the data is instantaneous.

-tinInputInterval timeInterval

Only aggregate TINs that have the specified time interval. Refer to -dtime
option for applicable formats. Use this option to ensure that the program
adds together specific time intervals. For example, if adding together DSS paths,
use -tinInputInterval 1Hour to ensure that no daily records are included in the results.

-maxTins nnnn

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, the program can appear
to freeze as it iterates through all the possibilities.
By default this value is set at 100,000.

-temporal

Used to specify adding TINs together temporally, resulting in a single
output TIN. This is the default option if neither -spatial or -temporal
is specified.

-spatial

Used to specify combining of TINs spatially, and can result in the
output of multiple TINs, depending on the time interval of the input TINs
being processed. Using the -infile and -inpath options specified, the
program will group the TINs by time interval, then process each group
individually, and then save the resulting TIN(s) in one or more output TINs.

-mergeType mergetype

The method to use to combine image sets together. The possible values are
'aggregate', 'min', 'max', 'avg', 'avgx0'.
For spatial processing the default is avg if -mergeType not specified.
For temporal processing the default dependent on the TIN parameter (i.e.
aggregate for precipitation).
aggregate - uses the accumulated value of the TINs at any particular point for
computing the surface.
min - uses the minimum value of the TINs at any particular point.
max - uses the minimum value of the TINs at any particular point.
avg - uses the average of the TINs at any particular point for computing the surface.
avgx0 - uses the average of the TINs at any particular point for computing the
surface, but excludes measurement values of zero from the averaging.
Certain gridded datasets may have areas of the grid set to 0
instead of undefined. This is the case where this method should be used.

-union

Use the union of images when merging. This is the default option for spatial
combination if neither -union or -intersection is specified. This option
is only applicable if one or more of the images being added is a gridded
image, and -noproject is not specified.

-intersection

Use only the spatial intersection of images when merging. This is the default
option for temporal combination if neither -union or -intersection is
specified. This option is only applicable if one or more of the images
being added is a gridded image and -noproject is not specified.

-prjFile file

A file that contains a valid WKT for the desired output projection. If
undefined, the output projection will match the input.
Certain -writeProvider and -writeType combinations imply a specific
coordinate system projection, such as using a DSS provider and a write
type of HRAP or SHG, which must match with this option to be successful.
Some write providers may infer a valid projection definition, but may
still require a gridSpacing to be defined.

-gridSpacing number

Desired output grid spacing in the units defined by the output projection.
If undefined, the a default value of 0.1 will be used.

-slendernessRatio ratio

The allowable ratio of triangle width to height to use for edge triangle
elimination. This is meant to reduce the problem of long slender triangles
around the edges of the data set and may result in a TIN that is not a
convex hull. This option is ignored for gridded data.

-slendernessRatio 10 would remove any edge triangles from the TIN that
have a with to height ratio of 10 or greater.

-noProject

Specifies that when merging TINs and grids, the actual TIN points be
added together for any non-gridded TINs. This contrasts with the default
option, where at least one of the TIN datasets is a grid, the TINs are
normally projected onto a 'master' grid, similar to what happens when the
utility ProjectTinToGrid is used. Using this option prevents that projection
step from occurring. Using this option can be time consuming, and the
resultant object will be a TIN that is not a grid.

-samplingMethod (inverseDistSq | surfaceInterp)

Specifies the methodology used to sample the source TIN if projecting.
Inverse distance squared weighting (inverseDistSq) uses the source grid
cells surrounding each target grid cell to set the target grid cell value.
Surface Interpolation (surfaceInterp) computes the value of each target
grid cell by using the centerpoint location of the cell on the corresponding
source TIN triangle element.

If not specified, the default is dependant on the source TIN. If the source
TIN is a gridded dataset, the inverseDistSq option is used. If the source
TIN is an ungridded dataset, the program uses the surfaceInterp option. Both
methods give similar resultant target grids, however the inverseDistSq method
is much faster when it can be used. Legacy versions of MetVue used only the
surfaceInterp method.

Note: The program will ignore this option when processing ungridded source
TINs and use surfaceInterp for the sampling method.

-nearestNeighbor [dist]

Specified to use the 'nearest neighbor' point on the
source TIN when setting the value for the grid cell on the target TIN,
instead of using the specified sampling method. If no point is found
within range the value is determined using the -samplingMethod option.

The 'dist' portion of the argument is optional (defaults to 1.0) and
specifies the distance in target grid cells that the nearest neighbor
point must be to be used.

-nearestNeighbor would use the closest point found if the centerpoint
of the source TIN was within 1/2 cell distance of the target TIN.

-nearestNeighbor 3 would use the closest point found if the centerpoint
of the source TIN was within 1 1/2 cells distance of the target TIN.

-nearestNeighbor .5 would use the closest point found if the centerpoint
of the source TIN was within +/-1/4 cells distance of the target TIN.

-shiftInTime timespan

The amount of time to shift the image from its encoded time.
The formats are the same as for the -dTime option with the additional
specification that the timespan can be negative. e.g. -06:00:00

-outputUnits units

Measurement data units that the output file units are in. Default is to
use the same units as the input.

-title title

Used to specify a title for the output file. If none is specified, the program
will attempt to generate one from the available times, and existing title of
one input file. A title that has blanks should be enclosed in double quotes.

-writeTimeZone timeZone

Specifies the time zone for which the output data will be written. If
not specified, the output will be written in the time zone of the input data.

A listing of the available time zones can be found at
https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. The TZ
database name should be passed in as the argument. It's preferred to use
time zone specifications with the Canonical status if possible.

-?writeProvider

See Grid and TIN Writing Arguments

-writeProvider provider

See Grid and TIN Writing Arguments

-writeType writeType

See Grid and TIN Writing Arguments

-outFile fileSpec

An output filename or file mask similar to the -infile command line argument,
except that only a single filespec can be used. If adding TINs together
spatially, the filespec should be a file mask and not a file name
(unless using DSS output) to support multiple resultant TINs.
Any filespecs containing the characters * or ? should be in quotes to keep
the operating system shell from expanding them.

-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 D and E path parts of the output path
are always unique based on the start and end time, there is no need to
specify more than one output paths.

-test

Output information on filenames and paths to be read and written, but
do not aggregate or write data.

-verbose

Give detailed output of files and paths etc.

SAMPLE COMMAND LINE ARGUMENTS

Read the entries in the list, and create a single output file using temporal aggregation.
-controlFile D:\obs\listOfThings.txt -outfile "D:\obs\result.rf"

Read from a file and write results to a file:
-inFile "D:\obs\%s:ddMMMyy%.rf" -sTime 01may2008 -eTime 31may2008 -temporal
-outFile "D:\obs\%yyyy%\%MMMyyyy%.rf" -verbose

Read from a DSS file and write results to a DSS file:
-inFile D:\radar\radar.dss -inpath "/HRAP/LMRFC/PRECIP/*/*/QPE/"
-sTime "13OCT2014,000000" -etime "13OCT2014,240000" -temporal
-tinInputInterval 1hour -outfile "D:\radar\Daily.%MMMyyyy%.dss"
-outpath "/HRAP/LMRFC/PRECIP///QPE/" -verbose

Read radar data from 2 different RFCs and merge them into a spatial dataset
for each time period. Process any data for the previous 5 days
-inFile D:\radar\radar.dss -inpath "/HRAP/LMRFC/PRECIP/*/*/QPE/"
-inpath "/HRAP/WGRFC/PRECIP/*/*/QPE/" -tinInputInterval 1hour -sTime T
-eTime "T-5D" -spatial -outfile D:\radar\precipMerged.dss
-outpath "/HRAP/LM_WG_RFC/PRECIP///MERGED/" -verbose

Arguments shown in brackets are optional.

Use double quotes to enclose options that have spaces or special characters.

NOTES FOR WINDOWS USERS

Any command line arguments containing a % sign needs to be escaped in order
to work. For example The command:

-inFile "D:\obs\%s:ddMMMyy%.rf" -outFile "D:\obs\%yyyy%\%MMMyyyy%.rf" ...

becomes:

-inFile "D:\obs\%%s:ddMMMyy%%.rf" -outFile "D:\obs\%%yyyy%%\%%MMMyyyy%%.rf" ...

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 AddTin.cmd example file provided.